APIs

import { VimeoEmbed } from '/snippets/vimeo-embed.mdx';

Twenty was built to be developer-friendly, offering powerful APIs that adapt to your custom data model. We provide four distinct API types to meet different integration needs.

Developer-First Approach

Twenty generates APIs specifically for your data model:

• No long IDs required: Use your object and field names directly in endpoints
• Standard and custom objects treated equally: Your custom objects get the same API treatment as built-in ones
• Dedicated endpoints: Each object and field gets its own API endpoint
• Custom documentation: Generated specifically for your workspace's data model

The Two API Types

Core API

Accessed on /rest/ or /graphql/

Work with your actual records (the data):

• Create, read, update, delete People, Companies, Opportunities, etc.
• Query and filter data
• Manage record relationships

Metadata API

Accessed on /rest/metadata/ or /metadata/

Manage your workspace and data model:

• Create, modify, or delete objects and fields
• Configure workspace settings
• Define relationships between objects

REST vs GraphQL

Both Core and Metadata APIs are available in REST and GraphQL formats:

Choose based on your needs — both formats access the same data.

API Endpoints

Authentication

Every API request requires an API key in the header:

Authorization: Bearer YOUR_API_KEY

Create an API Key

1. Go to Settings → APIs & Webhooks
2. Click + Create key
3. Configure:
   • Name: Descriptive name for the key
   • Expiration Date: When the key expires
4. Click Save
5. Copy immediately — the key is only shown once

Assign a Role to an API Key

For better security, assign a specific role to limit access:

1. Go to Settings → Roles
2. Click on the role to assign
3. Open the Assignment tab
4. Under API Keys, click + Assign to API key
5. Select the API key

The key will inherit that role's permissions. See Permissions for details.

Manage API Keys

Regenerate: Settings → APIs & Webhooks → Click key → Regenerate

Delete: Settings → APIs & Webhooks → Click key → Delete

API Playground

Test your APIs directly in the browser with our built-in playground — available for both REST and GraphQL.

Access the Playground

1. Go to Settings → APIs & Webhooks
2. Create an API key (required)
3. Click on REST API or GraphQL API to open the playground

What You Get

• Interactive documentation: Generated for your specific data model
• Live testing: Execute real API calls against your workspace
• Schema explorer: Browse available objects, fields, and relationships
• Request builder: Construct queries with autocomplete

The playground reflects your custom objects and fields, so documentation is always accurate for your workspace.

Batch Operations

Both REST and GraphQL support batch operations:

• Batch size: Up to 60 records per request
• Operations: Create, update, delete multiple records

GraphQL-only features:

• Batch Upsert: Create or update in one call
• Use plural object names (e.g., CreateCompanies instead of CreateCompany)

Rate Limits

API requests are throttled to ensure platform stability: