跳转到主要内容
本指南将帮助你将现有集成从 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/sessionsPOST /v3/organizations/sessions
列出会话GET /v1/sessionsGET /v3/organizations/sessions
获取会话GET /v1/session/{session_id}GET /v3/organizations/sessions/{devin_id}
发送消息POST /v1/session/{session_id}/messagePOST /v3/organizations/sessions/{devin_id}/messages
归档会话—POST /v3/organizations/sessions/{devin_id}/archive
删除会话—DELETE /v3/organizations/sessions/{devin_id}

​
Knowledge 端点

Operation（操作）v1 端点当前端点
列出 KnowledgeGET /v1/knowledgeGET /v3/organizations/knowledge/notes
创建 KnowledgePOST /v1/knowledgePOST /v3/organizations/knowledge/notes
更新 KnowledgePUT /v1/knowledge/{note_id}PUT /v3/organizations/knowledge/notes/{note_id}
删除 KnowledgeDELETE /v1/knowledge/{note_id}DELETE /v3/organizations/knowledge/notes/{note_id}

​
Playbook 端点

操作v1/v2 端点当前端点
列出 PlaybookGET /v1/playbooksGET /v3/organizations/playbooks
创建 PlaybookPOST /v1/playbooksPOST /v3/organizations/playbooks
获取 PlaybookGET /v1/playbooks/{playbook_id}GET /v3/organizations/playbooks/{playbook_id}
更新 PlaybookPUT /v1/playbooks/{playbook_id}PUT /v3/organizations/playbooks/{playbook_id}
删除 PlaybookDELETE /v1/playbooks/{playbook_id}DELETE /v3/organizations/playbooks/{playbook_id}

​
机密信息端点

操作v1 端点当前端点
列出机密信息GET /v1/secretsGET /v3/organizations/secrets
创建机密信息POST /v1/secretsPOST /v3/organizations/secrets
删除机密信息DELETE /v1/secrets/{secret_id}DELETE /v3/organizations/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/sessions?first=25"
# 然后使用响应中的 `end_cursor` 获取下一页：
curl "https://api.devin.ai/v3/organizations/sessions?first=25&after=CURSOR_VALUE"
详细信息请参见分页。

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

​
会话状态值

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

​
错误响应

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

​
弃用时间线

旧版 API key 会在 Devin 设置界面中显示弃用提示横幅。在过渡期间：
  • 当前：旧版 API key 仍然可用。新创建的组织可能无法创建旧版密钥。
  • 弃用阶段：旧版密钥与服务用户令牌将并行使用。
  • 终止阶段：旧版 API key 将在不久后移除。请在 Devin 设置中留意相关公告。
我们建议尽快迁移为使用服务用户，以利用基于角色的访问控制、会话归因以及新增功能。

​
需要帮助？

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