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 — models, tools, streaming, provider preferences — and the base URL is swappable, so your code barely changes. Five steps:

  1. Move your current OpenRouter API key into FreeRouter as a provider key.
  2. Create a FreeRouter API 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, including the models fallback array and provider preferences, so your bodies stay byte-identical.

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), 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