switchback — part of the aimock family private · pre-launch

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:

same request, two surfaces json
# /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:

error envelopes json
# /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.

client setup js
const client = new OpenAI({
  baseURL: "https://openrouter.ai/api/v1",
  apiKey: process.env.OPENROUTER_API_KEY,
});
client setup js
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.

Client sends a real credential bring-your-own passthrough forwarded

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.

Client sends nothing, or a marked dummy router's key supported

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.

allowCallerKeys: false boolean optional default: true

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:

two upstreams, one slug, 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:

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.

request body json
{
  "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" }]
}
switchback.config.json, route excerpt json
{
  "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.

switchback.config.json json
{
  "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[]:

  1. gpt-4o on openai-direct, as gpt-4o. The hot path.
  2. gpt-4o on openrouter-fallback, as openai/gpt-4o. The catch.
  3. openrouter/auto on openrouter-fallback, verbatim via unlistedModels. openai-direct declares 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.

402 on /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:

account endpoints json
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- or latency-aware routing provider.sort partial

"price" and "latency" order legs. "throughput" does not exist here by choice. The latency window is per-process and starts empty. Scope and limits.

An account, a balance, a top-up platform not supported

No credits to buy, no auth flow, no rate-limit tiers. Caps are config you write and the router enforces locally.

Generation lookup and endpoint discovery /api/v1/generation, /api/v1/models/:id/endpoints not supported

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.

Platform keys on a non-OpenRouter host transforms, route dropped

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.

Legacy completions /v1/completions not supported

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