> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devin.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API 发布说明

> 跟踪 Devin API 的变更、新功能和改进

本页用于跟踪 Devin 的 API (v1、v2 和 v3) 的相关变更。应用功能发布说明请参见 [应用发布说明](/zh/release-notes/overview)。

<div id="2026">
  ## 2026
</div>

<Update label="2026 年 6 月">
  **v3 API 更新**

  * **向 IP 访问列表端点添加 IP**：新增 `POST /v3/enterprise/ip-access-list`，用于向 Enterprise IP 访问列表追加 IP 范围，而不替换现有条目。与 `PUT /v3/enterprise/ip-access-list` (会替换整个列表) 不同，此端点会将提供的范围与当前列表合并。需要 `ManageEnterpriseSettings` 权限。

  * **更新 Git 权限端点**：新增 `PATCH /v3/enterprise/organizations/{org_id}/git-providers/permissions/{git_permission_id}`，用于更新现有的 Git 权限 (例如切换 `read_only`)。需要 `ManageGitIntegrations` 权限。

  * **组织作用域成员读取端点 (Beta)**：新增 `GET /v3beta1/organizations/{org_id}/members/users`、`GET /v3beta1/organizations/{org_id}/members/users/{user_id}` 和 `GET /v3beta1/organizations/{org_id}/members/idp-users`，用于通过组织作用域的服务用户列出和获取组织成员。支持基于游标的分页 (`after`, `first`) 和按 `email` 过滤。需要在组织级别具有 `ViewOrgMembership` 权限。

  * **用于创建会话的 Devin Lite mode**：`POST /v3/organizations/{org_id}/sessions` 上的 `devin_mode` 参数现在除 `"normal"` 和 `"fast"` 外，也接受 `"lite"` (Devin Lite)。Fast 和 Lite 受与 Web 应用相同的功能标志和 Enterprise Agent 预览限制约束。
</Update>

<Update label="2026 年 5 月">
  **v3 API 更新**

  * **用于创建会话的 Devin mode 参数 (5 月 21 日)**：在 `POST /v3/organizations/{org_id}/sessions` 中新增 `devin_mode` 参数。可接受 `"normal"` (默认 Agent mode) 或 `"fast"` (Fast mode) 。省略该参数时，会话将使用组织的默认 mode。Fast mode 受与 Web 应用相同的功能标志和 Enterprise Agent 预览限制约束。

  * **Git 连接代码仓库端点 (5 月 18 日)**：新增 `GET /v3/enterprise/git-providers/connections/{connection_id}/repositories`，用于列出特定 Enterprise Git 连接可用的代码仓库。支持 `filter_name` 过滤和基于游标的分页 (`after`, `first`)。需要 `ManageGitIntegrations` 权限。
</Update>

<Update label="2026 年 3 月">
  **v3 API 更新**

  * **会话洞察生成端点 (3 月 11 日) **：新增 `POST /v3/organizations/{org_id}/sessions/{devin_id}/insights/generate` 和 `POST /v3/enterprise/sessions/{devin_id}/insights/generate` 端点，用于按需触发会话洞察生成。开始生成时返回 `{ "status": "started" }`；如果洞察已生成或正在生成中，则返回 `{ "status": "already_exists" }`。请轮询现有的 GET 洞察端点以获取结果。需要 `ManageOrgSessions` 权限。
</Update>

<Update label="2026 年 2 月">
  **v3 API 更新**

  * **v3 端点已提升为生产环境**：以下端点组已从 `v3beta1` 提升到 `v3` (生产环境) 。请将这些端点的基础 URL 从 `/v3beta1/` 更新为 `/v3/`：

    * 会话 (创建、列表、GET、消息、归档、终止、标签、洞察) ——适用于 Enterprise 和组织范围
    * Knowledge 笔记——适用于 Enterprise 和组织范围
    * Playbooks——适用于 Enterprise 和组织范围
    * Secrets——组织范围
    * Schedules——组织范围
    * Attachments——组织范围
    * 审计日志——适用于 Enterprise 和组织范围
    * 消耗与计费 (周期、每日明细、ACU 限额) ——Enterprise 范围
    * 指标 (DAU、WAU、MAU、PR、会话、搜索、活跃用户、使用情况) ——Enterprise 范围
    * 组织、用户、成员、角色、IDP 分组——Enterprise 范围
    * Git 连接和权限——Enterprise 范围
    * Hypervisors、队列、IP 访问列表、组织组限制——Enterprise 范围
    * 会话标签 (组织默认标签) ——Enterprise 范围

    **仍为 Beta** (`v3beta1`) ：代码库索引端点、服务用户开通端点以及 guardrail 违规端点仍然在 `v3beta1`，并在文档中标记为 Beta 标签。

  * **Guardrail 违规端点**：新增 `GET /v3beta1/enterprise/guardrail-violations` 和 `GET /v3beta1/enterprise/organizations/{org_id}/guardrail-violations` 端点，用于在整个 Enterprise 范围内查询 guardrail 违规记录。返回的违规详情包括 guardrail 类型、原因说明、置信度分数、采取的动作以及触发的消息。支持按 `session_id` 和 `guardrail_id` 过滤，并支持时间范围和基于游标的分页。按组织过滤时请使用按组织划分的端点。需要 `ManageEnterpriseSettings` 权限。

  * **IP 访问列表端点 (2 月 9 日) **：新增用于管理 Enterprise 级 IP 允许列表的端点：`GET /v3beta1/enterprise/ip-access-list`, `PUT /v3beta1/enterprise/ip-access-list` 和 `DELETE /v3beta1/enterprise/ip-access-list`。`PUT` 端点会用提供的 IP 段 (支持 CIDR 表示法) 整体替换当前列表。需要 `ManageEnterpriseSettings` 权限。

  * **预定会话端点 (2 月 3 日) **：新增组织级日程管理端点：`POST /v3beta1/organizations/{org_id}/schedules` 用于创建日程，`GET /v3beta1/organizations/{org_id}/schedules` 用于列出日程，`GET /v3beta1/organizations/{org_id}/schedules/{schedule_id}` 用于获取特定日程，`PATCH /v3beta1/organizations/{org_id}/schedules/{schedule_id}` 用于更新日程，以及 `DELETE /v3beta1/organizations/{org_id}/schedules/{schedule_id}` 用于删除日程。需要 `ManageOrgSchedules` 权限。
</Update>

<Update label="2026 年 1 月">
  **v3 API 更新**

  * **ACU 限额端点 (1 月 27 日) **：新增企业级 ACU 限额管理端点，适用于 Devin 会话：`GET /v3beta1/enterprise/consumption/acu-limits/devin` 用于获取限额，`PUT .../organizations/{org_id}` 用于设置组织级限额，`DELETE` 用于删除限额。需要 `ManageBilling` 权限。

  * **附件端点 (1 月 27 日) **：新增组织级附件端点：`POST /v3beta1/organizations/{org_id}/attachments` 用于上传附件，`GET /v3beta1/organizations/{org_id}/attachments/{uuid}/{name}` 用于下载附件。上传操作需要 `UseDevinSessions` 权限，下载操作需要 `ViewOrgSessions` 权限。

  * **队列端点 (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`。
</Update>

<div id="2025">
  ## 2025
</div>

<Update label="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 日) **：为高级会话工作流程新增请求参数：`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 的审计日志端点。
</Update>

<Update label="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 日) **：新增端点，用于以编程方式终止正在运行的会话。
</Update>

<Update label="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 的功能。
</Update>

<Update label="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。
</Update>

<Update label="2025 年 3 月">
  **v2 Enterprise API 发布**

  * **API v2 发布 (3 月 23 日) **：为 Enterprise 管理员发布 Enterprise API v2，提供组织管理、使用量跟踪和成员管理能力。
</Update>

<div id="2024">
  ## 2024 年
</div>

<Update label="2024 年 10 月">
  **v1 API 发布 (10 月 26 日) **

  * 推出用于以编程方式创建和管理会话的 REST API
  * 用于会话创建、监控和管理的端点
  * 支持文件附件上传和下载
  * 使用 API keys 进行基本身份验证
  * 支持幂等的会话创建
  * 使用场景：自动化拉取请求 (PR) 审查、lint 错误修复、迁移
</Update>

***

<div id="api-versioning-policy">
  ## API 版本管理策略
</div>

<div id="backward-compatibility">
  ### 向后兼容性
</div>

我们尽力在同一主版本内保持向后兼容性。不向后兼容的变更将会：

1. 至少提前 7 天进行公告
2. 记录在本发行说明中
3. 在适用情况下提供迁移指南

<div id="deprecation-process">
  ### 弃用流程
</div>

当我们弃用某个 API 功能时：

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

<div id="version-support">
  ### 版本支持
</div>

* **v1**: 旧版 — 即将弃用，将由 Organization API (v3) 取代
* **v2**: 旧版 — 即将弃用，将由 Enterprise API (v3) 取代
* **v3**: 已正式发布，推荐用于所有新的集成

***

<div id="migrating-to-the-current-api">
  ## 迁移到当前 API
</div>

如需从 v1 或 v2 迁移的分步说明，请参阅[迁移指南](/zh/api-reference/getting-started/migration-guide)。

<div id="support">
  ## 支持
</div>

如果你对 API 变更有疑问或需要迁移协助，请发送电子邮件至 [support@cognition.ai](mailto:support@cognition.ai)。