upstream-twenty/packages/twenty-docs/developers/extend/api.mdx

---
title: APIs
icon: "plug"
description: REST and GraphQL APIs generated from your workspace schema.
---

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

## Schema-per-tenant APIs

There is no static API reference for Twenty. Each workspace has its own schema — when you add a custom object (say `Invoice`), it immediately gets REST and GraphQL endpoints identical to built-in objects like `Company` or `Person`. The API is generated from the schema, so endpoints use your object and field names directly — no opaque IDs.

Your workspace-specific API documentation is available under **Settings → API & Webhooks** after creating an API key. It includes an interactive playground where you can execute real calls against your data.

## Two APIs

**Core API** — `/rest/` and `/graphql/`

CRUD on records: People, Companies, Opportunities, your custom objects. Query, filter, traverse relations.

**Metadata API** — `/rest/metadata/` and `/metadata/`

Schema management: create/modify/delete objects, fields, and relations. This is how you programmatically change your data model.

Both are available as REST and GraphQL. GraphQL adds batch upserts and the ability to traverse relations in a single query. Same underlying data either way.

## Base URLs

| Environment | Base URL |
|-------------|----------|
| Cloud | `https://api.twenty.com/` |
| Self-Hosted | `https://{your-domain}/` |

## Authentication

```
Authorization: Bearer YOUR_API_KEY
```

Create an API key in **Settings → API & Webhooks → + Create key**. Copy it immediately — it's shown once. Keys can be scoped to a specific role under **Settings → Members → Roles → Assignment tab** to limit what they can access.

<VimeoEmbed videoId="928786722" title="Creating API key" />

For OAuth-based access (external apps acting on behalf of users), see [OAuth](/developers/extend/oauth).

## Batch operations

Both REST and GraphQL support batching up to 60 records per request — create, update, or delete. GraphQL also supports batch upsert (create-or-update in one call) using plural names like `CreateCompanies`.

## Rate limits

| Limit | Value |
|-------|-------|
| Requests | 100 per minute |
| Batch size | 60 records per call |