Connect any provider.

Provider kinds

Every provider is one of four kinds. All of them speak to the proxy through a single adapter interface — chat, chatStream, listModels, and testConnection — so the routing core stays protocol-agnostic.

Bring your own API keys

Add a provider with a name, a kind, a protocol, a base URL, and your API key. The base URL is checked against the SSRF guard and the key is encrypted before the row is written. Nothing is dialed at save time — hit Test on the provider card afterwards to run a live testConnection, then Sync models. The key is only ever decrypted at call time.

Connect a Claude or ChatGPT subscription

This section moved to its own page. Connecting a Claude Pro/Max or ChatGPT Plus/Pro subscription — the guided OAuth flow, presets and wire headers, refresh and rotation safety, and reauthorize — is now covered in full at Subscription routing.

A subscription is still one of the provider kinds listed above, and behaves like any other member of a tier chain once connected.

Models & pricing

polyrouter keeps a model catalog per provider and prices every request from a versioned pricing catalog. Sync a provider's /models list, edit prices per model on custom and local providers (API-key and subscription providers are priced from the catalog — the API rejects a manual price with 422), and let the daily refresh keep public prices current — without ever rewriting a recorded cost.

Output caps

The catalog carries more than prices: each entry's max_output_tokens is ingested from the same LiteLLM data. When a router-chosen chain runs, members whose known cap can't satisfy the request's ask are deferred behind members that can; if nothing in the chain can, the attempt is clamped to that member's own cap and finishes honestly with length instead of dying on a guaranteed provider 400. Both are recorded in the routing reason, as output_cap_deferred and output_cap_clamped. Which wire field the cap travels in is a separate per-provider setting — see Max-tokens spelling.

Max-tokens spelling

OpenAI's o-series and reasoning models require max_completion_tokens and reject the older max_tokens; many local and legacy gateways accept only max_tokens. Each provider carries a max_tokens_spelling setting so the outbound request always uses the field that provider expects. This setting applies to OpenAI-compatible providers only — Anthropic-compatible providers always emit max_tokens, and the ChatGPT Responses protocol drops the cap entirely (it is rejected upstream). This one is API-only — the dashboard's provider form does not offer it. Set it with maxTokensSpelling on POST /api/providers or PATCH /api/providers/:id; omitting the field keeps the stored value, and an explicit null is rejected with 400.

Upstream timeouts

Research-class models — Deep Research, Opus with thinking — can spend seconds to minutes on prefill before the first byte, then stream normally. A blanket 30-second first-event timeout would 503 them and trip the breaker. Set per-provider patience in the provider form's Advanced — patience for slow models block: First response (s) and Between chunks (s), in seconds, up to 3600. Leave a field blank to inherit — the placeholder reads 30 · instance default, read live from GET /api/providers/timeout-defaults rather than hard-coded. Raising patience here does not lift your client SDK's own timeout, which is the one bound the router can't reach.

Circuit breakers

Each provider has a Redis-backed circuit breaker, shared across instances, that stops hammering a failing upstream. State is keyed per provider — every model on that provider shares one breaker, so a failing upstream is skipped wholesale. Provider rows are owner-scoped, so one tenant's breaker never affects another's. Model-specific faults (unknown_model, bad_request) deliberately do not trip it.

• Generation-stamped. An incrementing generation counter means a stale completion from a previous generation can't corrupt current state under retries.
• Long streams survive. The half-open probe lease renews, so a legitimate long stream isn't mistaken for a hang.
• The probe is patient. A half-open probe runs with the member's first-byte and idle bounds doubled — min(2 × effective, 1 h) — and takes a lease wide enough to cover that silence, so a slow-but-healthy provider closes its breaker on the workload that tripped it. The multiplier is a constant, not a knob: per-provider first_byte_timeout_ms stays the tuning surface for heavy chains.
• Long-stall trips. Hung connects and stalled reads — bounded by the provider's first-byte / idle timeouts — record a failure atomically.
• Redis-authoritative. The server clock comes from Redis TIME to avoid instance skew; an in-memory store is the fallback if Redis is unavailable.

What a skipped member records

A chain member skipped by an open breaker is never dialed, so it must not read as an upstream failure. It records the pseudo-token skip@<model> in the request's routing reason — deliberately outside the provider-error taxonomy — alongside structured per-attempt metadata (attempt_failures: model, error kind, HTTP status, cascade leg; no free text). The requests inspector renders that as a Fallback trail — see Decision trail & inspector.

OpenRouter attribution

When a provider's base URL is on openrouter.ai, polyrouter adds two identity headers so it shows up in OpenRouter's app attribution.

HTTP-Referer: https://polyrouter.app
X-OpenRouter-Title: polyrouter