Migrate from OpenRouter to FreeRouter

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. Prefer to delegate? Copy the agent prompt below into your coding agent.

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:

  1. Create a FreeRouter account.
  2. Move your current OpenRouter API key into FreeRouter as a provider key.
  3. Create a FreeRouter key with the openrouter shape and route 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 — 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

1
Sign up with Google or email + OTP
Go to app.freerouter.com and sign up with Google or with your email address plus a one-time passcode (OTP). Full walkthrough: Getting Started.

Step 2 — Store your OpenRouter key as a provider key

2
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 3 — Create a FreeRouter key with the OpenRouter shape

3
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 accepts your existing fields; FreeRouter may rewrite model and strips models/provider before forwarding (reported via X-FreeRouter-Dropped-Params) — see What's different.
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.

Step 4 — Route 100% to OpenRouter

4
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 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-Provider response header reads openrouter.
  • Confirm X-FreeRouter-Attempts is 1 — 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_id by pinning the follow-up to the provider that holds the state — but OpenRouter itself rejects both store: true and previous_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 full input each 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-Mode to 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.
Marketing overview Prefer the short version? freerouter.com/migrate-from-openrouter.html summarizes this guide with the same agent prompt.
Related guide Upgrading to FreeRouter from OpenRouter in your existing app