HTTP エンドポイント

/admin* ルートは [server.admin] が設定されている場合にのみ存在します。そのテーブルがなければ、いずれも登録されません。管理認証情報は設定されたヘッダーまたは x-api-key で受け付け、read_keys の認証情報は上記のすべての GET を通過しますが、すべての変更操作では 403 で拒否されます。サインインは可能です: POST /admin/login はこれを受け入れて read 階層のセッションを発行し、そのセッションの変更操作も同じ 403 で拒否されます。 このログイン POST には same-origin ガードがあります: クロスサイトのフォーム送信は認証情報を検査する前に 403 で拒否されるため、どの認証情報の保持者も、サインイン済みの運用者のセッション Cookie を自分のものへ差し替えることはできません。スクリプトからのログインは影響を受けません — Sec-Fetch-Site と Origin のどちらも無い場合、このチェックは通過します。ただし SPA シェルとバンドルファイルは例外で、GET /admin(2 つの綴りとも)、GET /admin/{*path}、GET /admin/assets/{*path} は管理認証なしで配信されます。これらは運用者のデータを含まず、SPA が読み取る値はすべて、リクエストごとに認証する /admin/api/* の背後にあるため安全です。ワイルドカードの 2 つのルートは、[server.admin] が設定され、かつ --features ui でビルドしたバイナリでのみ存在します。GET /admin/api/observed は、ゲートウェイホスト上のサポート対象の Claude Code、Codex CLI、Gemini CLI、Kimi Code、Grok CLI、Cursor.app の認証情報を自動検出します。これらのソースをリフレッシュしたり書き込んだりすることはありません。その検出を省くには [server.admin].hide_observed を設定します: ルートは引き続き認証したうえで { "accounts": [] } を返し、GET /admin/api/session は hide_observed: true を報告し、ダッシュボードはそのリクエストを省いて管理対象のプールアカウントのみを一覧表示します。

管理 SPA バンドル（--features ui）

/admin/assets/{*path} と /admin/{*path} の SPA フォールバックは、 --features ui でビルドしたバイナリにのみ存在します。このビルドは ui/ パッケージから生成したバンドルをバイナリに埋め込みます。既定の cargo build は Node ツールチェーンを必要とせず、バンドルも持たず、どちらのルートも登録しません。 配布されているリリースバイナリはこの機能を有効にしてビルドされています。

フォールバックは /admin マウント配下に限定されます。

• /admin/ 配下でどのルートにも一致しないパスは、200 と text/html で SPA シェルを返すため、クライアント側のディープリンクがリロード後も維持されます。
• /admin/api/ 配下で一致しないパスは、Anthropic のエラー形状で 404 を返します。 この名前空間は UI ではなく JSON であり、HTML を返すとクライアントのエラー処理が 壊れるためです。
• マウントの外側のパスは影響を受けず、これまでどおり 404 を返します。

GET /admin もシェルで、GET /admin/ も同様です。ワイルドカードのセグメントは空文字列に一致しないため、/admin/ は完全一致のルートにもフォールバックにも一致せず、ダッシュボード自身のルートで本文のない 404 を返してしまいます。そのため、マウントルートは 2 つの綴りをそれぞれ登録しています。

この 2 つは、両方のビルドに登録されていながら応答が機能フラグ次第で変わる管理パスで、有効ならシェル、無効なら本文に --features ui を挙げた 404 を返します。どちらでも登録しておくのは、その 404 にこの案内文を持たせるためです — ルートごと外すと axum の本文なし 404 になり、運用者は [server.admin] 未設定と見分けられません。

管理パスの移行

破壊的変更です。 すべての管理 JSON ルートと変更系ルートが /admin/* から /admin/api/* へ 移動しました。古いパスはエイリアスを残さず削除され、どのリクエストも admin ハンドラーには 到達しなくなりました。

古いパスで何が返るかはビルドによって異なるため、そこでの 200 を成功と見なさないでください:

• デフォルトビルド — パスがどこにも登録されておらず、404 を返します。
• --features ui(ビルド済みリリースバイナリはこちら)— GET はマウント配下の他のディープ リンクと同様に /admin/{*path} の SPA フォールバックへ落ち、200 text/html のシェルを返します。 HEAD も同じです。それ以外のメソッドは Allow: GET,HEAD を伴う 405 を返します — フォールバックが any ではなく get で登録されているためです。

そのため古い GET URL のままのスクリプトは、移行を示すシグナルではなく HTML を受け取ります。 /admin/api/* へ移してください。レスポンスの Content-Type が確実な判別基準です。

/admin はダッシュボードのシェルとして残り、/admin/login と /admin/oidc/callback もそのままです — これらは API ルートではなく、サーバー側でレンダリングされるページだからです。それ以外はすべて 移動しました。ダッシュボードが /admin/* をブラウズ可能なディープリンクとして使えるようにするため です。一つのパスが JSON エンドポイントであると同時にクライアント側のルートであることはできないため、 互換用のエイリアスは残していません。

スクリプトから呼び出している箇所は、機械的に一度だけ書き換えてください。パスは /admin の後ろに /api セグメントが一つ増えるだけです:

認証は変わりません。同じ管理認証情報を同じヘッダーまたは x-api-key で送り、読み取り/書き込みの等級も同じです。

spend-limit ルートは、起動時に [server.spend] が設定されていた場合にのみ存在します。[server.admin] の認証情報で認証するため、[server.gateway] とは無関係です。その認証情報は設定された管理ヘッダー（デフォルトは x-shunt-admin-token）または x-api-key で送信します — どちらのスロットも受け付けます。write の認証情報（write_keys エントリー、または tokens_env/tokens_file のペア）はすべての操作を使用でき、read_keys の認証情報は GET のみ使用でき、変更操作では 403 を受け取ります。POST は user と organization の scope、daily／weekly／monthly の period、user scope では 1～256 バイトの user_id、1～19 桁の USD セント非負整数文字列または null の amount を受け付け、(scope, period) 単位で upsert します。一覧では limit（1～1000、デフォルト 20）、after_id、before_id、scope_type を使用でき、2 つのカーソルは同時に指定できません。すべてのレスポンスに request-id が含まれ、エラーは Anthropic のエラー形式です。上限と変更監査レコードは、設定したバージョン付き JSON 状態ファイルに一緒に保存され、各変更は admin-key:<id> または admin-token:<name> に帰属します — 両方のスロットが同じティアの異なる認証情報を保持している場合は、設定された管理ヘッダー側が帰属先になります。GET /v1/organizations/spend_limits/effective（read または write 認証情報）は、プリンシパルと期間ごとに 1 行、適用される上限（amount、source、spend_limit_id）と米国セント単位の period_to_date_spend を返します。limit（1–1000、デフォルト 20、プリンシパル数で計数）、period[]、user_ids[]（最大 100 件、ページネーションなし）、q、sort=spend_desc（period[] がちょうど 1 つのとき）、page を受け付け、不正な入力には 400 invalid_request_error を返します。period_to_date_spend はメーターが読み取れたカウンターだけを反映します。保存されたカウンターレコードの復元に失敗したプリンシパルは、unavailable フラグが解除されるまで支出が 0 または一部だけに見えることがあり、ログの復元警告にそのプリンシパルが記録されます。上限は /v1/messages と、受信 Codex エンドポイントの Responses ルートおよび /alpha/search エイリアスに適用されます（上限を超えた Codex ターンは 429 usage_limit_reached を受けます。受信 Codex エンドポイントを参照）。passthrough または type = "noop" ルートのみのチェーンには適用されません。/audit は公開されません。

/user/bootstrap ルートは、起動時に [server.gateway] が有効だった場合にのみ存在し、有効なゲートウェイ bearer JWT を要求します。static な [server.auth] トークンでは認証できません。[server.gateway.desktop_bootstrap] のテンプレートを application/json で返し、文字列値の中の ${user.email}、${user.sub}、${user.name} は置換されます。エラーと 304 を含むすべてのレスポンスに Cache-Control: no-store が付き、ルートはリダイレクトしません。

policy がなければサインイン済みの全ユーザーが対象で、policy があれば、policy の match.emails に含まれるか、catch-all policy（match なし）がある場合に対象になります。デバイスコードのエンドポイントは、client_id のないリクエスト（Claude Desktop は送りません）と client_id=claude-code のリクエストを受け付け、それ以外の値は拒否します。client_id のないリクエストで拒否された refresh トークンは 400 {"error":"invalid_grant"} を返し、claude-code のリクエストは 401 のままです。Claude Desktop の接続を参照してください。

GET /managed/settings と POST /v1/{metrics,logs,traces} のテレメトリー受信ルートは、起動時に [server.gateway] が有効だった場合にのみ存在し、どちらも同じゲートウェイのベアラー JWT を要求します。受信ルートは、管理された Claude Code クライアントが export する OTLP/HTTP ペイロードを受け取り（[server.gateway.telemetry] がそれらの exporter をゲートウェイへ向けます）、リクエストのバイト列をその signal に opt-in したすべての宛先へそのまま中継します。インバウンドの content-type と content-encoding は保持され、宛先に設定された headers がその上に適用されます（設定されたキーは転送値を置き換え、ヘッダーを重複させません）。クライアントの Authorization ヘッダーが転送されることはなく、中継はリダイレクトに従いません。宛先は signal ごとに opt-in し（metrics はデフォルト on、logs／traces は off）、どの宛先も opt-in していない signal は受理後に破棄されます。中継はデタッチされているため、宛先の状態にかかわらずレスポンスは常に即座の 200 で、成功ボディは OTLP/HTTP に従いリクエストのプロトコルをミラーします（application/json には {}、それ以外には空の application/x-protobuf ボディ）。32 MiB の受信上限を超えるボディは 413 を返します。

Inbound Codex Responses、Web 検索、モデルカタログ、analytics のルートは [server.codex_endpoint] が設定されている場合にのみ存在します。Responses ルートは OpenAI Responses のリクエストとレスポンスを HTTP/SSE（POST）または WebSocket アップグレード（GET）でそのまま中継し、[[server.codex_endpoint.routes]] によってモデルごとに別の Responses 互換アップストリームへルーティングすることもできます。Codex 専用の 2 つのモデルパスは {"models":[]} を返し、共有の /v1/models はクエリに client_version がある場合だけその形式を返し、それ以外では Anthropic 契約を保ちます。すべてのカタログ変形は通常のモデル検出認証ゲートを使います。2 つの analytics ルートは同じ inbound auth ポリシーを適用し、クライアント payload を転送または保持せず、認証後は不正な JSON やサイズ超過の body にも 200 {} を返します。サニタイズ済みイベント名だけを shunt.codex_client_events に記録し、metric sink がなければ純粋な破棄 sink として動作します。3 つの Web 検索パスは、Codex CLI の組み込み Web 検索を Responses パスと同じアカウントプールと inbound auth ポリシーでバックエンドの /codex/alpha/search へそのまま中継します。POST のみを受け付け、[[server.codex_endpoint.routes]] のエントリには従いません。

/usage ルートは [server.usage] を設定した場合にのみ存在し、同じく [server.auth] または [server.gateway] の設定を必要とします。GET /v1/messages と同じクライアントトークン、または Authorization: Bearer で送られたゲートウェイログインのアクセストークン（shunt gateway claude で起動したセッションが送るもの）で認証します。有効なゲートウェイログインは [server.auth] を参照せずに受け付けるため、[[server.auth.jwt]] の鍵セットに到達できなくても締め出されません。共有アカウントプールのウィンドウごとの残り余裕（そのウィンドウを報告した無効化されていないアカウントの mean(clamp(cap - utilization, 0, 1))。cap はそのウィンドウについてのアカウントの解決済み max_utilization ハードキャップで、該当するものがなければ 1.0、つまりキャップによってアカウントが除外されるまでにプール全体の容量のうちまだ使える割合。キャップがそのウィンドウのリクエストからすでに除外しているアカウントは 0 として数えられ、5h または 7d のキャップは Fable リクエストからもそのアカウントを除外します）、それらのアカウントが報告した最も早いリセット時刻（キャップで 0 として数えられているアカウントは、そのキャップが解除される時刻を含む）、ok／degraded／exhausted／capped ステータスを返します。アカウントの身元、件数、優先度、disabled、しきい値、アカウント単位の数値は公開しません。無効化されていないアカウントがそのウィンドウを報告していない場合だけ null になります。Codex の x-codex-* レスポンスヘッダーとオプションの wham/usage ポーリングは、5 時間と共有週次ウィンドウを埋めます。WebSocket トランスポートでは、ストリーム内の codex.rate_limits イベントが再利用接続を含むすべてのターンで同じウィンドウを埋めます。Codex には Fable スコープ（7d_oi）のシグナルがありませんが、混在プロバイダーのプールでは別のプロバイダーが集約 Fable 値を提供できます。pool はプールされるすべてのプロバイダーを通じた集計で、providers は同じサニタイズ済み集計をプールされるプロバイダーごとに、設定されたプロバイダー名をキーとして持ちます。そのため特定のプロバイダーにルーティングするクライアントは、プール全体の平均ではなく、そのプロバイダーの余裕とステータスを読み取れます。プールされない認証モードのプロバイダーは省略されます。完全なレスポンス形は英語版エンドポイントリファレンスを参照してください。 Claude Code のクライアントであれば curl なしで読めます。このリポジトリのプラグインマーケットプレイスにある shunt モッド が /shunt:usage をこのエンドポイントから答え、ウィンドウごとの余裕とリセット時刻を表示します。関数フック（CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1）が必要で、まだアーリーアクセスです。

プール状態 capped は、利用可能なアカウントがなく、有効（disabled でない）かつ一時停止されていないアカウントのうち 1 つ以上が max_utilization* のハードキャップで除外されていることを意味し（[server.pool] を参照）、exhausted とは区別されます。

GET / と GET /health は、[server.auth] が有効なときも開いたままです（ヘルスチェックツールは通常トークンを付けられません）。機密情報は何も公開しません — ステータス、バージョン、およびすでに公開されているエンドポイント一覧のみです。 [[server.auth.jwt]] エントリを設定すると、Authorization: Bearer の検証済み外部 JWT がクライアントトークンと同じゲート対象ルートを認証します。どのエントリでも検証できなかったトークンは 401、検証できたエントリがなく、トークンの issuer に一致するエントリのうちキャッシュ済みの key set がなく取得にも失敗したものがある場合は 503 です。

ゲートウェイプロトコル

shunt は公式の Claude Code LLM ゲートウェイプロトコルを実装します: 正しいヘッダーとボディフィールドの転送、機能のパススルー、システムプロンプトのアトリビューション処理。ゲートウェイ所有のエラーは Anthropic のエラー形で返され、上流のコンテキストオーバーフローエラーは Anthropic の prompt is too long の文言へ書き換えられて Claude Code のコンパクト＆リトライが発火し、ストリーミングレスポンスはバッファリングなしで中継されます（オプションでキープアライブ ping 付き）。