Claude Code Routineをfire APIで外部から起動する手順

Claude Codeの/fireエンドポイントは、保存済みのRoutineをHTTPのPOST一発で起動する入口です。CIの失敗やアラート検知をきっかけに、Claude Codeのセッションをクラウド上で立ち上げられます。リクエストが返るのはセッション作成の時点で、実行の完了やストリーム出力は待ちません。レスポンスに入っているセッションURLを開いて、進行を追う形になります。

このAPIは実験的な位置づけで、リクエストとレスポンスの形、レート制限、トークンの意味が変わる可能性があると明記されています。Routine全体の仕組みはClaude Code Routines完全ガイドにあり、ここでは/fireを外部から叩く部分だけを掘り下げます。

通常のAPIと何が違うか

/fireはClaude Platformの一部ではなく、Claude Codeの製品面に属します。Claude APIの感覚で扱うと、認証で最初につまずきます。

呼び出せるのは、Claude Code on the webが有効なPro・Max・Team・Enterpriseのclaude.aiアカウントです。ANTHROPIC_BASE_URLで向き先を切り替える類の設定とは無関係で、APIキーをトークンの代わりに渡しても通りません。

スケジュールやGitHubトリガーとの使い分け

Routineのトリガーは3種類で、1つのRoutineに組み合わせられます。たとえばPRレビュー用のRoutineを、毎晩の定期実行、デプロイスクリプトからの呼び出し、新しいPRへの反応の3つで動かせます。

イベントがGitHub上で完結するならGitHubトリガー、時刻で決まるならスケジュール、GitHub以外のシステムが発火源ならAPIトリガーという分け方になります。上限の性質も違います。スケジュールは超えると待たされますが、GitHubとAPIは超えた分が実行されません。アラートのように取りこぼしが困る入口にAPIを使うなら、上限を見込んだ設計が要ります。

準備: URLとトークンを手に入れる

トークンはWebのUIでしか作れません。CLIからはトークンの作成・再生成・削除ができません。

新しいトークンを作ると、前のトークンは失効します。ローテーションは「Regenerate」、API経由の起動を止めたいときは「Delete token」です。IDはroutine_ではなくtrig_で始まります。パラメータ名はroutine_idのままなので、読み違えやすい点です。

最小の呼び出し

URLとトークンをシークレットとして保存し、環境変数経由で渡します。

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": "Sentry alert SEN-4521 fired in prod."}'

成功すると200 OKで、次の3フィールドが返ります。

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

typeは常にroutine_fireです。claude_code_session_urlをSlack通知などに載せておくと、起動したセッションにすぐ飛べます。

anthropic-betaヘッダは必要か

公式の2つのページで、ヘッダの扱いが食い違っています。Claude Code側のdocsのcurl例にはanthropic-beta: experimental-cc-routine-2026-04-01が入っています。一方、Platform側のAPIリファレンスの必須ヘッダはAuthorizationとanthropic-versionの2つで、betaヘッダを送る古い連携も「付けても付けなくても受け付ける」と書かれています。

anthropic-versionは2023-06-01だけが有効値で、欠けたり別の値だったりすると400になります。新規に組むなら、Platform側の記述どおり2つのヘッダで始め、400が出たらベータヘッダの有無を疑う、という順が無難です。

textに何を入れるか

リクエストボディは任意で、フィールドはtextだけです。未知のフィールドは無視されます。

• 中身は自由形式の文字列で、パースされません。JSONを送っても、Routineには文字列そのものが届きます
• 上限は65,536文字で、超えると400になります
• 保存済みのプロンプトに添える形で渡されます

アラート本文、失敗したログの数行、gitのdiffといった、その回だけの文脈に向く欄です。長いログを丸ごと入れるより、末尾の数十行に絞るほうが、上限にも読み取り負荷にも余裕が出ます。

プロンプトが参照しないと無視される

textは裸のメッセージとしては届きません。<routine-fire-payload>ブロックで包まれ、「信頼できないデータ」として扱われます。保存済みプロンプトが明示的に参照しない限り、Claudeはその中の指示に従いません。

つまりRoutine側のプロンプトに、payloadを参照する一文が要ります。

左のように書くと、/fireで送ったtextは手がかりとして扱われるだけで、調べる対象にはなりません。右のように「ブロックに書かれた内容」を名指しすると、textが作業の入力になります。

これを書き忘れると、リクエストは200で成功してもセッションはtextを使わずに終わります。トークンが漏れても、textだけで任意の指示を実行させられない設計です。

GitHub Actionsから失敗時に起動する

公式の例は、if: failure()でCIが落ちたときだけ/fireを叩くステップです。

- 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\"}"

URLとトークンの両方をsecretsに置いている点が要です。この例は失敗の事実と実行IDしか渡していません。Routine側にリポジトリが紐づいていれば、プロンプトで「ログはCIの該当runを見て確認する」と指示する構成にできます。ワークフローのYAMLをClaude Codeと一緒に組む手順はGitHub Actionsのワークフロー作成にあります。そちらがCIの中でClaudeを動かす方式なのに対し、Routineは保存済みの設定で毎回同じ状態から起き上がり、CIは起動の合図を送るだけです。

次の形は、公式の例を元にした組み立て例です。ログの末尾をjqでJSONに安全に埋め込み、引用符やバックスラッシュで壊れないようにします。

run: |
  tail -n 80 build.log | head -c 60000 > tail.txt
  jq -n --rawfile log tail.txt \
    --arg run "$GITHUB_RUN_ID" \
    '{text: ("CI failed. run=" + $run + "\n" + $log)}' \
  | curl -X POST "$ROUTINE_FIRE_URL" \
      -H "Authorization: Bearer $ROUTINE_FIRE_TOKEN" \
      -H "anthropic-version: 2023-06-01" \
      -H "Content-Type: application/json" \
      -d @-

head -c 60000はバイト数での切り詰めです。日本語などのマルチバイトは1文字が複数バイトになるため、文字数としては上限65,536を下回ります。

429とリトライを設計する

起動回数には時間あたりの上限があります。

上限に達すると429 rate_limit_errorが返り、Retry-Afterヘッダにウィンドウが戻る目安が入ります。失敗が連続して出るCIや、ノイズの多いアラートをそのまま/fireに流すと、数十分で枠を使い切ります。Routine側のRun nowも同じ30回を食うため、手動で試した分も数えます。

エラーごとの原因は次のとおりです。

503はClaude Platformの529に相当しますが、このエンドポイントでは503で返ります。

再試行で二重起動する点に注意

冪等キーの仕組みはありません。リトライすると、そのたびに別のセッションが作られます。成功したのにレスポンスだけ受け取れなかった場合も、再送すれば二重起動です。

次は、429のときだけRetry-Afterを待つ最小の例です。5xxの自動再試行は、二重起動を許容できるアラート用途に限るのが安全です。

for i in 1 2 3; do
  code=$(curl -s -o resp.json -D hdr.txt -w '%{http_code}' \
    -X POST "$ROUTINE_FIRE_URL" \
    -H "Authorization: Bearer $ROUTINE_FIRE_TOKEN" \
    -H "anthropic-version: 2023-06-01" \
    -H "Content-Type: application/json" \
    -d '{"text": "deploy check"}')
  [ "$code" != "429" ] && break
  sleep "$(awk 'tolower($1)=="retry-after:"{print $2+0}' hdr.txt)"
done
echo "status=$code"

待ち時間が長くなる場合は、ループで粘るより通知を捨てるか、ジョブを後ろにずらす設計のほうが、CIの実行時間を食いません。

起動できないときの切り分け順

エラー表の原因が複数あるものは、確認の順番を決めておくと早く片づきます。

運用のチェックポイント

• 通知の全件を流さず、落ちたジョブだけ・本番の重大度だけに絞ってから/fireを呼ぶ
• Routine側のプロンプトでpayloadブロックを必ず参照させる
• トークンはシークレットストアに置き、流出や退職時は「Regenerate」で即失効させる
• 同時に複数セッションが立ち上がっても困らないよう、PR作成先のブランチ運用を決めておく。環境やネットワークの制約はクラウド環境の内部構造で整理しています

トークンの権限は、そのRoutineを起動することに限られます。読み取りはできず、他のRoutineやアカウントのデータにも触れません。漏れた場合の影響は、そのRoutineが余分に走る範囲に収まります。