通过 API 触发例程

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

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

调用此端点需要拥有 Pro、Max、Team 或 Enterprise 套餐的 claude.ai 账户，并已启用 Claude Code on the web。请使用在 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

每个请求都必须包含 anthropic-beta: experimental-cc-routine-2026-04-01 标头。不包含该标头的请求将返回 400 invalid_request_error。

当您添加 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 "anthropic-beta: experimental-cc-routine-2026-04-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 "anthropic-beta: experimental-cc-routine-2026-04-01" \
      -H "Content-Type: application/json" \
      -d "{\"text\": \"CI failed: $GITHUB_WORKFLOW run $GITHUB_RUN_ID on $GITHUB_REF\"}"

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



标头



路径参数



请求体

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



响应

成功的请求会返回 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 调用方进行重试，该端点会创建多个会话。



速率限制

例程运行会计入每个账户的每日配额，该配额因套餐而异，并且生成的会话会消耗与交互式会话相同的 Claude Code 订阅用量。当达到任一限制时，端点会返回 429 rate_limit_error 并附带 Retry-After 标头。启用了额外用量的组织在超出包含的配额后会以按量计费的超额方式继续使用。

您剩余的每日运行次数显示在 claude.ai/code/routines。有关例程用量如何与订阅限制和额外用量计费交互的信息，请参阅 Claude Code 文档中的用量和限制。



SDK 支持

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



另请参阅

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