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

---
title: 接口
icon: plug
description: 由你的工作区架构生成的 REST 和 GraphQL API。
---

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

## 租户级架构 API

Twenty 没有静态 API 参考文档。 每个工作区都有自己的架构——当你添加一个自定义对象（例如 `Invoice`）时，它会立即获得与内置对象（如 `Company` 或 `Person`）相同的 REST 和 GraphQL 端点。 API 根据架构生成，因此端点会直接使用你的对象和字段名称——没有不透明的 ID。

创建 API 密钥后，可在 **设置 → API & Webhooks** 中查看你的工作区专属 API 文档。 其中包含交互式 Playground，可对你的数据执行真实调用。

## 两种 API

**核心 API** — `/rest/` 和 `/graphql/`

对记录执行 CRUD：人员、公司、商机，以及你的自定义对象。 查询、筛选、遍历关系。

**元数据 API** — `/rest/metadata/` 和 `/metadata/`

架构管理：创建/修改/删除对象、字段和关系。 这是以编程方式更改数据模型的方法。

两者均提供 REST 和 GraphQL。 GraphQL 还提供批量 upsert，以及在单个查询中遍历关系的能力。 无论哪种方式，底层数据相同。

## 基础 URL

| 环境  | 基础 URL                    |
| --- | ------------------------- |
| 云端  | `https://api.twenty.com/` |
| 自托管 | `https://{your-domain}/`  |

## 身份验证

```
Authorization: Bearer YOUR_API_KEY
```

在 **Settings → API & Webhooks → + Create key** 中创建 API 密钥。 请立即复制——仅显示一次。 可在 **Settings → Members → Roles → Assignment 选项卡** 下将密钥限定到特定角色，以限制其可访问的范围。

<VimeoEmbed videoId="928786722" title="创建 API 密钥" />

对于基于 OAuth 的访问（外部应用代表用户执行操作），请参见 [OAuth](/l/zh/developers/extend/oauth)。

## 批量操作

REST 和 GraphQL 均支持每个请求最多批量处理 60 条记录——创建、更新或删除。 GraphQL 还支持批量 upsert（一次调用即可创建或更新），使用诸如 `CreateCompanies` 之类的复数名称。

## 速率限制

| 限制   | 值           |
| ---- | ----------- |
| 请求   | 每分钟 100 次请求 |
| 批量大小 | 每次调用 60 条记录 |