透過 API 觸發例行程序

Claude Code 是 Anthropic 的代理式編碼工具。Claude Code on the web 在 Anthropic 管理的雲端基礎設施上於 claude.ai/code 執行 Claude Code 工作階段，而例行程序是其中儲存的設定：一個提示、一個或多個儲存庫以及連接器，經過封裝後可以按排程、回應 GitHub 事件或透過 HTTP 呼叫時無人值守地執行。

此端點是 HTTP 進入點。向它發送 POST 請求會啟動現有例行程序的新執行，並回傳產生的工作階段 ID 和 URL。典型的呼叫者是警報系統、CI 管線以及需要以程式化方式啟動 Claude Code 工作階段的內部工具。

呼叫此端點需要一個啟用了 Claude Code on the web 的 Pro、Max、Team 或 Enterprise 方案的 claude.ai 帳戶。請使用在 Claude Code 網頁 UI 中建立的每個例行程序專屬的 bearer token 進行驗證，而非 Claude API 金鑰。

與 Claude Platform 的差異

例行程序觸發端點屬於 Claude Code 產品範疇，它在幾個方面與 Claude Platform 的 API 和 SDK 不同：

開始之前

要呼叫此端點，您需要：

1. 在 claude.ai/code/routines 建立的例行程序。
2. 為該例行程序產生的 bearer token：開啟例行程序進行編輯，在 Select a trigger 下點擊 Add another trigger，選擇 API，然後在彈出視窗中點擊 Generate token。該 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 網頁 UI 會在 token 旁提供完整的 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 token 的範圍僅限於單一例行程序。遭洩露的 token 只能觸發該例行程序；它不授予讀取存取權、不授予對其他例行程序的存取權，也不授予對帳戶資料的存取權。

在 claude.ai/code/routines 的例行程序 API 觸發器設定中產生和撤銷 token。沒有用於 token 管理的公開 API。產生新 token 會撤銷前一個 token。

冪等性

每個成功的請求都會建立一個新的工作階段。沒有冪等性金鑰。如果 webhook 呼叫者重試，端點會建立多個工作階段。

速率限制

例行程序執行會計入每個帳戶的每日配額（依方案而異），而產生的工作階段會消耗與互動式工作階段相同的 Claude Code 訂閱用量。當達到任一限制時，端點會回傳 429 rate_limit_error 以及 Retry-After 標頭。啟用了額外用量的組織可以在超出包含配額後以計量超額方式繼續使用。

在 claude.ai/code/routines 查看您剩餘的每日執行次數。要了解例行程序用量如何與訂閱限制和額外用量計費互動，請參閱 Claude Code 文件中的用量與限制。

SDK 支援

此端點不在 Anthropic SDK 中。其 token 模型與 API 金鑰驗證不同，而典型的呼叫者（例如 CI 工作和警報 webhook）會直接發送請求。

另請參閱

• Claude Code 文件中的使用例行程序自動化工作
• Beta 標頭
• 錯誤