跳转到主要内容
本页用于跟踪 Devin 的 API（v1、v2 和 v3）的相关变更。应用功能发布说明请参见 应用发布说明。

​
2026

​
2026 年 1 月
v3 API 更新
  • 队列端点（1 月 21 日）：新增 GET /v3beta1/enterprise/queue 端点，供企业管理员监控会话队列运行状况。返回排队会话总数以及状态指示符（normal、elevated 或 high）。可用于针对容量问题设置告警。需要 ViewAccountMetrics 权限。
  • 会话端点（1 月 19 日）：新增 GET /v3beta1/enterprise/sessions/{devin_id} 和 GET /v3beta1/organizations/{org_id}/sessions/{devin_id} 端点，用于获取指定会话的详细信息。新增 POST /v3beta1/enterprise/sessions/{devin_id}/messages 和 POST /v3beta1/organizations/{org_id}/sessions/{devin_id}/messages 端点，用于向活动会话发送消息（如果会话处于挂起状态，将自动恢复）。同时在会话列表端点中新增 origins 筛选参数，用于根据会话来源进行过滤（webapp、slack、teams、api、linear、jira、other）。
  • 审计日志排序参数（1 月 17 日）：为 Enterprise 和组织审计日志端点新增 order 查询参数（asc 或 desc，默认为 desc），用于控制结果的排序顺序。
  • Secrets 路由（1 月 16 日）：新增组织级机密管理端点：GET /v3beta1/organizations/{org_id}/secrets 用于列出机密，POST /v3beta1/organizations/{org_id}/secrets 用于创建机密，DELETE /v3beta1/organizations/{org_id}/secrets/{secret_id} 用于删除机密。需要 ManageOrgSecrets 权限。
  • 审计日志修复（1 月 15 日）：已修复当页面上存在记录时，审计日志 API 响应中未返回 end_cursor 的问题。
  • 服务用户开通（1 月 14 日）：新增 POST /v3beta1/enterprise/service-users 和 POST /v3beta1/organizations/{org_id}/service-users 端点，用于以编程方式开通新的服务用户。强制防止权限提升：目标角色的权限必须是调用方权限的子集，且绝不能授予 ManageServiceUsers 权限。分别需要具备 ManageAccountServiceUsers 或 ManageOrgServiceUsers 权限。
  • IDP 组企业级端点（1 月 14 日）：新增 GET /v3beta1/enterprise/idp-groups 端点，用于列出在 Enterprise 中注册的 IDP 组，POST /v3beta1/enterprise/idp-groups 用于批量注册 IDP 组（一次最多 100 个），以及 DELETE /v3beta1/enterprise/idp-groups/{idp_group_name} 用于移除已注册的 IDP 组。已有角色分配或包含用户成员的组无法删除。需要 ManageAccountMembership 权限。
  • 审计日志操作（1 月 12 日）：在审计日志响应中新增 create_join_request、automatic_join_event 和 reject_join_request 操作类型。
  • Active users endpoint（1 月 8 日）：新增 GET /v3beta1/enterprise/metrics/active-users 端点，用于在自定义日期范围内获取去重后的活跃用户数。不同于返回按周期拆分列表的 DAU/WAU/MAU 端点，此端点会返回整个指定时间范围内唯一活跃用户的总数。支持按组织 ID 过滤，并支持可配置的活跃度阈值（min_sessions、min_searches）。
  • 虚拟机管理程序默认状态（1 月 8 日）：GET /v3beta1/enterprise/hypervisors 端点现在默认按 available 状态过滤，只返回可用的虚拟机管理程序，而不再返回所有虚拟机管理程序。传入 status=all 参数即可在不考虑状态的情况下获取所有虚拟机管理程序。
  • 会话机密（1 月 5 日）：在会话创建端点（POST /v3beta1/organizations/{org_id}/sessions）中新增 session_secrets 参数。会话机密是在当前会话中可用的临时机密，不会存储到组织机密中。
  • 分页修复（1 月 5 日）：修复了 v3 企业用户 API 中的分页问题，该问题会导致 end_cursor 有时无法正确返回。
v2 API 更新
  • 代码仓库克隆问题修复（1 月 20 日）：已修复 POST /v2/enterprise/organizations/{org_id}/clone-repository 端点的 schema 定义。移除了旧版的 RepoSetupStepsT 格式，并将请求体简化为使用扁平字段（pull_repo_commands、run_lint_commands、run_project_commands、update_dependencies_commands、repo_note、repo_path）。
  • Git 权限 URL 字段（1 月 15 日）：在 GitPermissionRequest schema 中添加了 group_prefix_url 和 repo_url 字段，提供基于完整 URL 的仓库和组前缀匹配方式，作为基于路径匹配的替代方案。
  • 组织成员角色字段（1 月 8 日）：在 GET /v2/enterprise/organizations/{org_id}/members 响应中新增 org_role_name 字段，用于显示每个成员在该组织内的角色。
  • 组织创建选项（1 月 8 日）：在 POST /v2/enterprise/organizations 中新增名为 add_creator_as_member 的布尔参数（默认为 true），允许企业版管理员在创建组织时无需自动将自己添加为成员。
  • 用量时区文档（1 月 7 日）：在每日用量端点中补充了时区行为说明。计费周期以太平洋标准时间（PST）午夜（对应 08:00:00 UTC）作为日期边界。
v1 API 更新
  • 密钥类型更新（1 月 16 日）：在 secrets API 架构中新增 dictionary 作为受支持的密钥类型值。注意：创建类型为 dictionary 的密钥已弃用；请改用 cookie、key-value 或 totp。

​
2025

​
2025 年 12 月
v3 API 更新
  • 组织分组限额端点（12 月 23 日）：新增 GET /v3beta1/enterprise/org-group-limits 和 PUT /v3beta1/enterprise/org-group-limits 端点，用于管理组织分组的配置。分组用于将一组组织 ID 映射到每个计费周期可选的最大 Agent Compute Unit 限额。需要 ManageOrganizations 权限。此功能需要由您的客户团队为您启用。
  • 会话归档端点（12 月 11 日）：新增 POST /v3beta1/organizations/{org_id}/sessions/{devin_id}/archive 端点用于归档会话。同时在 DELETE /v3beta1/organizations/{org_id}/sessions/{devin_id}（终止会话）中新增 archive 查询参数，并在会话响应中新增 is_archived 字段。
  • Order 参数移除（12 月 11 日）：**不兼容变更：**从会话列表端点（GET /v3beta1/organizations/{org_id}/sessions）中移除了 order 查询参数。客户端必须停止发送 order；请改用基于游标的分页方式，使用 first/after 参数。
  • Searches 路由（12 月 10 日）：在 GET /v3beta1/enterprise/searches 和 GET /v3beta1/organizations/{org_id}/searches 新增 Enterprise 和组织级别的搜索端点，用于列出搜索记录，并支持分页和过滤。
  • 审计日志改进（12 月 10 日）：在审计日志响应中新增 data 对象、service_user_name 和 user_email 字段。新增 update_git_permission 动作类型。
  • 高级会话支持（12 月 8 日）：新增对高级会话模式（analyze、create、improve、batch、manage）的支持，并新增请求参数：advanced_mode、child_playbook_id、session_links 和 bypass_approval。会话响应现在包含 child_session_ids、parent_session_id 和 is_advanced 字段。
  • Session Tags 路由（12 月 5 日）：在 /v3/beta/enterprise/organizations/{org_id}/tags 添加了 CRUD 端点，用于按组织管理允许的会话标签。当启用标签验证时，会话创建和标签更新将强制使用允许列表中的标签。
  • Enterprise Sessions 端点（12 月 5 日）：新增 GET /v3/beta/enterprise/sessions，用于在整个 Enterprise 范围内列出会话，并支持可选的 org_ids 过滤。
  • Git Permissions 更新（12 月 5 日）：新增用于按路径前缀匹配代码仓库的 prefix_path 字段。新增 PUT 和 DELETE 端点，用于批量替换或清空某个组织的全部权限。
  • 会话模拟（Session impersonation，12 月 5 日）：在会话创建端点中新增 create_as_user_id 参数，允许服务用户以其他用户身份创建会话。
  • Hypervisors 响应变更（12 月 5 日）：Hypervisors 端点的响应现在返回 utilization_percentage，不再返回 max_slots 和 available_slots。
  • Notes 和 Playbooks 路由（12 月 1 日）：在 v3 API 中新增 Enterprise 和组织级别的 Notes 与 Playbooks 管理端点。Notes 端点需要 ManageAccountKnowledge 权限，Playbooks 端点需要 ManageAccountPlaybooks 权限。
v2 API 更新
  • 组织分组限额端点（12 月 23 日）：新增 GET /v2/enterprise/org-group-limits 和 PUT /v2/enterprise/org-group-limits 端点，用于管理组织分组的配置。分组用于将一组组织 ID 映射到每个计费周期可选的最大 Agent Compute Unit 限额。PUT 端点会替换整个配置（未在请求中包含的分组将被删除）。此功能需要由您的客户团队为您启用。
  • Self 端点（12 月 23 日）：新增 GET /v2/enterprise/self 端点，返回已认证 API key 的相关信息，包括 key ID、关联的用户 ID、用户邮箱以及组织 ID。
  • Sessions messages 字段（12 月 11 日）：在 v2 sessions API 响应中新增 messages 字段，提供与 v1 API 类似的全部会话消息。
  • 响应 schema 改进（12 月 11 日）：为审计日志、快照和 Playbooks 端点新增规范的响应 schema，包括 AuditLogsResponse、EnterpriseSnapshotResponse 和 EnterprisePlaybookResponse。
v1 API 更新
  • 审计日志弃用（12 月 5 日）：/v1/audit-logs 端点已弃用；请改用 v2 或 v3 的审计日志端点。
​
2025 年 11 月
v2 Enterprise API 更新
  • 分页 limit 调整（11 月 21 日）：为提升性能和可靠性，将最大分页上限从每次请求 1000 条减少到 200 条。默认上限仍为 100。此变更不影响 v1 External API。
  • Sessions 路由（11 月 16 日）：在 v2 API 中为 Enterprise 管理员新增了完整的会话管理端点。
  • Snapshots API 端点（11 月 3 日）：新增用于以编程方式获取快照详情的端点。
v1 API 更新
  • 终止会话端点（10 月 31 日）：新增端点，用于以编程方式终止正在运行的会话。
​
2025 年 10 月
v3 API 发布（Beta）
  • API v3 发布（10 月 23 日）：发布 v3 API，提供完整的 RBAC 支持、服务用户认证模型，以及针对服务用户操作的全面审计日志记录。
v2 Enterprise API 更新
  • 快照创建端点（10 月 30 日）：新增 v2 Enterprise Organizations API 端点，供 Enterprise 管理员以编程方式克隆代码仓库并创建快照，支持自定义设置步骤和启动命令。
  • Playbooks API 改进（10 月 14 日）：新增用于发布 Enterprise Playbooks 的 API，并改进了以编程方式管理 Playbooks 的功能。
​
2025 年 9 月
v2 Enterprise API 更新
  • Roles 路由（9 月 25 日）：新增 Enterprise 角色路由，提供五个 API 端点，用于以编程方式管理角色。
v1 API 更新
  • Playbooks API（9 月 6 日）：在 v1 中新增完整的 Playbooks API 端点，用于以编程方式创建、更新、列出和删除 Playbooks。
  • Secrets 端点（9 月 5 日）：新增 POST /v1/secrets 端点，用于通过 API 创建 Secrets。
​
2025 年 3 月
v2 Enterprise API 发布
  • API v2 发布（3 月 23 日）：为 Enterprise 管理员发布 Enterprise API v2，提供组织管理、使用量跟踪和成员管理能力。

​
2024 年

​
2024 年 10 月
v1 API 发布（10 月 26 日）
  • 推出用于以编程方式创建和管理会话的 REST API
  • 用于会话创建、监控和管理的端点
  • 支持文件附件上传和下载
  • 使用 API keys 进行基本身份验证
  • 支持幂等的会话创建
  • 使用场景：自动化拉取请求（PR）审查、lint 错误修复、迁移

​
API 版本管理策略

​
向后兼容性

我们尽力在同一主版本内保持向后兼容性。不向后兼容的变更将会：
  1. 至少提前 7 天进行公告
  2. 记录在本发行说明中
  3. 在适用情况下提供迁移指南

​
弃用流程

当我们弃用某个 API 功能时：
  1. 公告：我们会发布弃用公告并给出时间表
  2. 弃用期：该功能在被标记为已弃用的情况下仍然可用
  3. 移除：在弃用期结束后，该功能会被移除

​
版本支持

  • v1：正式可用，持续维护
  • v2：正式可用，持续维护
  • v3：测试版 - 功能可能变更，目前不建议用于生产环境

​
迁移指南

​
从 v1 迁移到 v3

如果你正在构建需要细粒度权限控制的新集成，建议使用 v3 而不是 v1： 主要差异：
  • 认证：v3 需要使用服务用户 Token，而不是个人/服务 API key
  • 授权：v3 提供完整的 RBAC（基于角色的访问控制）权限模型
  • 端点（Endpoints）：v3 使用不同的 URL 模式（/v3beta1/* 而不是 /v1/*）
迁移步骤：
  1. 在 Enterprise Settings > Service Users 中创建一个服务用户
  2. 为该服务用户分配合适的角色
  3. 为该服务用户生成一个 API key
  4. 将你的集成更新为使用 v3 端点
  5. 在非生产环境中进行充分测试
查看 v3 API 文档 →

​
从 v2 迁移到 v3

与 v2 相比，v3 为企业自动化提供了更高的灵活性： 主要差异：
  • 认证（Authentication）：v3 使用服务账号，而不再要求 Enterprise Admin 的个人密钥
  • 授权（Authorization）：v3 支持细粒度 RBAC（基于角色的访问控制），而不再仅限企业管理员访问
  • 作用范围（Scope）：v3 可以限定到特定组织，而 v2 始终作用于整个企业
何时迁移：
  • 你需要在非管理员权限下进行自动化
  • 你希望将 API 访问范围限定到特定组织
  • 你需要在人类账号与服务账号之间有清晰的隔离
  • 你需要为自动化操作提供详细的审计日志

​
支持

如果您对 API 变更有疑问或需要迁移方面的协助：