从 v1/v2 迁移

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

有哪些变化

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

步骤 1：创建服务用户

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

前往 Settings > Devin API，打开 服务用户 选项卡
点击 Provision 服务用户 并分配合适的角色
复制预配完成后显示的 API key (以 cog_ 开头)
更新你的集成以使用新的 API key

# 之前（旧版 API key）
curl -H "Authorization: Bearer apk_user_YOUR_LEGACY_KEY" ...

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

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

步骤 2：更新端点 URL

会话端点

操作	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}`

Knowledge 端点

操作	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}`

Playbook 端点

操作	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}`

机密信息端点

操作	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}`

仅限 Enterprise 的端点 (新)

这些端点在 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 使用上限等

步骤 3：更新分页方式

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

# 之前（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"

详细信息请参见分页。

第 4 步：处理响应格式变化

会话状态值

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

错误响应

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

弃用时间线

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

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

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

需要帮助？

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

快速开始

核心概念

Agent 生命周期

上下文管理

环境管理

自动化

集成

分析

可观测性

Devin for Security

基础架构

身份与访问控制

配置

旧版 API v1

旧版 API v2

有哪些变化

步骤 1：创建服务用户

步骤 2：更新端点 URL

会话端点

Knowledge 端点

Playbook 端点

机密信息端点

仅限 Enterprise 的端点 (新)

第 4 步：处理响应格式变化

会话状态值

错误响应

弃用时间线

需要帮助？

​有哪些变化

​步骤 1：创建服务用户

​步骤 2：更新端点 URL

​会话端点

​Knowledge 端点

​Playbook 端点

​机密信息端点

​仅限 Enterprise 的端点 (新)

​步骤 3：更新分页方式

​第 4 步：处理响应格式变化

​会话状态值

​错误响应

​弃用时间线

​需要帮助？

有哪些变化

步骤 1：创建服务用户

步骤 2：更新端点 URL

会话端点

Knowledge 端点

Playbook 端点

机密信息端点

仅限 Enterprise 的端点 (新)

步骤 3：更新分页方式

第 4 步：处理响应格式变化

会话状态值

错误响应

弃用时间线

需要帮助？