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

# 从 v1/v2 迁移

> 将你的集成从 API v1 或 v2 迁移到当前 API

本指南将帮助你将现有集成从 API v1 或 v2 迁移到当前的 Organization 和 Enterprise API。旧版 API (v1 和 v2) 将在弃用过渡期内继续可用，但所有新功能仅在当前 API 中提供。

<div id="whats-changing">
  ## 有哪些变化
</div>

| 项目         | v1/v2 (旧版)                          | 当前 API                                   |
| ---------- | ----------------------------------- | ---------------------------------------- |
| **身份验证**   | API key (以 `apk_user_` 或 `apk_` 开头) | 服务用户令牌 (以 `cog_` 开头)                     |
| **基础 URL** | `/v1/*`、`/v2/*`                     | `/v3/organizations/*`、`/v3/enterprise/*` |
| **分页方式**   | 基于偏移量 (`offset` + `limit`)          | 基于游标 (`first` + `after`)                 |
| **作用域**    | 扁平——所有端点都在同一层级                      | 组织范围和企业级范围                               |
| **权限**     | Key 级别 (全有或全无)                      | 基于角色的细粒度权限                               |

<div id="step-1-create-a-service-user">
  ## 步骤 1：创建服务用户
</div>

将原有 API key 替换为服务用户：

1. 前往 **Settings > Service users**
2. 创建一个具有合适角色的服务用户
3. 生成一个 API key (以 `cog_` 开头)
4. 更新你的集成以使用新的 API key

```bash theme={null}
# 之前（旧版 API key）
curl -H "Authorization: Bearer apk_user_YOUR_LEGACY_KEY" ...

# 之后（服务用户令牌）
curl -H "Authorization: Bearer cog_YOUR_SERVICE_USER_KEY" ...
```

<Note>
  在弃用过渡期内，你的旧版 API key 将继续有效。你可以分阶段逐步完成迁移。
</Note>

<div id="step-2-update-endpoint-urls">
  ## 步骤 2：更新端点 URL
</div>

<div id="session-endpoints">
  ### 会话端点
</div>

| 操作   | v1 端点                                   | 当前端点                                                           |
| ---- | --------------------------------------- | -------------------------------------------------------------- |
| 创建会话 | `POST /v1/sessions`                     | `POST /v3/organizations/{org_id}/sessions`                     |
| 列出会话 | `GET /v1/sessions`                      | `GET /v3/organizations/{org_id}/sessions`                      |
| 获取会话 | `GET /v1/session/{session_id}`          | `GET /v3/organizations/{org_id}/sessions/{devin_id}`           |
| 发送消息 | `POST /v1/session/{session_id}/message` | `POST /v3/organizations/{org_id}/sessions/{devin_id}/messages` |
| 归档会话 | —                                       | `POST /v3/organizations/{org_id}/sessions/{devin_id}/archive`  |
| 删除会话 | —                                       | `DELETE /v3/organizations/{org_id}/sessions/{devin_id}`        |

<div id="knowledge-endpoints">
  ### Knowledge 端点
</div>

| 操作           | v1 端点                            | 当前端点                                                          |
| ------------ | -------------------------------- | ------------------------------------------------------------- |
| 列出 Knowledge | `GET /v1/knowledge`              | `GET /v3/organizations/{org_id}/knowledge/notes`              |
| 创建 Knowledge | `POST /v1/knowledge`             | `POST /v3/organizations/{org_id}/knowledge/notes`             |
| 更新 Knowledge | `PUT /v1/knowledge/{note_id}`    | `PUT /v3/organizations/{org_id}/knowledge/notes/{note_id}`    |
| 删除 Knowledge | `DELETE /v1/knowledge/{note_id}` | `DELETE /v3/organizations/{org_id}/knowledge/notes/{note_id}` |

<div id="playbook-endpoints">
  ### Playbook 端点
</div>

| 操作          | v1/v2 端点                             | 当前端点                                                        |
| ----------- | ------------------------------------ | ----------------------------------------------------------- |
| 列出 Playbook | `GET /v1/playbooks`                  | `GET /v3/organizations/{org_id}/playbooks`                  |
| 创建 Playbook | `POST /v1/playbooks`                 | `POST /v3/organizations/{org_id}/playbooks`                 |
| 获取 Playbook | `GET /v1/playbooks/{playbook_id}`    | `GET /v3/organizations/{org_id}/playbooks/{playbook_id}`    |
| 更新 Playbook | `PUT /v1/playbooks/{playbook_id}`    | `PUT /v3/organizations/{org_id}/playbooks/{playbook_id}`    |
| 删除 Playbook | `DELETE /v1/playbooks/{playbook_id}` | `DELETE /v3/organizations/{org_id}/playbooks/{playbook_id}` |

<div id="secret-endpoints">
  ### 机密信息端点
</div>

| 操作     | v1 端点                            | 当前端点                                                    |
| ------ | -------------------------------- | ------------------------------------------------------- |
| 列出机密信息 | `GET /v1/secrets`                | `GET /v3/organizations/{org_id}/secrets`                |
| 创建机密信息 | `POST /v1/secrets`               | `POST /v3/organizations/{org_id}/secrets`               |
| 删除机密信息 | `DELETE /v1/secrets/{secret_id}` | `DELETE /v3/organizations/{org_id}/secrets/{secret_id}` |

<div id="enterprise-only-endpoints-new">
  ### 仅限 Enterprise 的端点 (新)
</div>

这些端点在 v1/v2 中没有对应接口——仅在当前 API 中可用：

* `GET /v3/enterprise/organizations` — 列出组织
* `GET /v3/enterprise/audit-logs` — 审计日志
* `GET /v3/enterprise/consumption/*` — 使用和计费数据
* `GET /v3/enterprise/metrics/*` — 使用量指标
* `GET /v3/enterprise/members/users` — 用户管理
* `GET /v3/enterprise/roles` — 角色管理
* 服务用户预配、IP 访问控制列表、ACU 使用上限等

<div id="step-3-update-pagination">
  ## 步骤 3：更新分页方式
</div>

当前 API 采用游标分页，而不是偏移量分页：

```bash theme={null}
# 之前（v1/v2 基于偏移量）
curl "https://api.devin.ai/v1/sessions?offset=0&limit=25"

# 之后（基于游标）
curl "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/sessions?first=25"
# 然后使用响应中的 `end_cursor` 获取下一页：
curl "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/sessions?first=25&after=CURSOR_VALUE"
```

详细信息请参见[分页](/zh/api-reference/concepts/pagination)。

<div id="step-4-handle-response-format-changes">
  ## 第 4 步：处理响应格式变化
</div>

<div id="session-status-values">
  ### 会话状态值
</div>

当前 API 会返回更细粒度的状态信息。完整的模式定义请参见端点参考文档。

<div id="error-responses">
  ### 错误响应
</div>

错误信息格式保持一致：HTTP 状态码 + 包含错误详情的 JSON 响应体。

<div id="deprecation-timeline">
  ## 弃用时间线
</div>

旧版 API key 会在 Devin 设置界面中显示弃用提示横幅。在过渡期间：

* **当前**：旧版 API key 仍然可用。新创建的组织可能无法创建旧版密钥。
* **弃用阶段**：旧版密钥与服务用户令牌将并行使用。
* **终止阶段**：旧版 API key 将在不久后移除。请在 Devin 设置中留意相关公告。

我们建议尽快迁移为使用服务用户，以利用基于角色的访问控制、会话归因以及新增功能。

<div id="need-help">
  ## 需要帮助？
</div>

如果在迁移过程中遇到问题，请通过您常用的 Devin 支持渠道与我们联系，或发送邮件至 [support@cognition.ai](mailto:support@cognition.ai)。