透過 API 觸發例行程序

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

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

呼叫此端點需要一個使用 Pro、Max、Team 或 Enterprise 方案且已啟用 Claude Code on the web 的 claude.ai 帳戶。請使用在 Claude Code 網頁介面中建立的每個例行程序專屬「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

當您新增 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 "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 token 的範圍僅限於單一例行程序。遭洩露的 token 只能觸發該例行程序；它不授予讀取存取權、不授予對其他例行程序的存取權，也不授予對帳戶資料的存取權。

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

冪等性

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

速率限制

API 觸發次數有每小時上限：每個例行程序每小時最多接受 30 次觸發（由 API 觸發、網頁 UI 中的 Run now 按鈕和一次性重新啟用共用），而每個帳戶每小時在所有例行程序中最多可進行 100 次 API 觸發。產生的工作階段會消耗與互動式工作階段相同的 Claude Code 訂閱用量。當達到限制時，端點會回傳 429 rate_limit_error 以及一個 Retry-After 標頭。

要了解例行程序用量如何與訂閱限制和額外用量計費互動，請參閱 Claude Code 文件中的用量與限制。

SDK 支援

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

另請參閱

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