Upgrading to FreeRouter from OpenRouter in your existing app
The plan
The good news: this is quick and takes minimal effort. The OpenRouter API shape accepts your existing request bodies verbatim — model, tools, streaming, models, provider — and the base URL is swappable, so your code barely changes. Five steps:
models itself, on every gateway (on both /v1/chat/completions and /v1/responses, including MCP tool loops): candidates are tried in list order (your model first, or models[0] when model is omitted), and only when every target on the key fails to serve one — missing model, rejected parameter, rate limit, or upstream outage — does the next candidate run. X-FreeRouter-Model-Fallback names the model that answered, and Logs badges it too. OpenRouter-only request fields (transforms, plugins, route, usage) and model suffixes (:nitro, :floor, :exacto, :online, :extended) pass through untouched when OpenRouter answers, and are automatically stripped on any other gateway so failover never 400s or 404s (:free stays strictly on gateways that list a free variant so a free call never bills a paid gateway). provider names OpenRouter-internal providers, which have no equivalent here — the gateways on your key are the provider axis — so FreeRouter strips it and reports the drop as provider in X-FreeRouter-Dropped-Params and in Logs, alongside any field or suffix stripped for another gateway. For gateway-level control (order, split, cheapest) use the key's routing rule.
- Move your current OpenRouter API key into FreeRouter as a provider key.
- Create a FreeRouter key and set its shape to
openrouter. - Attach a routing rule that sends 100% of traffic to OpenRouter.
- Swap the OpenRouter key for the FreeRouter key in your app.
- Swap the OpenRouter base URL for the FreeRouter base URL.
Steps 1–3 happen in the dashboard with zero downtime: your app keeps calling OpenRouter directly until steps 4–5 cut it over. If anything looks wrong after the cutover, point the app back at OpenRouter while you investigate — the old key still works.
Step 1 — Store your OpenRouter key as a provider key
Do not delete or rotate the key at OpenRouter yet — your app still needs it until step 4. You are copying it into FreeRouter, not moving it away.
Step 2 — Create a FreeRouter key with the OpenRouter shape
openrouterprod-openrouter), and set its API shape to openrouter. Copy the fr_live_... secret — it is shown only once. The openrouter shape speaks your existing request format, so your bodies stay intact apart from models and provider, which FreeRouter handles itself (see the note above).Step 3 — Route 100% to OpenRouter
X-FreeRouter-Attempts response header will read 1 on healthy traffic. See Routing Rules for what happens when you add a second target later.Step 4 — Swap the key in your app
Replace the OpenRouter secret with your FreeRouter secret wherever your app configures it — almost always an environment variable, not code:
# Before
OPENROUTER_API_KEY="sk-or-v1-..."
# After
FREEROUTER_API_KEY="fr_live_..."
Keep the old variable set until you've verified step 5, so rollback is a one-line revert.
Step 5 — Swap the base URL
Point your client at FreeRouter instead of OpenRouter. Everything else — endpoints, bodies, streaming — stays identical:
# Before
base_url = "https://openrouter.ai/api/v1"
# After
base_url = "https://api.freerouter.com/v1"
For SDK-specific snippets (Python base_url, Node baseURL, streaming), see Quickstart — Migrating. If you pass OpenRouter app headers (HTTP-Referer, X-Title) or an Idempotency-Key, FreeRouter forwards them upstream.
Verify the cutover
- Send one request and check the
X-FreeRouter-Providerresponse header readsopenrouter. - Confirm
X-FreeRouter-Attemptsis1— no failover happened. - Watch the Usage & Spend dashboard for the request volume you expect, with the error rate near zero.
Why this setup is better
Day one, nothing behaves differently — and that is the point. But the router now sits between your app and the gateway, which buys you three things you didn't have:
- Swap backends any time. Add a second provider and flip the rule to priority with failover (OpenRouter primary, something else on outage) or a %-split (80/20 cost blend, canary, A/B) — no code deploy, the next request follows the new rule.
- Re-map models without touching code. A model remap rewrites one incoming model id to a fixed provider/model on the backend — retire a deprecated model, arbitrage a premium id onto a cheaper equivalent, or canary a slice of traffic — while your app keeps sending the same string.
- Or change nothing. Leave the single-target rule in place knowing you hold the option: when a gateway raises prices, drops a model, or degrades, the fix is a dashboard edit, not a migration project.