通过 API 触发例程

Claude Code 是 Anthropic 的智能体编码工具。网页版 Claude Code 在 Anthropic 托管的云基础设施上（位于 claude.ai/code）运行 Claude Code 会话，而 "routine"（例程）是保存在那里的一种配置：一个提示、一个或多个代码仓库以及连接器，打包在一起，使其可以按计划、响应 GitHub 事件或在通过 HTTP 调用时无人值守地运行。详见 routine。

此端点是 HTTP 入口点。向其发送 POST 请求会启动现有例程的一次新运行，并返回生成的会话 ID 和 URL。典型的调用方包括告警系统、CI 流水线以及需要以编程方式启动 Claude Code 会话的内部工具。

调用此端点需要一个订阅 Pro、Max、Team 或 Enterprise 计划并已启用网页版 Claude Code 的 claude.ai 账户。请使用在 Claude Code 网页界面中创建的每例程专属 bearer 令牌进行身份验证，而不是使用 Claude API 密钥。

与 Claude Platform 的区别

例程触发端点属于 Claude Code 产品层面，它与 Claude Platform 的 API 和 SDK 在以下几个方面有所不同：

开始之前

要调用此端点，您需要：

1. 在 claude.ai/code/routines 创建的一个例程。
2. 为该例程生成的 bearer 令牌：打开例程进行编辑，在 Select a trigger 下点击 Add another trigger，选择 API，然后在模态窗口中点击 Generate token。该令牌仅显示一次，之后无法再次获取。

完整的设置流程请参阅 Claude Code 文档中的添加 API 触发器。

触发例程

POST https://api.anthropic.com/v1/claude_code/routines/{routine_id}/fire

当您添加 API 触发器时，Claude Code 网页界面会在提供令牌的同时提供完整的 URL，因此大多数集成会将两者都存储为密钥并直接调用该端点。以下示例展示了一个 shell 调用，以及一个在 CI 失败时触发例程的 GitHub Actions 步骤。

curl -X POST https://api.anthropic.com/v1/claude_code/routines/$ROUTINE_ID/fire \
  -H "Authorization: Bearer $ROUTINE_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{"text": "Sentry alert SEN-4521 fired in prod. Stack trace attached."}'

- if: failure()
  env:
    ROUTINE_FIRE_URL: ${{ secrets.ROUTINE_FIRE_URL }}
    ROUTINE_FIRE_TOKEN: ${{ secrets.ROUTINE_FIRE_TOKEN }}
  run: |
    curl -X POST "$ROUTINE_FIRE_URL" \
      -H "Authorization: Bearer $ROUTINE_FIRE_TOKEN" \
      -H "anthropic-version: 2023-06-01" \
      -H "Content-Type: application/json" \
      -d "{\"text\": \"CI failed: $GITHUB_WORKFLOW run $GITHUB_RUN_ID on $GITHUB_REF\"}"

请求在会话创建后即返回。它不会流式传输会话输出，也不会等待会话完成。

标头

发送 anthropic-beta: experimental-cc-routine-2026-04-01 标头的旧版集成不受影响：无论是否包含该标头，端点都会接受请求。

路径参数

请求体

请求体是可选的。请求体中的未知字段将被忽略。

响应

成功的请求返回 200 OK 以及新会话的详细信息：

{
  "type": "routine_fire",
  "claude_code_session_id": "session_01HJKLMNOPQRSTUVWXYZ",
  "claude_code_session_url": "https://claude.ai/code/session_01HJKLMNOPQRSTUVWXYZ"
}

错误

错误使用标准的 Anthropic 错误封装格式：

{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "<string>"
  }
}

身份验证

bearer 令牌的作用域限定为单个例程。泄露的令牌只能触发该例程；它不授予任何读取权限，不能访问其他例程，也不能访问账户数据。

请在 claude.ai/code/routines 的例程 API 触发器设置中生成和撤销令牌。没有用于令牌管理的公开 API。生成新令牌会撤销之前的令牌。

幂等性

每个成功的请求都会创建一个新会话。没有幂等性键。如果 webhook 调用方进行重试，该端点会创建多个会话。

速率限制

API 触发按小时限制：每个例程每小时最多接受 30 次触发（API 触发、网页界面中的 Run now 按钮以及一次性重新启用共用这一上限），每个账户在所有例程中每小时最多可进行 100 次 API 触发。由此产生的会话与交互式会话消耗相同的 Claude Code 订阅用量。达到限制时，端点会返回 429 rate_limit_error 以及 Retry-After 标头。

要了解例程用量如何与订阅限制和额外用量计费相互作用，请参阅 Claude Code 文档中的用量和限制。

SDK 支持

此端点未包含在 Anthropic SDK 中。其令牌模型与 API 密钥身份验证不同，并且 CI 作业和告警 webhook 等典型调用方会直接发送请求。

另请参阅

• Claude Code 文档中的使用例程自动化工作
• 错误