Introducing a new way to review your PRs.

Read the announcement

alishahryar1 / free-claude-code

Use Claude Code, Codex, Antigravity, VSCode, Pi, and OpenCode (and 6 other harnesses) for free (1.3B+ free tokens) from your terminal, app, IDE, or phone, and now from the browser with native browser sessions (multi-harness + multi-model) like OpenClaw (voice supported + ToS friendly)

View on GitHub

28 documents · Updated Nov 20, 2026

docs / api-anthropic-endpoints

Anthropic-compatible API endpoints

The Anthropic-compatible API presents a Messages interface for clients that expect Claude-style requests and responses. It also presents an OpenAI Responses stream for clients such as Codex. It validates and routes each request to a configured provider, then returns a protocol-shaped response. The same boundary also offers token estimates for clients that need to check input size before generation.

Endpoint surface

The public API exposes two generation paths and one token-count path. All three paths use proxy authentication when it is enabled, and the generation paths share request correlation so a client can match a response with server records.

EndpointClient contractResult
POST /v1/messagesAnthropic Messages APIJSON message when stream is false; Anthropic SSE when stream is true
POST /v1/responsesOpenAI Responses APIOpenAI Responses SSE; streaming is required
POST /v1/messages/count_tokensAnthropic token-count APIJSON object with input_tokens
HEAD or OPTIONS on any pathCapability probe204 response with the allowed methods

The API application joins these routes with the local admin routes. The endpoint page is therefore the client-facing part of the broader API gateway, while provider and runtime controls are described in admin and web tools.

References: src/…/routes.py• L35 src/…/routes.py• L109-164 src/…/app.py• L36-45

Request intake

The request models define the shared language between compatible clients and the gateway. A message request carries a model name, ordered messages, optional system content, generation limits, tools, tool choice, reasoning controls, and other protocol extensions; token-count requests keep the input parts needed for an estimate. Unknown protocol fields are retained at this boundary so compatible clients can send extensions without immediate rejection.

Responses requests use a separate OpenAI-compatible shape. They carry a model and input plus optional instructions, tools, generation controls, reasoning data, and response state fields. This gateway requires the stream mode for this endpoint, and rejects an empty model or input before provider execution.

The intake path performs these checks before provider execution:

  1. The authentication dependency checks the bearer token when proxy auth is enabled.
  2. FastAPI parses the JSON body into the API request model.
  3. The handler rejects an empty messages list or invalid Responses stream request.
  4. The model router turns the public model name into a provider target and applies any configured fallback targets.
  5. The message handler applies gateway policies and checks for supported server-tool or local short-circuit paths.

The request ID is created at HTTP ingress and is reused by the handler, provider execution, error response, and response headers. This gives a streamed request one stable identity even when execution moves across provider candidates.

References: src/…/models.py• L114-153 src/…/models.py• L8-26 src/…/dependencies.py• L47-77 src/…/request_errors.py• L28-30 src/…/request_ids.py• L20-67 src/…/messages.py• L97-142 src/…/responses.py• L53-86 src/…/routing.py• L190-214

Message request flow

The message handler is the main product flow for Claude-compatible generation. It keeps the public model name for the response while passing the resolved provider model to execution, so clients see a stable gateway contract rather than provider-specific routing details.

This diagram shows how one incoming message request becomes a JSON message or an Anthropic event stream.

flowchart TD
    A[POST /v1/messages] --> B[Parse request and check auth]
    B --> C[Validate messages]
    C --> D[Resolve model and policy]
    D --> E{Gateway path}
    E -->|Web server tool| F[Generate tool response stream]
    E -->|Local optimization| G[Return complete message]
    E -->|Provider execution| H[Stream provider output]
    F --> I{stream flag}
    H --> I
    I -->|true| J[Anthropic SSE response]
    I -->|false| K[Aggregate SSE into JSON message]
    G --> L[JSON message]

The normal provider path starts with a synchronous preflight, estimates input tokens, and then reads provider chunks. A retryable failure before the first committed chunk can move execution to the next configured provider. Once a candidate emits response data, the stream is committed and later failures are sent as terminal protocol errors instead of silently switching providers.

Before provider execution, the handler can apply a safety-classifier policy to a recognized request. That policy can remove the classifier stop sequence and turn reasoning off when the request requires it. The handler can also produce a response without a provider call: web server tool requests use the gateway web-tool path when enabled, and recognized local optimizations return a complete message directly. Unsupported server tools fail as an invalid request rather than reaching a provider that cannot honor them.

References: src/…/messages.py• L97-142 src/…/messages.py• L281-343 src/…/execution.py• L143-209 src/…/execution.py• L211-333

Non-streaming message responses

When stream is false, the handler still uses the shared internal stream. It consumes the Anthropic events and folds message metadata, content blocks, deltas, stop data, and usage into one JSON message. This keeps non-streaming clients aligned with the same provider and tool behavior as streaming clients.

The returned message has the Anthropic shape: an assistant role, message identity, model, ordered content blocks, stop reason, and usage. A stream-level error becomes a normal HTTP error response with an Anthropic error envelope instead of a partial success body. The handler also keeps cancellation and application errors distinct from unexpected execution failures, so a client does not receive a misleading success response when aggregation stops early.

References: src/…/messages.py• L144-203 src/…/sse_aggregation.py• L20-128 src/…/models.py• L167-183

Streaming message responses

When stream is true, the handler exposes a managed text/event-stream response. The stream uses Anthropic event names and JSON payloads so a compatible client can process message start, content block changes, message metadata, and message stop events as they arrive.

The stream ledger preserves content-block order and tracks text, thinking, and tool-use state. It also closes open blocks and emits a terminal message event for a successful response. The response wrapper delays runtime release until the client consumes or closes the body, which keeps the provider generation alive for the full response lifetime.

References: src/…/response_streams.py• L42-174 src/…/response_streams.py• L329-371 src/…/emitter.py• L12-62 src/…/ledger.py• L155-232 src/…/ledger.py• L234-380

Responses request flow

The Responses handler provides an OpenAI Responses-compatible stream for clients that use that protocol. It shares model routing and provider execution with Messages, but returns OpenAI event names and error envelopes.

This diagram shows how a valid Responses request becomes an OpenAI Responses event stream.

flowchart TD
    A[POST /v1/responses] --> B[Parse request and check auth]
    B --> C[Require stream, model, and input]
    C --> D[Resolve model]
    D --> E[Stream provider output]
    E --> F[OpenAI Responses SSE]

The handler rejects stream: false, a blank model, or empty input before provider work starts. After validation, it passes the routed request to the provider executor. If execution fails before the first event, the client receives an HTTP error. If it fails after the stream starts, the shared stream boundary emits a terminal OpenAI-compatible failure frame.

References: src/…/responses.py• L32-106 src/…/responses.py• L108-159 src/…/models.py• L8-26 src/…/response_streams.py• L386-422

Token-count requests

The token-count handler estimates the input size of a Messages request without starting generation. It applies the same model routing step as message creation, then counts system text, message content, tool content, and protocol block data to return {"input_tokens": ...}.

The estimate is a gateway-side planning value, not a provider billing record. It gives compatible clients a consistent way to check context pressure before sending a generation request, including requests with images, tool use, tool results, thinking, and server-tool blocks.

References: src/…/token_count.py• L26-87 src/…/tokens.py• L13-111 src/…/routes.py• L150-164

Stream and error contracts

The gateway maps internal execution outcomes to the client's wire error format at the HTTP boundary. Before a stream sends its first event, the gateway can return an HTTP error with a JSON error envelope. After the stream starts, it sends a terminal SSE error event when execution fails, then performs stream cleanup without asking the client to retry through the transport.

The main failure classes are:

  • Invalid request data returns the wire API's invalid-request error type.
  • Authentication, permission, rate-limit, overload, and context failures map to their wire API error types and status codes.
  • Provider timeouts and upstream failures return a non-retryable terminal execution result.
  • A client disconnect cancels the inference work for /v1/messages and releases the retained runtime resource.

The Messages stream contract requires a message start, valid content-block nesting, and a terminal message stop for successful streams. The Responses stream uses its own OpenAI event contract. Both serializers disable proxy buffering and keep the connection open so clients receive incremental output.

References: src/…/errors.py• L8-97 src/…/response_streams.py• L216-422 src/…/stream_contracts.py• L95-164 src/…/request_lifetime.py• L7-84

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep the public model name and request ID consistent across routing, provider fallback, response bodies, and response headers.
  • Keep the non-streaming aggregator aligned with every SSE content block and delta that the streaming ledger can emit.
  • Keep pre-start HTTP errors and post-start SSE errors aligned with the wire API's error type and status maps.
  • Keep runtime lease release tied to response completion, stream cancellation, and empty-stream cleanup.
  • Keep token-count inputs aligned with the message fields that provider preflight and request conversion accept.
  • Keep Responses streaming validation and OpenAI event and error frames aligned with the client contract.
  • Keep safety-classifier routing changes aligned with reasoning controls and stop-sequence handling before provider execution.

Important failure modes

TriggerConsequenceGuard
Empty messages arrayThe request is rejected as invalid before routing.Shared non-empty message validation in both message and token-count handlers.
Responses request sets stream: false or has empty model or inputThe request is rejected before provider work starts.Responses handler validates its streaming-only contract and required values.
Provider fails before its first committed chunk and is retryableThe next configured provider can serve the same request.Provider executor commits a candidate only after it yields data.
Provider fails after stream commitmentThe client receives a terminal wire error instead of a silent provider switch.Managed stream terminal-frame handling.
Non-streaming aggregation misses a new SSE block or deltaJSON clients receive incomplete or malformed content.Keep the aggregator and stream ledger changes in the same contract update.
Client disconnects during generationProvider work can continue unless the request lifetime boundary cancels it.Inference lifetime middleware owns /v1/messages cancellation.
Stream ends before its first eventThe client receives an HTTP error rather than an empty successful stream.First-chunk response wrapper checks for an empty stream.
A recognized safety-classifier request keeps its classifier stop sequence or reasoning modeProvider output can violate the gateway's safety-classifier policy.Apply the routing policy before web-tool, optimization, or provider execution.

Key files

FileWhy to read it
src/…/routes.pyDefines the Anthropic-compatible routes and connects them to handlers and runtime services.
src/…/messages.pyShows the complete message lifecycle from validation through routing policies, optimization, and public response selection.
src/…/responses.pyShows the Responses validation, routing, streaming, and error boundary.
src/…/token_count.pyShows the token-count contract and its routing and error behavior.
src/…/routing.pyExplains how a gateway model name becomes a provider target with fallbacks.
src/…/execution.pyShows provider preflight, streaming, progress limits, and fallback commitment.
src/…/response_streams.pyDefines response lifetime, first-chunk handling, and terminal stream errors.
src/…/ledger.pyShows how streamed content blocks and usage state become Anthropic events.
src/…/sse_aggregation.pyShows how the shared stream becomes one JSON message for non-streaming clients.
src/…/models.pyDefines the public request and response shapes used by compatible clients.
src/…/models.pyDefines the OpenAI Responses request shape accepted at ingress.