OpenRouter migration
The router serves an OpenRouter-shaped surface at /api/v1/*, so for a lot of
clients this is a base-URL swap and nothing else. Three things look like they carry over
and don't, and one of them fails silently. Read those first.
Warning
provider.sort supports "price" and "latency", and
both order legs for real. It does not support
"throughput", and it is not going to — see
what sort does and does not cover, including the
one case that is still silent.
What a base-URL swap actually gets you
The router exposes the same routed path under two surfaces, and the surface is derived
from the path prefix: anything beginning /api/ is treated as the
OpenRouter-shaped surface, and its responses run through an OpenRouter post-pass. So
/v1/chat/completions and /api/v1/chat/completions route
identically and differ only in the envelope they hand back.
The differences on the same request, captured from a running router:
# /v1 body
{"id":"chatcmpl-x", …, "choices":[{…"finish_reason":"stop","native_finish_reason":"stop"}], …, "provider":"openai"}
# /api/v1 body
{"id":"gen-x", …, "choices":[{"index":0,"message":{"role":"assistant","content":"pong","reasoning":null},"finish_reason":"stop","native_finish_reason":"stop"}], …, "provider":"openai","system_fingerprint":null,"service_tier":null}
Streaming follows the same split: /v1 chunks carry
chatcmpl-<hex> ids, /api/v1 chunks carry
gen-<hex> ids. Both were verified against a live router.
Error envelopes differ too, which matters if you parse them:
# /v1
{"error":{"message","type","code","metadata"?}}
# /api/v1 — the OpenRouter envelope
{"error":{"code","message","metadata"?}}
If your client already handles OpenRouter's {code, message, metadata} shape,
stay on /api/v1 and it keeps working. If you are rewriting the client anyway,
/v1 gives you the OpenAI-shaped envelope with a type field.
Step 1 — swap the base URL
Request bodies need no changes for the swap itself: model,
models[] and provider{} are all read on the way in.
const client = new OpenAI({
baseURL: "https://openrouter.ai/api/v1",
apiKey: process.env.OPENROUTER_API_KEY,
});
const client = new OpenAI({
baseURL: "http://127.0.0.1:4011/api/v1",
apiKey: "unused", // the router holds the real keys — see below
});
What happens to the key your client sends
There are exactly three postures here, and the one you get depends on what the client
sends and on the upstream's allowCallerKeys. Pick deliberately rather than
discovering it.
If the upstream's allowCallerKeys is not false, that
credential is forwarded to the upstream verbatim. Your callers' keys reach the
provider, and the router's own configured key is not used for that request.
An absent credential, or one carrying the sk-aimock- dummy marker,
falls back to the upstream's configured key. This is what
apiKey: "unused" above relies on.
Set on the upstream, this forces the router's own key unconditionally and a
caller-supplied credential is never used. It is a sibling of
auth on the upstream object, not a key inside it. See
Security for the credential rules and
Configuration for where it sits.
The OpenRouter-shaped endpoints
Four endpoints, and that is the whole surface. Anything else under
/api/v1 is a structured 404.
| Endpoint | Available | Behavior here |
|---|---|---|
| POST /api/v1/chat/completions | Yes | Routed chat, in the OpenRouter envelope. |
| GET /api/v1/models | Yes |
OpenRouter model objects, one per routed slug in your config: the keys of
route.models. Not a catalog of everything a provider offers.
|
| GET /api/v1/key | Partial |
Key metadata synthesized from the live global budget scope. The
rate_limit block is a static compatibility stub and
label is a fixed literal. See
Credits become budget caps.
|
| GET /api/v1/credits | Yes |
total_credits and total_usage, also synthesized from the
live global budget scope.
|
| GET /api/v1/generation | No | Structured 404. There is no per-generation lookup. |
| GET /api/v1/models/:id/endpoints | No | Structured 404. |
| /api/v1/auth/* | No | Structured 404. There is no account, so there is no auth flow. |
| /v1/completions | No | Permanent 404 on both surfaces, verified. The legacy completions shape is not implemented. |
Embeddings live on the OpenAI surface only, at /v1/embeddings, and route
through the same engine, but only to openai-compat upstreams, with no
streaming. A leg to any other dialect is skipped silently.
Field-by-field compatibility
What the router does with each OpenRouter-shaped field you are already sending. "Partial" here always means something real happens but not the thing you would assume.
| Field | Support | What the router does with it |
|---|---|---|
| model | Partial |
Read, but it feeds route matching and the report's
requested_model only. On its own it does not select
what gets called. See below.
|
| models[] | Yes |
A non-empty models[] becomes the candidate chain, as
[model, ...models], overriding the route's own chain.
|
| provider.order | Yes |
Front-loads the matching upstreams, preserving their relative order. A
request-level order replaces the route's.
|
| provider.only | Yes | Whitelist. Config and request compose as an intersection. |
| provider.ignore | Yes | Blacklist. Config and request compose as a union. |
| provider.allow_fallbacks | Yes |
false truncates the chain to the primary candidate's legs. Any
explicit false wins, whichever side set it.
|
| provider.sort | Partial |
"price" orders legs by catalog price; "latency" orders
them by this process's observed TTFT. "throughput" and the
percentile-object forms are refused at load.
What is and is not covered.
|
| transforms | Partial |
Forwarded verbatim only to an upstream whose profile is
exactly "openrouter". Everywhere else it is dropped with a
dropped_params annotation.
|
| route | Partial | Same rule as transforms. |
| reasoning | Partial |
Kept on openai-compat legs, translated into Anthropic extended
thinking on an anthropic-messages leg, and dropped on
gemini-generate, bedrock-converse and
cohere-chat.
|
| HTTP-Referer | Partial |
Not forwarded by default. The caller-header allowlist is
content-type and accept only, so you must name it in the
upstream's forwardHeaders.
|
| X-Title | Partial | Same rule as HTTP-Referer. |
| Caller Authorization | Partial | Forwarded verbatim when it is a real credential and the upstream permits caller keys; otherwise the upstream's own configured key is used. |
| usage.cost | Yes |
On a leg to an openrouter-profile upstream, a non-negative finite
usage.cost is taken verbatim as that leg's actual cost. Its
cost_details and is_byok siblings are extracted too.
|
How provider{} composes
Config-level provider{} lives on the route; a request-level
provider{} narrows it and never widens it. Request-side
values are coerced defensively: only string arrays survive, and a sort value
must be exactly "price" or "latency" to be accepted at all (and
then does nothing).
Those names mean your upstreams
Warning
In order, only and ignore, the strings name
upstreams you declared in your own config, not entries in OpenRouter's
provider pool. A config carried across verbatim, still naming OpenRouter's providers,
will filter against names that do not exist and will not do what it used to. Rename them
to your upstream keys as part of the move.
What sort covers, and what it never will
sort: "price" orders a candidate's legs by catalog price, cheapest first. An
unpriced leg sorts last rather than being guessed at. sort: "latency" orders
them by the rolling mean TTFT this process has actually observed per upstream.
Proven on this build, not inferred from reading:
sort: "price" result
# route provider: {"sort": "price"}
# the SECOND-declared upstream serves a 100x cheaper model
x-switchback-upstream: cheap-direct # cheapest first, against declaration order
Two honest limits on "latency". The window is per process and starts
empty, so until an upstream has served at least one streaming request the router has no
measurement for it and falls back to declaration order. And TTFT is recorded only from
legs that reached their streaming commit point — a non-streaming request contributes no
sample. The window is a hint, deliberately not shared across a fleet.
sort: "throughput" is not supported, and that is a deliberate refusal rather
than a gap we intend to close. OpenRouter ranks endpoints against traffic from every
customer on their platform; a single self-hosted process only ever sees its own. An
imitation built on one instance's samples would be measurably worse while looking like the
same feature, so we do not ship one. Express throughput preferences as declaration order
or provider.order.
Warning
The two paths differ, and one of them is still silent. In the
config, a sort value other than "price",
"latency" or null is a load-time failure — the router refuses
to start and names the key. In a request body, an unrecognised
sort value is dropped and the request routes in declaration order,
without an annotation in the routing report saying so. So a client sending
{"sort": "throughput"} gets no error and no evidence. Annotating that drop
is open work; until it lands, treat request-level sort as strictly
"price" or "latency".
model alone does not pick the model
OpenRouter routes what you ask for. Here, the matched route's chain is what
gets routed, unless the request carries a non-empty models[]. A
request for a slug that is not in the chain does not fail. It quietly runs the chain.
Verified: against a route whose chain is ["gpt-4o"], a request
for {"model":"nope"} returned 200, served by the gpt-4o leg.
If your client varies model per request, and most migrating clients do, then
you have two honest options and you need one of them:
-
Send
models[]on every request. The candidate chain becomes[model, ...models], so the request decides. -
Declare per-model routes and select them with
match.modelsglobs. Note the asymmetry:match.modelsentries are globs, whilematch.surfaceis an exact path list. It is easy to get those backwards.
Author-prefixed slugs
OpenRouter slugs carry an author prefix (openai/gpt-4o) that direct provider
APIs do not accept. For a slug you have not mapped in route.models, each
upstream opts in via its own unlistedModels rule, in upstream declaration
order:
unlistedModels |
Effect on an unmapped slug |
|---|---|
| "verbatim" | Passed through unchanged. This is what makes an OpenRouter upstream a working catch-all for every slug you never mapped. |
| "strip-author" |
Keeps the portion after the first /, so
openai/gpt-4o reaches the upstream as gpt-4o. This is
how an unchanged OpenRouter-style client reaches a direct provider upstream.
|
| "none" | Unset or "none": the upstream serves no unmapped slugs at all. |
A slug that is mapped in route.models gets one leg per declared
upstream and only those; unlistedModels is not consulted for it. A candidate
that maps nowhere contributes zero legs and is skipped silently; a whole chain that maps
nowhere is a 404. Routing has the full expansion order.
Before and after: the same intent, translated
A request body you send OpenRouter today, and the config that expresses the same intent here. Note what survives, what moves from the request into the config, and what has no landing place.
{
"model": "openai/gpt-4o",
"models": ["openai/gpt-4o", "anthropic/claude-sonnet-4.5"],
"provider": {
"order": ["OpenAI", "Azure"],
"ignore": ["DeepInfra"],
"allow_fallbacks": true,
"sort": "price"
},
"transforms": ["middle-out"],
"messages": [{ "role": "user", "content": "ping" }]
}
{
"chat-default": {
"match": { "surface": ["/api/v1/chat/completions"] },
// "order"/"ignore" now name YOUR upstreams, not a provider pool
// cheapest-first means: declare it first. "sort" has no equivalent.
"chain": ["gpt-4o", "claude-sonnet-4-5"],
"provider": {
"order": ["openai-direct"],
"ignore": [],
"allow_fallbacks": true
},
"policy": {
"advanceOn": ["rate_limited", "server_error", "timeout_ttft", "silent_empty"]
}
}
}
transforms is gone from the "after" config because it is a request-body key,
not a config key. Keep sending it, and it reaches an openrouter-profile
upstream unchanged and is dropped with an annotation anywhere else.
advanceOn is the part with no OpenRouter equivalent at all: you name which
failure classes are allowed to move the chain, and everything you do not name surfaces to
the client instead. Add translated_bad_request to it whenever a non-openai-compat
upstream is in a chain, or a content-expressibility skip will surface rather than fall
through. Providers has the per-dialect detail.
Keeping OpenRouter as a fallback upstream
The other migration shape, and the one most people actually want first: send the hot path
straight to the provider, and keep OpenRouter behind it as the thing that catches a bad
window. It is an ordinary upstream with the openrouter profile, which is what
teaches the router that host's error grammar, retry headers,
reasoning_details passthrough, and usage.cost extraction.
{
"route": {
"listen": { "host": "127.0.0.1", "port": 4011 },
"upstreams": {
"openai-direct": {
"baseURL": "https://api.openai.com/v1",
"dialect": "openai-compat",
"profile": "openai",
"auth": { "env": "OPENAI_API_KEY" }
},
"openrouter-fallback": {
"baseURL": "https://openrouter.ai/api/v1",
"dialect": "openai-compat",
"profile": "openrouter",
"auth": { "env": "OPENROUTER_API_KEY" },
"unlistedModels": "verbatim",
"forwardHeaders": ["HTTP-Referer", "X-Title"]
}
},
"models": {
"gpt-4o": {
"openai-direct": "gpt-4o",
"openrouter-fallback": "openai/gpt-4o"
}
},
"routes": {
"chat-default": {
"match": { "surface": ["/v1/chat/completions", "/api/v1/chat/completions"] },
"chain": ["gpt-4o", "openrouter/auto"],
"provider": { "allow_fallbacks": true },
"policy": {
"advanceOn": ["rate_limited", "server_error", "timeout_ttft", "silent_empty"],
"respectRetryAfter": { "capMs": 5000 },
"maxTotalAttempts": 4
}
}
},
"budget": {
"global": { "dollars": "500.00", "window": "monthly" },
"perUpstream": { "openrouter-fallback": { "dollars": "25.00", "window": "monthly" } }
}
}
}
Read that config back as a leg order. For a request carrying no models[]:
-
gpt-4oonopenai-direct, asgpt-4o. The hot path. -
gpt-4oonopenrouter-fallback, asopenai/gpt-4o. The catch. -
openrouter/autoonopenrouter-fallback, verbatim viaunlistedModels.openai-directdeclares no rule, so it contributes nothing here.
Two details make this topology behave the way you want. Advancing to a different upstream
never waits: the backoff and Retry-After sleeps only apply to retrying the
same leg, and Retry-After is always capped (a hint above the cap advances
immediately instead of sleeping). And maxTotalAttempts counts
dispatched attempts only, so skipped legs are free and cannot starve a reachable
leg further down the chain.
What the fallback leg costs you
Warning
When that fallback fires, the intermediary is back for that request: its fee, an extra network hop, and a data path that leaves your process and crosses a third party. The whole point of the hot path being direct is that none of those apply to it; none of that is true of the fallback leg. This topology does not remove the middleman, it bounds him.
So bound him explicitly. The perUpstream cap above fences how much spend can
route back through the intermediary, independently of your global cap, and it is enforced
before dispatch rather than reported afterwards. And every such leg is visible rather than
inferred: the per-request routing report names the upstream, the
provider, and the cost of each leg, and the
switchback report summarizer aggregates them as byUpstream wins
and legs plus spend.byUpstream. If you cannot say what fraction of traffic
took the fallback last week, that is a question with an answer. See
Observability.
One boundary worth knowing before you rely on it: failover is pre-first-token only. Once a streaming response commits, the engine never re-routes, and a later failure arrives in the stream as an error event rather than moving to the fallback.
Credits become budget caps
There is no balance to top up here. A credit balance becomes explicit caps you write down,
at global, route:<name> and
upstream:<name> scope, reserved before dispatch and settled from real
usage afterwards. A crossed cap is a 402, the same status OpenRouter uses
for credit exhaustion, so client code that already handles that path keeps working.
/api/v1, formatted json
{
"error": {
"code": 402,
"message": "budget cap reached for scope \"global\" (monthly); …",
"metadata": {
"reason": "budget_exhausted",
"scope": "global",
"window": "monthly",
"limit_kind": "dollars",
"limit": "0.000001",
"spent": "0.000000",
"remaining": "0.000001",
"resets_at": "2026-08-01T00:00:00.000Z"
}
}
}
The two account-level endpoints are synthesized from the
global scope specifically. Per-route and per-upstream caps
are leg-scoped and show up on chat responses instead, not here. Captured against a
"5.00" global cap:
GET /api/v1/key → {"data":{"label":"sk-or-v1-aimock", …,"limit":5,"limit_remaining":5,"usage":0, …}}
GET /api/v1/credits → {"data":{"total_credits":5,"total_usage":0}}
With no dollar cap on the global scope, limit and
limit_remaining are null and total_credits is
0. Two fields on /api/v1/key are shape-compatibility stubs
rather than live data, and you should not build on them: the rate_limit block
is static (requests: -1, interval: "10s", plus a note that it is
deprecated and safe to ignore), and label is the fixed literal
sk-or-v1-aimock. There are no rate-limit tiers to migrate.
Only two models have prices out of the box
Danger
The bundled price catalog contains openai/gpt-4o and
anthropic/claude-sonnet-4-5, and nothing else. Under a dollar cap with the
default allowUnpriced: false, every other model is
refused at reserve time. A migration that sets a cap and a wide model
list will fail closed on most of it. Add priceMap entries, keyed
<upstreamModelId>@<upstream>, using the id the
upstream knows, not your client-facing slug. A key that does not match raises
no error at all: the overlay is silently ignored and the leg is refused as unpriceable.
Budgets has the reserve-and-settle rules.
What is not here
Stated plainly, so you find it now rather than in an incident.
"price" and "latency" order legs.
"throughput" does not exist here by choice. The latency window is
per-process and starts empty. Scope and limits.
No credits to buy, no auth flow, no rate-limit tiers. Caps are config you write and the router enforces locally.
Structured 404. The per-request decision trace is the local equivalent of a generation lookup: it records every leg tried, why each was abandoned, and what it cost.
Dropped anywhere except an openrouter-profile upstream, including plain
OpenAI and every translated dialect, because those hosts would reject them. When a
platform feature stops working after the move, check dropped_params in
the report first.
Permanent 404 on both surfaces. Verified, not an oversight of configuration.
Note
The repository is private and pre-launch, and the router prints an experimental notice on every start: config shape and behavior may change without notice. Plan the migration accordingly, and see Install for how to get a runnable build.
Where to go next
- Configuration Every field of the config you just wrote, with its validation and its default.
- Routing Leg expansion, the failure taxonomy, and exactly what advances a chain.
- Budgets Reserve and settle, the scopes and windows, and what the 402 carries.
- Providers Which params and content forms survive each dialect, and which skip a leg.