从 v1/v2 迁移

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

本指南将帮助你将现有集成从 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 替换为服务用户：

1. 前往 Settings > Service users
2. 创建一个具有合适角色的服务用户
3. 生成一个 API key (以 cog_ 开头)
4. 更新你的集成以使用新的 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 支持渠道与我们联系，或发送邮件至 [e-mail]。