Provider Routing

Onlist routes every request to a platform provider that has an active listing for the model you asked for. By default Onlist picks for you. To take control, add an optional provider object to the JSON request body. It is the one Onlist-specific extension to the OpenAI/OpenRouter wire format — everything else in your request is unchanged.

curl https://onlist.io/v1/chat/completions \
  -H "Authorization: Bearer YOUR_ONLIST_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o",
    "messages": [{"role": "user", "content": "Hello from Onlist"}],
    "provider": { "sort": "price" }
  }'

The provider field

A bare string is shorthand for pinning a single provider:

"provider": "alice-shop"

is exactly equivalent to:

"provider": { "only": ["alice-shop"] }

Provider slugs are bare and must match ^[a-z0-9_-]{1,64}$. There is no sub-slug addressing: a slug containing a / returns 400 provider_sub_slug_removed.

Field reference

Onlist honors a strict subset of OpenRouter's provider controls. Unsupported fields are accepted and silently ignored (never a 400) and reported in the X-Onlist-Warnings response header so you can detect them.

Honored fields

only — pin one provider

only pins the request to a single provider. Only the first element (only[0]) is honored. Any additional slugs are dropped and reported in X-Onlist-Warnings.

curl https://onlist.io/v1/chat/completions \
  -H "Authorization: Bearer YOUR_ONLIST_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o",
    "messages": [{"role": "user", "content": "Hi"}],
    "provider": { "only": ["alice-shop"] }
  }'

sort — price or throughput

sort chooses the ordering variant within the eligible pool.

"provider": { "sort": "price" }        // cheapest provider first
"provider": { "sort": "throughput" }   // fastest provider first

A model-slug suffix overrides this field: gpt-4o:floor forces price-first and gpt-4o:nitro forces throughput-first, regardless of any sort value you send. See Models for the suffix forms. Any other sort value (such as OpenRouter's latency) is ignored and reported in X-Onlist-Warnings.

order — try-order priority

order is an ordered list of provider slugs. Failover advances through them in the order you give. Setting order also suppresses sticky-channel affinity, so each request re-evaluates from the top of your list.

"provider": { "order": ["alice-shop", "bob-relay", "carol-ai"] }

allow and ignore — allowlist and denylist

allow is a request-level allowlist (merged with any token/account preferences). ignore is a request-level denylist. When a slug appears in both, deny wins.

"provider": {
  "allow": ["alice-shop", "bob-relay"],
  "ignore": ["carol-ai"]
}

If your allow/ignore rules exclude every viable provider, the request returns 503 no_provider_after_allow_deny.

allow_fallbacks — control failover

Failover across providers is on by default. Set allow_fallbacks: false to require the first selected provider and disable cross-provider failover. This also disables the top-level models[] fallback list (see below).

"provider": { "only": ["alice-shop"], "allow_fallbacks": false }

max_price — USD-per-token caps

max_price filters the pool to providers priced at or below your caps, in OpenRouter's native USD-per-token format (for example 0.0000025 = $2.50 per million tokens).

"provider": {
  "max_price": { "prompt": 0.0000025, "completion": 0.00001 }
}

• prompt and completion are enforced fail-closed: if no provider fits, the request returns 503 no_provider_in_max_price rather than silently overspending.
• image and request are not implemented (the scope is chat-only): they are ignored and reported in X-Onlist-Warnings.

The models[] fallback list

Independently of the provider object, you can send a top-level models array — the OpenRouter-compatible fallback list. Onlist tries each model in order, rewriting the body model for each attempt, until one succeeds.

{
  "model": "openai/gpt-4o",
  "models": ["openai/gpt-4o", "anthropic/claude-sonnet-4-20250514"],
  "messages": [{ "role": "user", "content": "Hi" }]
}

This list is gated by allow_fallbacks: with provider.allow_fallbacks: false, only the primary model is attempted and models[] is not used.

The X-Onlist-Warnings header

Whenever Onlist ignores a field or fires a routing notice, it reports it in the X-Onlist-Warnings response header. The value is a de-duplicated list joined by a comma and a space (, ). Parse it by splitting on , .

X-Onlist-Warnings: ignored: provider.sort, ignored: provider.zdr, ignored: provider.only[1:3]

Entries take the form ignored: <field> (a dropped field) or a notice such as cool_pool_exhausted_fallback_used. The header is present only when something was ignored or a notice fired — a clean request returns no warnings header. Always check it in development to confirm Onlist honored what you intended.

Next steps

• Privacy & data handling — What zdr and data_collection actually mean — provider-attested, not platform-verified.
• Errors — The 503 routing codes: no_provider_in_max_price, no_provider_after_allow_deny.
• Limits & headers — X-Onlist-Warnings, X-Onlist-Route-Id, Retry-After — and why there are no X-RateLimit-* headers.
• Models — Model id forms, onlist/auto, and the :floor / :nitro sort suffixes.