HTTP Endpoints

The gateway discovery, device, token, and browser routes exist only when [server.gateway] is configured at startup. POST /device/authorize and GET /device/callback additionally require [server.gateway.oidc]; without OIDC configuration they return a browser error page rather than starting an external sign-in. Adding or removing [server.gateway] requires a restart because route registration is fixed at boot, while changes to its resolved credentials and OIDC configuration hot-apply.

The /managed/settings route exists only when [server.gateway] was enabled at boot. A valid gateway bearer JWT is required; static [server.auth] tokens do not authenticate this endpoint. When [[server.gateway.policies]] is configured, the response is:

{
  "uuid": "sha256:<stable-user-hash>",
  "checksum": "sha256:<settings-hash>",
  "settings": { "availableModels": ["claude-opus-4-8"] }
}

ETag is the quoted checksum ("sha256:<settings-hash>"). Send it back in If-None-Match to receive 304 Not Modified with an empty body when settings have not changed; comma-separated validator lists, weak validators, *, and legacy unquoted checksum values are accepted. No configured policies returns 404; a policy that resolves to an empty document returns 200 with settings: {}.

The POST /v1/{metrics,logs,traces} telemetry-ingest routes exist only when [server.gateway] was enabled at boot, and require the same gateway bearer JWT as /managed/settings. They accept the OTLP/HTTP payloads managed Claude Code clients export — [server.gateway.telemetry] points those exporters at the gateway — and relay the exact request bytes to every destination that opted in to the signal, preserving the inbound content-type and content-encoding and applying the destination’s own configured headers over them (a configured key replaces the forwarded value rather than duplicating the header). The client’s Authorization header is never forwarded, and relays do not follow redirects. Destinations opt in per signal (metrics on by default, logs and traces off), and a signal with no opted-in destination is accepted and discarded. Relays are detached, so the response is always an immediate 200 regardless of destination health — the success body mirrors the request protocol per OTLP/HTTP ({} for application/json, an empty application/x-protobuf body otherwise); a body over the 32 MiB inbound cap returns 413.

The spend-limit routes exist only when [server.spend] was configured at boot — independently of [server.gateway], since they authenticate with the [server.admin] credential. Send that credential in the configured admin header (x-shunt-admin-token by default) or in x-api-key; both slots are accepted. A write credential (a write_keys entry, or a tokens_env/tokens_file pair) can use every operation, while a read_keys credential can use GET only and receives 403 on mutations. POST accepts user and organization scopes, a daily/weekly/monthly period, a user_id of 1–256 bytes for user scopes, and an amount that is either a 1–19 digit whole-number string of USD cents or null. It upserts by (scope, period). List pagination accepts limit (1–1000, default 20), after_id, before_id, and scope_type; the two cursors are mutually exclusive. Every response includes request-id, and errors use the Anthropic error shape. Caps and mutation audit records persist together in the configured versioned JSON state file, each mutation attributed to admin-key:<id> or admin-token:<name> — when both slots carry a different credential of the same tier, the configured header is the attributed one. Stage 1 does not expose /effective or /audit and does not enforce caps on inference requests.

The /admin* routes exist only when [server.admin] is configured; without that table, none of them are registered. They accept the admin credential in the configured header or x-api-key, and a read_keys credential passes every GET below while being refused with 403 on every mutation and with 401 on POST /admin/login. GET /admin/observed auto-discovers supported Claude Code, Codex CLI, Gemini CLI, Kimi Code, Grok CLI, and Cursor.app credentials on the gateway host. It never refreshes or writes those sources. Claude usage is cached for 60 seconds; Codex usage is response-derived and remains unavailable until traffic through this shunt returns x-codex-* headers; the other providers use their first-party read-only quota surfaces. Managed account CRUD and /admin/pool remain the separate shunt-owned credential lane.

The /backend-api/codex/responses, /responses, /v1/responses, /backend-api/codex/analytics-events/events, and /codex/analytics-events/events routes exist only when [server.codex_endpoint] is configured; without that table, none of them are registered. The three Responses paths relay raw OpenAI Responses requests and responses, unlike the Anthropic-Messages-translating /v1/messages above. The two analytics paths use the same inbound-auth policy, never forward or retain the client payload, and return 200 {} after authentication even for malformed or oversized bodies. Only sanitized event names are counted in shunt.codex_client_events; with no metric sink configured they are pure discard sinks. See the inbound Codex endpoint guide.

The /usage route exists only when [server.usage] is configured, which itself requires [server.auth]. It authenticates the same client token as GET /v1/messages (configured header, x-api-key, or Authorization: Bearer) and returns a sanitized, aggregated view of the shared account pool — per-window remaining headroom and reset time plus a coarse ok/degraded/exhausted status — so a non-admin caller can anticipate throttling. It never exposes account names, counts, priorities, disabled flags, thresholds, or per-account numbers; the full per-account detail stays behind admin-only GET /admin/pool. A window is null only when no non-disabled account reports it. Codex response x-codex-* headers and optional wham/usage polling populate the observed 5-hour and shared weekly windows; an unobserved window alone is null. Codex has no Fable-scoped (7d_oi) signal, although another provider in a mixed pool may supply the aggregate Fable window. Response shape:

{
  "pool": {
    "status": "ok",
    "windows": {
      "5h":    { "remaining": 0.42, "resets_at": 1752000000 },
      "7d":    { "remaining": 0.61, "resets_at": 1752500000 },
      "fable": { "remaining": null, "resets_at": null }
    }
  }
}

The /api/oauth/usage route exists only when [server.oauth_usage] is configured. It is the exact path the Claude Code CLI’s own usage bars fetch (fetchUtilization), so when the CLI is pointed at shunt via ANTHROPIC_BASE_URL, its unmodified UI can show real numbers — but only for CLIs using a full interactive claude login session; claude setup-token and shared-gateway client-token setups were verified not to trigger the CLI’s own fetch (see the M14 behavior specification for the full precondition evidence). Unlike GET /usage, auth is bind-topology-gated: unauthenticated on a loopback [server] bind, and requiring a valid credential — a configured client token or a valid gateway JWT, exactly as /v1/messages is gated — on a non-loopback bind (which itself then requires [server.auth] or [server.gateway] to be configured). Bare header presence is not accepted. It reports only claude_oauth-provider accounts, using a routing-aware, priority-tiered worst case per window rather than /usage’s pool-wide least-utilized aggregate — the worst case among the accounts the next request can actually route to, not an optimistic pool-wide minimum. It never exposes account names, counts, priorities, disabled flags, thresholds, or per-account numbers. Response shape (Anthropic’s own /api/oauth/usage schema, resets_at in RFC3339):

{
  "five_hour": { "utilization": 42.37, "resets_at": "2026-07-20T23:00:00Z" },
  "seven_day": { "utilization": 61.02, "resets_at": "2026-07-27T00:00:00Z" },
  "limits": [
    {
      "kind": "weekly_scoped",
      "scope": { "model": { "display_name": "Fable" } },
      "percent": 12.5,
      "resets_at": "2026-07-27T00:00:00Z"
    }
  ]
}

five_hour/seven_day are omitted (not null) when no non-disabled Claude account reports that window; limits is omitted entirely (not an empty array) when no account reports the Fable-scoped window.

GET / and GET /health stay open even when [server.auth] is enabled (healthcheck tools usually cannot attach tokens) and expose nothing sensitive — only status, version, and the already-public endpoint list. With [server.auth] enabled, GET /v1/models requires a valid client token in the configured header, x-api-key, or Authorization: Bearer; it stays open when inbound auth is not configured. GET /routes remains open as shunt-native routing metadata.

Gateway protocol

shunt implements the official Claude Code LLM gateway protocol: correct header and body-field forwarding, feature pass-through, and system-prompt attribution handling. Gateway-owned errors are returned in the Anthropic error shape, upstream context-overflow errors are rewritten to Anthropic’s prompt is too long wording so Claude Code’s compact-and-retry fires, and streaming responses are relayed without buffering (with optional keepalive pings).