Upgrading to FreeRouter from OpenRouter in your existing app

You call OpenRouter in production today. This guide puts FreeRouter between your app and OpenRouter — same models, same request bodies — so you gain gateway optionality without a rewrite.

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:

OpenRouter fields and model suffixes FreeRouter runs 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.
  1. Move your current OpenRouter API key into FreeRouter as a provider key.
  2. Create a FreeRouter key and set its shape to openrouter.
  3. Attach a routing rule that sends 100% of traffic to OpenRouter.
  4. Swap the OpenRouter key for the FreeRouter key in your app.
  5. 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

1
Providers → Add provider → OpenRouter
In the dashboard, open Providers, choose OpenRouter, and paste the API key your app uses today. FreeRouter encrypts it at rest and uses it only to forward your traffic; it is verified on first use, not at save time, and never returned after you save it.

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

2
API Keys → Create key, shape openrouter
Open API Keys, create a key (label it something like prod-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

3
Attach a single-target priority rule
On the new key, open the routing editor, keep the priority strategy, and add your OpenRouter provider as the only target. One target means every request goes to OpenRouter — behavior identical to today — and the X-FreeRouter-Attempts response header will read 1 on healthy traffic. See Routing Rules for what happens when you add a second target later.
Sanity-check before touching code Use the key card's Test key button: it sends a tiny live completion through the key's own routing and shows which gateway answered. One small inference spend per click — cheaper than debugging your app against a misconfigured rule.

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-Provider response header reads openrouter.
  • Confirm X-FreeRouter-Attempts is 1 — 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.
Next guide Starting fresh with FreeRouter in a new app