跳转到主要内容
本指南将帮助你将现有集成从 API v1 或 v2 迁移到当前的组织和企业 API。旧版 API (v1 和 v2) 将在弃用过渡期内继续可用,但所有新功能仅在当前 API 中提供。

有哪些变化

步骤 1:创建服务用户

将原有 API 密钥替换为服务用户:
  1. 前往 Settings > Devin API,打开 服务用户 选项卡
  2. 点击 Provision 服务用户,分配合适的角色,并选择过期时间 (默认为 30 天)
  3. 复制预配完成后显示的 API 密钥 (以 cog_ 开头)
  4. 更新你的集成以使用新的 API 密钥
在弃用过渡期内,你的旧版 API 密钥将继续有效。你可以分阶段逐步完成迁移。

步骤 2:更新端点 URL

会话端点

Knowledge 端点

Playbook 端点

/playbooks 端点在所有 API 版本中均已弃用。操作手册正在迁移到技能。请在 Customize 页面以技能形式创建新的指示。对于 2026 年 10 月 24 日或之后创建、且没有任何 playbook 的账户,调用这些端点将返回 410。详见操作手册正在迁移到技能。

机密信息端点

仅限 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 采用游标分页,而不是偏移量分页:
详细信息请参见分页。

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

会话状态值

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

错误响应

当前 API 以 RFC 9457 格式返回错误,内容类型为 application/problem+json。响应体包含 type、title 和 status 成员,还可能包含 detail、instance、errors 和 error_code 成员。 旧版 API 返回的 JSON 响应体包含一个 detail 成员。在当前 API 的 422 响应中,detail 为字符串,字段级错误则包含在 errors 成员中。

弃用时间线

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

需要帮助?

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