Migrate from OpenRouter to FreeRouter
The plan
The OpenRouter API shape accepts your existing request fields — model, tools, streaming — while FreeRouter itself consumes models (cross-gateway fallback) and strips provider before forwarding, and the base URL is swappable, so your code barely changes. Five steps:
- Create a FreeRouter account.
- Move your current OpenRouter API key into FreeRouter as a provider key.
- Create a FreeRouter key with the
openroutershape and route 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 — then test end-to-end and watch the Logs tab.
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 — Create your FreeRouter account
Step 2 — 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 3 — 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 accepts your existing fields; FreeRouter may rewrite model and strips models/provider before forwarding (reported via X-FreeRouter-Dropped-Params) — see What's different.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.
Step 4 — 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 5 — Swap the key and base URL, then verify
Replace the OpenRouter secret with your FreeRouter secret wherever your app configures it — almost always an environment variable, not code. Keep the old variable set until you've verified, so rollback is a one-line revert:
# Before
OPENROUTER_API_KEY="sk-or-v1-..."
OPENROUTER_BASE_URL="https://openrouter.ai/api/v1"
# After
FREEROUTER_API_KEY="fr_live_..."
FREEROUTER_BASE_URL="https://api.freerouter.com/v1"
SDK-specific form (Python base_url, Node baseURL) — everything else stays identical, and OpenRouter app headers (HTTP-Referer, X-Title) and Idempotency-Key are forwarded upstream. For curl, Python, and Node snippets see Quickstart — Migrating.
Verify end-to-end on the Logs tab
- Send one request and check the
X-FreeRouter-Providerresponse header readsopenrouter. - Confirm
X-FreeRouter-Attemptsis1— no failover happened. - Open the Logs tab in the dashboard and watch your request land: each row splits time-to-first-byte into Router, Upstream, and Duration columns, and expanding the row shows the attempt path — proof your traffic now flows through your own routing rules. See Usage & Spend for the full tour.
- Confirm request volume and a near-zero error rate on the Usage & Spend dashboard.
Copy-paste agent prompt
Rather click through this yourself? Paste the prompt below into your coding agent. It asks the agent to study the FreeRouter docs and your code, then come back with a migration plan for your review — not to start rewriting code.
I am currently using OpenRouter as my LLM gateway and would like to replace it with FreeRouter, with my existing OpenRouter account serving as a backend provider through FreeRouter (bring-your-own-key).
Explore the technical documentation at https://docs.freerouter.com as well as my code, then put together a well-thought-out migration plan for this objective so I can review and approve it. Do NOT make any code changes yet — present the plan first and wait for my approval.
Useful context for the plan:
- Current gateway: OpenRouter. Identify every place in my code that calls OpenRouter today and keep the diff minimal (the openrouter API shape accepts existing request fields — tools, streaming, transforms, plugins, usage, and :nitro/:floor/:online model suffixes, which pass through to OpenRouter and automatically strip on other gateways — while FreeRouter runs `models` itself (with or without a top-level `model`) as a cross-gateway fallback and strips `provider` before forwarding, reporting any stripped field or suffix in X-FreeRouter-Dropped-Params; gateway-level order, split, or cheapest belongs in the key's routing rule).
- FreeRouter essentials: base URL https://api.freerouter.com/v1; auth with a fr_live_... key; model ids look like provider/model (e.g. openai/gpt-4o-mini); each key has an API shape (use openrouter to match my client) and a routing rule (priority with 100% to OpenRouter, failover later).
- Setup the plan must cover: (1) creating a FreeRouter account, (2) adding my OpenRouter key as a BYOK provider (Providers → Add provider → OpenRouter), (3) creating a FreeRouter key with the openrouter shape and a routing rule sending 100% to OpenRouter, (4) swapping my app's base URL from https://openrouter.ai/api/v1 to https://api.freerouter.com/v1 and the key to the fr_live_... key, (5) end-to-end testing plus witnessing the routing on the Logs tab in the FreeRouter dashboard.
The plan should include: (1) every place in my code that calls OpenRouter today, (2) the exact config and code changes (base URL, key, model ids, API shape), (3) how to validate (the dashboard Test key button, the X-FreeRouter-Provider response header, GET /v1/models, the Logs tab), and (4) how to roll back if something breaks (point the app back at OpenRouter — the old key still works).
If you use OpenRouter's Responses beta
OpenRouter serves POST /v1/responses, and so does FreeRouter — same path, same bodies, same base-URL swap as the rest of this guide. Your key must be in the openai or openrouter shape, which it already is if you were calling chat completions.
Two differences worth knowing before you move Responses traffic across:
- Chaining needs a chain-capable gateway. FreeRouter supports
previous_response_idby pinning the follow-up to the provider that holds the state — but OpenRouter itself rejects bothstore: trueandprevious_response_id("Each response request is independent"), so an OpenRouter target cannot anchor a chain either way. Route to Ramp Router or Cloudflare if you need chaining, or resend the fullinputeach turn. See Chaining. - You gain gateways, not lose them. Routing a Responses key across several gateways works even where a gateway does not implement the endpoint — FreeRouter translates. Check
X-FreeRouter-Responses-Modeto see whether a given call was served natively or by translation.
Full detail in the API reference.
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.