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

# API 概览

> 了解如何使用我们的 REST API 以编程方式与 Devin 交互

Devin API 允许你将 Devin 集成到你的应用程序中、实现工作流自动化，并构建强大的工具。使用 **service users** (服务用户) 配合基于角色的访问控制，实现安全且可审计的 API 访问。

<div id="getting-started">
  ## 入门
</div>

<CardGroup cols={2}>
  <Card title="Teams 快速入门" icon="rocket" href="/zh/api-reference/getting-started/teams-quickstart">
    适用于团队和标准组织。创建服务用户，在几分钟内完成首次 API 调用。
  </Card>

  <Card title="Enterprise 快速入门" icon="building" href="/zh/api-reference/getting-started/enterprise-quickstart">
    适用于使用 RBAC、多组织支持和高级权限的 Enterprise 客户。
  </Card>
</CardGroup>

<Tip>
  **我应该选择哪种方式？** 大多数客户应从 Teams 快速入门开始。如果你管理多个组织、使用 SSO (单点登录) ，或需要自定义角色和 RBAC，请选择 Enterprise。
</Tip>

<div id="api-structure">
  ## API 结构
</div>

API 分为两个作用域：

<div id="organization-api">
  ### Organization API
</div>

**基础 URL：** `https://api.devin.ai/v3/organizations/*`

用于管理单个组织内的资源，如 sessions、Knowledge、playbooks、secrets 等。大多数集成都从这里开始。

<div id="enterprise-api">
  ### Enterprise API
</div>

**基本 URL：** `https://api.devin.ai/v3/enterprise/*`

用于跨组织管理，包括分析、审计日志、用户管理、计费和基础设施。仅向企业客户提供。

这两个 scope 都使用服务用户凭据 (`cog_` 前缀) 。有关配置，请参见 [Authentication](/zh/api-reference/authentication)。

<div id="session-attribution">
  ## 会话归因
</div>

服务用户与人类用户是不同的身份，但你可以使用 `create_as_user_id` 参数**代表组织中的任何用户创建会话**。这意味着这些会话会出现在该用户的会话列表中，并计入该用户的使用量——就像由他们自己创建的一样。

```bash theme={null}
curl -X POST "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/sessions" \
  -H "Authorization: Bearer $DEVIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Fix the login bug in issue #42",
    "create_as_user_id": "user_abc123"
  }'
```

<Tip>
  **从个人 API key 迁移过来？** 在 v1/v2 中，个人 API key 会自动以你的用户身份创建会话。使用 v3 时，改用服务用户 (service user) 加上 `create_as_user_id` 即可实现相同行为——并额外获得 RBAC、审计日志以及集中化密钥管理等优势。服务用户的角色必须包含 `ImpersonateOrgSessions` 权限。
</Tip>

<Note>
  **Personal Access Tokens (PATs) 即将推出。** PAT 将允许你在 v3 API 中直接以自己的用户身份进行认证——不再需要服务用户或 `create_as_user_id`。会话会自动归属到你名下。请关注上线时间。
</Note>

你可以通过 [List users](/zh/api-reference/v3/users/organizations-members-users) 端点，或在 Devin UI 的组织成员设置中找到用户 ID。

<div id="legacy-apis-v1-and-v2">
  ## 旧版 API (v1 和 v2)
</div>

在弃用过渡期间，v1 和 v2 API 将继续可用，但不会再获得新功能。我们建议迁移到当前版本的 API，以获得基于角色的访问控制、会话归因以及新的功能能力。

* [v1 API 文档](/zh/api-reference/v1/overview) — 使用旧版 API key 的会话管理
* [v2 API 文档](/zh/api-reference/v2/overview) — 使用旧版 API key 的企业管理
* [迁移指南](/zh/api-reference/getting-started/migration-guide) — 从 v1/v2 的逐步迁移

***

<div id="error-handling">
  ## 错误处理
</div>

所有 API 均使用标准 HTTP 状态码：

* `200 OK`: 请求成功
* `201 Created`: 资源创建成功
* `400 Bad Request`: 请求参数无效
* `401 Unauthorized`: 缺少或无效的 API key
* `403 Forbidden`: 权限不足
* `404 Not Found`: 未找到资源
* `429 Too Many Requests`: 超出请求频率限制
* `500 Internal Server Error`: 服务器内部错误

<div id="support">
  ## 支持
</div>

如有关于 API 的疑问或需要报告问题，请发送电子邮件至 [support@cognition.ai](mailto:support@cognition.ai)。