跳转到主要内容
Twenty 的设计对开发者友好，提供适合您定制数据模型的强大API。 我们提供四种不同的API类型来满足不同的集成需求。

​
开发者优先的方法

Twenty 会针对您的数据模型生成专用 API：
  • 无需长ID：直接在终端使用对象和字段名称
  • 标准与自定义对象平等对待：您的自定义对象将获得与内置对象相同的API处理
  • 专用终端：每个对象和字段都有自己的API终端
  • 自定义文档：专门为您的工作区的数据模型生成
创建 API 密钥后，可在 设置 → API & Webhooks 中查看您的个性化 API 文档。 由于 Twenty 会生成与您的自定义数据模型相匹配的 API，因此文档对您的工作区是唯一的。

​
两种 API 类型

​
核心API

访问路径：/rest/或/graphql/。 处理您实际的记录（数据）：
  • 创建、读取、更新、删除 People、Companies、Opportunities 等。
  • 查询并筛选数据
  • 管理记录关系

​
元数据API

访问路径：/rest/metadata/或/metadata/。 管理您的工作区和数据模型：
  • 创建、修改或删除对象和字段
  • 配置工作区设置
  • 定义对象之间的关系

​
REST 与 GraphQL

Core 和 Metadata API 均提供 REST 和 GraphQL 格式：
格式可用操作
RESTCRUD、批量操作、Upsert
GraphQL同上 + 批量 Upsert，在一次调用中进行关系查询
可根据需要选择 — 两种格式访问的是同一份数据。

​
API端点

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

​
身份验证

每个 API 请求都需要在请求头中包含 API 密钥： 
Authorization: Bearer YOUR_API_KEY

​
创建 API 密钥

  1. 前往 设置 → APIs & Webhooks
  2. 点击 + 创建密钥
  3. 配置:
    • 名称：密钥的描述性名称
    • 到期日期：密钥的到期时间
  4. 单击 保存
  5. 立即复制 — 密钥仅显示一次
您的 API 密钥可访问敏感数据。 不要与不受信任的服务共享它。 如果遭到泄露，请立即将其禁用并生成一个新的。

​
为 API 密钥分配角色

为提高安全性，请分配特定角色以限制访问：
  1. 进入 设置 → 角色
  2. 点击要分配的角色
  3. 打开 分配 选项卡
  4. 在 API Keys 下，点击 + Assign to API key
  5. 选择该 API 密钥
该密钥将继承该角色的权限。 详见 权限。

​
管理 API 密钥

Regenerate: 设置 → APIs & Webhooks → 点击密钥 → Regenerate Delete: 设置 → APIs & Webhooks → 点击密钥 → Delete

​
API 操作台

使用我们内置的操作台，可直接在浏览器中测试您的 API — 同时支持 REST 和 GraphQL。

​
访问操作台

  1. 前往 设置 → APIs & Webhooks
  2. 创建 API 密钥（必需）
  3. 点击 REST API 或 GraphQL API 打开操作台

​
您将获得

  • 交互式文档：针对您的特定数据模型生成
  • 实时测试：对您的工作区执行真实的 API 调用
  • 架构浏览器：浏览可用的对象、字段和关系
  • 请求构建器：使用自动补全构建查询
操作台会反映您的自定义对象和字段，因此文档始终与您的工作区保持一致且准确。

​
批量操作

REST 和 GraphQL 均支持批量操作：
  • 批量大小：每个请求最多60条记录
  • 操作：创建、更新、删除多条记录
仅 GraphQL 功能：
  • 批量 Upsert：在一次调用中创建或更新
  • 使用复数对象名称（例如，用 CreateCompanies 而不是 CreateCompany）

​
速率限制

为确保平台稳定性，API 请求将受到限流：
限制值
请求每分钟 100 次调用
批量大小每次调用 60 条记录
使用批量操作以最大化吞吐量 — 在一次 API 调用中处理最多 60 条记录，而不是发起单独的请求。