> ## Documentation Index
> Fetch the complete documentation index at: https://docs.twenty.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 接口

> 使用 REST 或 GraphQL 以编程方式查询和修改您的客户关系管理数据。

export const VimeoEmbed = ({videoId, title = 'Video'}) => <div style={{
  padding: '69.01% 0 0 0',
  position: 'relative',
  margin: '32px 0px',
  borderRadius: '16px',
  overflow: 'hidden',
  border: '2px solid black'
}}>
    <iframe src={`https://player.vimeo.com/video/${videoId}?autoplay=1&loop=1&autopause=0&background=1&app_id=58479`} frameBorder="0" allow="autoplay; fullscreen; picture-in-picture; clipboard-write" style={{
  position: 'absolute',
  top: 0,
  left: 0,
  width: '100%',
  height: '100%',
  transform: 'scale(1.1)'
}} title={title} />
  </div>;

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

## 开发者优先的方法

Twenty 会针对您的数据模型生成专用 API：

* **无需长ID**：直接在终端使用对象和字段名称
* **标准与自定义对象平等对待**：您的自定义对象将获得与内置对象相同的API处理
* **专用终端**：每个对象和字段都有自己的API终端
* **自定义文档**：专门为您的工作区的数据模型生成

<Note>
  创建 API 密钥后，可在 **设置 → API & Webhooks** 中查看您的个性化 API 文档。 由于 Twenty 会生成与您的自定义数据模型相匹配的 API，因此文档对您的工作区是唯一的。
</Note>

## 两种 API 类型

### 核心API

访问路径：`/rest/`或`/graphql/`。

处理您实际的**记录**（数据）：

* 创建、读取、更新、删除 People、Companies、Opportunities 等。
* 查询并筛选数据
* 管理记录关系

### 元数据API

访问路径：`/rest/metadata/`或`/metadata/`。

管理您的**工作区和数据模型**：

* 创建、修改或删除对象和字段
* 配置工作区设置
* 定义对象之间的关系

## REST 与 GraphQL

Core 和 Metadata API 均提供 REST 和 GraphQL 格式：

| 格式          | 可用操作                            |
| ----------- | ------------------------------- |
| **REST**    | CRUD、批量操作、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. **立即复制** — 密钥仅显示一次

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

<Warning>
  您的 API 密钥可访问敏感数据。 不要与不受信任的服务共享它。 如果遭到泄露，请立即将其禁用并生成一个新的。
</Warning>

### 为 API 密钥分配角色

为提高安全性，请分配特定角色以限制访问：

1. 转到 **设置 → 成员 → 角色**
2. 点击要分配的角色
3. 打开 **分配** 选项卡
4. 在 **API Keys** 下，点击 **+ Assign to API key**
5. 选择该 API 密钥

该密钥将继承该角色的权限。 详见 [权限](/l/zh/user-guide/permissions-access/capabilities/permissions)。

### 管理 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 条记录 |

<Tip>
  使用批量操作以最大化吞吐量 — 在一次 API 调用中处理最多 60 条记录，而不是发起单独的请求。
</Tip>