API reference.

Base URLs & auth

Mint a key in the dashboard (Agents → New agent — it looks like poly_… and is shown once). An OpenAI client points at /v1 and sends a Bearer token; an Anthropic client points at the root and sends x-api-key (it appends /v1/messages itself). The same poly_… key is accepted either way.

POST /v1/chat/completions

The OpenAI-compatible endpoint. The body is a standard Chat Completions request — a model, a messages array, and the OpenAI parameters polyrouter recognises (temperature, tools, response_format, …). Set stream: true for token streaming. The output cap may be sent as either max_tokens or max_completion_tokens — polyrouter accepts both inbound and emits the spelling each provider needs.

The recognised fields are model, messages, tools, tool_choice, parallel_tool_calls, temperature, top_p, max_tokens/max_completion_tokens, stop, stream, stream_options, response_format, reasoning_effort and n. Anything else (frequency_penalty, presence_penalty, seed, logprobs, logit_bias, user, store, service_tier, prediction, …) is silently dropped rather than forwarded. n > 1 is rejected with a 400 — the router always returns exactly one choice.

The model field is where routing begins. It takes four forms:

POST /v1/messages

The Anthropic-compatible endpoint. The body is a standard Messages request — a model, a required max_tokens, a messages array, and an optional system. Set stream: true for SSE. An Anthropic SDK targets the root base URL and appends /v1/messages itself; the same routing forms in the model field apply here too.

GET /v1/models

Returns everything routable by your key in the OpenAI list shape, so clients that fetch a model list for validation or pickers work unchanged. Authenticate exactly as for chat completions. The list is auto, then every tier key (always including default), then <providerId>:<model> for every model, plus the bare model id when it is unique across your providers. Every entry is {id, object:"model", owned_by:"polyrouter"} — no created, no permission.

Routing control headers

Two mechanisms steer routing without hard-coding a concrete model. Send the x-polyrouter-tier header to pin a tier, and/or set "model":"auto" in the body to engage the smart layers.

Streaming & fallback semantics

Set "stream": true and the response is a text/event-stream of SSE frames in the wire format of the client's protocol.

How long polyrouter waits is per-provider: first_byte_timeout_ms bounds time-to-first-token and — plus PROXY_EVENT_TIMEOUT_MARGIN_MS (500 ms) — the gap between streamed events, so this is the knob to raise for slow streaming models. idle_timeout_ms bounds the inter-chunk gap on non-streaming (buffered) reads only; raising it can never keep a slow stream alive. Each is 1 s–1 h; unset inherits the instance defaults PROXY_FIRST_EVENT_TIMEOUT_MS / PROXY_IDLE_TIMEOUT_MS, both 30 s. Raise the first-byte bound for research-class models — Deep Research, or Opus with thinking — whose long prefill would otherwise 503 and trip the provider's circuit breaker.

Errors

When a provider in the resolved tier's chain fails, polyrouter classifies the error. Every provider kind except bad_request is fallback-eligible — a fault at one provider should not fail the request, so the chain walks to the next entry. A terminal error returns immediately. Fallback only applies before the response commits — see Streaming.

Every /v1 failure is rendered in the caller's own envelope with a fixed, sanitized message — never the raw upstream body, request id, or credential.

A 500 with a null code is the unclassified-throw case — internal proxy error. Anthropic envelopes carry type and message only; the code column above appears in the OpenAI envelope.

Management REST API

The dashboard is driven by a REST API under /api/*. These use dashboard session auth (the Better Auth session cookie from signing in) — not poly_… agent keys, which authenticate only the inference endpoints under /v1. Disabling a user cuts both planes at once.