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.

curl https://<your-instance>/v1/chat/completions \
  -H "Authorization: Bearer poly_your_key" \
  -H "Content-Type: application/json" \
  -d '{"model":"auto","messages":[{"role":"user","content":"hi"}]}'

curl https://<your-instance>/v1/messages \
  -H "x-api-key: poly_your_key" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":256,"messages":[{"role":"user","content":"hi"}]}'

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:

curl https://<your-instance>/v1/chat/completions \
  -H "Authorization: Bearer poly_your_key" \
  -H "Content-Type: application/json" \
  -d '{"model":"auto","stream":true,"messages":[{"role":"user","content":"Summarize this diff in two sentences."}]}'

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.

curl https://<your-instance>/v1/messages \
  -H "x-api-key: poly_your_key" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":1024,"messages":[{"role":"user","content":"Write a haiku about load balancers."}]}'

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.

curl https://<your-instance>/v1/models \
  -H "Authorization: Bearer poly_your_key"

{"object":"list","data":[
  {"id":"auto","object":"model","owned_by":"polyrouter"},
  {"id":"default","object":"model","owned_by":"polyrouter"},
  {"id":"fast","object":"model","owned_by":"polyrouter"},
  {"id":"5d3c1f8a-…:gpt-5-mini","object":"model","owned_by":"polyrouter"},
  {"id":"gpt-5-mini","object":"model","owned_by":"polyrouter"}
]}

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.

curl https://<your-instance>/v1/chat/completions \
  -H "Authorization: Bearer poly_your_key" \
  -H "x-polyrouter-tier: fast" \
  -H "Content-Type: application/json" \
  -d '{"model":"auto","messages":[{"role":"user","content":"hi"}]}'

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.

data: {"id":"chatcmpl-…","object":"chat.completion.chunk",
       "created":1753430000,"model":"gpt-5-mini",
       "choices":[{"index":0,"delta":{"content":"Hel"},
                   "finish_reason":null}]}
data: {"choices":[{"index":0,"delta":{"content":"lo"},
                   "finish_reason":null}]}
data: [DONE]

event: message_start
event: content_block_start
event: content_block_delta
event: content_block_stop
event: message_delta
event: message_stop

How long polyrouter waits is per-provider: firstByteTimeoutMs 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. idleTimeoutMs bounds the inter-chunk gap on non-streaming (buffered) reads only; raising it can never keep a slow stream alive. Both are fields on POST/PATCH /api/providers, each 1 s–1 h, with null inheriting the instance defaults PROXY_FIRST_EVENT_TIMEOUT_MS / PROXY_IDLE_TIMEOUT_MS — both 30 s, and readable at GET /api/providers/timeout-defaults. 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.

{"error": {"message": "upstream rate limited",
           "type": "rate_limit_error",
           "code": "rate_limited"}}

{"type": "error",
 "error": {"type": "rate_limit_error",
           "message": "upstream rate limited"}}

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. Three endpoints sit outside the session plane on purpose: GET /api/health so orchestration can probe the container, GET /api/login-config so the sign-in screen knows which methods to render, and POST /api/invites/accept so an invitee can redeem a token before they have a session. GET /metrics is outside /api altogether — network-guard the port.