GET /protocol, covering the same forwarding requirements plus the Claude apps gateway-specific endpoints for SSO sign-in, managed-settings delivery, and telemetry. Claude apps gateway runs from the same claude binary as the CLI, so the Claude apps gateway quickstart is the shortest path to a running instance you can fetch the spec from.
- To roll out an existing or third-party gateway for your organization, see Roll out an LLM gateway
- If you’re an individual developer authenticating Claude Code to a gateway with a credential you were given, see Connect Claude Code to an LLM gateway
- API formats and the endpoints to serve for each
- Request headers: which must reach the upstream and which your gateway can consume
- The system prompt attribution block and how it interacts with prompt caching
- Feature pass-through: what breaks when headers or body fields are stripped
- Model discovery
- Forward unchanged: pass it to the upstream byte-for-byte
- Consume: the gateway may read it for routing, attribution, or tracing and need not forward it
API formats
A gateway must expose at least one of the following API formats to Claude Code clients. Which format Claude Code speaks is determined by the client’s configuration: the variable in the Selected by column of the table below points Claude Code at your gateway in that format. Google Cloud’s Agent Platform is Google Cloud’s Claude endpoint, formerly Vertex AI; its variable names keep theVERTEX spelling.
Foundry and Claude Platform on AWS
Microsoft Foundry and the Claude Platform on AWS implement the Anthropic Messages format. Claude Code routes to them through their own variables,ANTHROPIC_FOUNDRY_BASE_URL and ANTHROPIC_AWS_BASE_URL, but a gateway fronting either implements the Anthropic Messages row above. A gateway fronting the Claude Platform on AWS must also forward the anthropic-workspace-id header, which that platform requires on every request.
Optional endpoints and startup traffic
Token-counting endpoints are the only optional ones: when they’re absent, Claude Code estimates context usage locally. Inference requests post to/v1/messages?beta=true, so match on the path, not the full URL. The Google Cloud’s Agent Platform method suffixes attach to the publisher model path, as in /projects/{project}/locations/{location}/publishers/anthropic/models/{model}:streamRawPredict.
A gateway also sees best-effort startup traffic it can reject without breaking anything: a HEAD / connectivity probe, and on Amazon Bedrock-format gateways a GET /inference-profiles?type=SYSTEM_DEFINED request.
The fast mode availability check never appears in gateway logs: it calls api.anthropic.com directly rather than following ANTHROPIC_BASE_URL, so on a network that blocks direct egress to api.anthropic.com, fast mode can report a connectivity error while inference through the gateway keeps working. The WebFetch domain safety check also calls api.anthropic.com directly. Use fast mode behind proxies and LLM gateways covers the variables that restore it.
Streaming
Inference responses must stream. Claude Code consumes server-sent events as they arrive, so a gateway that buffers complete responses before relaying them stalls the client. Forward keep-alive pings as well. On connections throughANTHROPIC_BASE_URL or ANTHROPIC_AWS_BASE_URL, Claude Code counts every byte your gateway relays, including SSE ping events and comment lines, and aborts a stream that goes silent for 300 seconds by default. The upstream’s pings are the only traffic during long thinking pauses, so if your gateway strips or buffers them, Claude Code aborts the stream during those pauses; Automatic retries covers what an aborted stream reports based on how far the response had progressed. Gateways reached through ANTHROPIC_BEDROCK_BASE_URL, ANTHROPIC_VERTEX_BASE_URL, or ANTHROPIC_FOUNDRY_BASE_URL aren’t wrapped by this byte-level watchdog, even when they relay the Anthropic Messages format; there, a 5-minute idle timeout aborts a silent stream instead, and on ANTHROPIC_BEDROCK_BASE_URL connections you can add the byte watchdog with CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK.
Format mismatch with the upstream
Which format the client speaks determines what your gateway receives. The common failure mode is a mismatch between the format the client sends to your gateway and the format the upstream provider behind it accepts.- When the client speaks the Amazon Bedrock or Google Cloud’s Agent Platform format, Claude Code sends only the subset of its full capability set that those providers accept
- When the client speaks the Anthropic Messages format, Claude Code sends the full set, even if your gateway forwards to an Amazon Bedrock or Google Cloud’s Agent Platform upstream
Request headers
Claude Code includes these headers on API requests. Header names are case-insensitive on the wire. Forwardanthropic-version and anthropic-beta unchanged, plus anthropic-workspace-id when the upstream is the Claude Platform on AWS; the rest the gateway may consume for routing, attribution, and tracing, and need not forward.
Subagent IDs are generated fresh for each spawn. Teammate agents, the named members of an agent team, reuse a stable name-based ID across reconnections. In both cases the ID identifies an agent, not a person or a device, so don’t treat the agent ID header as a user identifier.
If your developers set
ANTHROPIC_CUSTOM_HEADERS, those headers appear on requests as well.
Forward as open lists
Treat the headers and body fields as open lists, not closed ones. Claude Code gains capabilities over releases, and they arrive as newanthropic-beta values, new request body fields, and occasionally new anthropic-* or x-claude-code-* headers.
When forwarding to an Anthropic-format upstream, pass anthropic-* request headers and request body fields through unchanged rather than allowlisting the ones you see today. A gateway pinned to an observed list strips the next capability’s header or field and breaks it on the release that introduces it.
The exception is a non-Anthropic upstream such as Amazon Bedrock or Google Cloud’s Agent Platform, where bridging the schema difference is the gateway’s job; see feature pass-through.
System prompt attribution block
Claude Code prepends a short attribution block to the system prompt containing the client version and a fingerprint derived from the conversation. Theapi.anthropic.com endpoint strips the block before processing when it arrives unchanged as the first system block, so it doesn’t affect first-party prompt caching. Any other upstream receives it as part of the prompt.
The strip is positional, so it only works when the gateway forwards the system array unchanged. To keep the block out of the prompt without losing other system content:
- Forward the
systemarray exactly as received, keeping the block first: prepending another system block, reordering the array, or converting it to a single string defeats the strip, and the block then reaches the model and the prompt cache key. - Keep the block in its own array entry: the endpoint treats a merged block that starts with the attribution header as attribution in its entirety and drops everything merged into it, including the rest of the system prompt.
- If your gateway must reshape system content, set
CLAUDE_CODE_ATTRIBUTION_HEADER=0so Claude Code omits the block. Anthropic and the cloud providers’ Claude endpoints read the block for attribution, so omit it at the client rather than stripping or moving it in the gateway.
CLAUDE_CODE_ATTRIBUTION_HEADER=0 when your gateway does either of these:
- Implements a prompt cache keyed on the request body.
- Forwards requests to a third-party provider such as Amazon Bedrock, Microsoft Foundry, or Google Cloud’s Agent Platform, in the Anthropic Messages format or the provider’s own, where the changing prefix reduces prompt-cache reuse on that provider.
Feature pass-through
Claude Code treats anANTHROPIC_BASE_URL gateway as an Anthropic-format endpoint and sends it the beta headers and request body fields it sends to api.anthropic.com, except a small set of diagnostics and defaults reserved for direct connections, such as the fine-grained tool streaming default covered below. That set varies by release, so don’t depend on its contents.
Capabilities that add body fields pair them with a beta header, and the pair travels together. A gateway that strips the header while passing the body, or forwards an Anthropic-format body to an upstream with a different schema, produces hard 400 errors; only when both halves are absent together does the feature turn off quietly.