---
title: 接口
description: 使用 REST 或 GraphQL 以编程方式查询和修改您的客户关系管理数据。
---

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

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

核心 API 和元数据 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>