Starting fresh with FreeRouter in a new app
The plan
There is no swap-out here — nothing to migrate. Instead you set things up in the order that keeps you flexible from day one:
- Pick an LLM gateway and sign up for it.
- Store that gateway's API key in FreeRouter as a provider key.
- Create a FreeRouter key and pick its API shape.
- Check the routing rule: the create form already routes the new key to your provider key.
- Integrate FreeRouter into your application.
Step 1 — Pick a gateway and sign up
openrouter/free lets you finish this guide before funding one.Don't overthink this choice. The whole point of the setup below is that picking gateway #1 commits you to nothing — gateway #2 joins later without touching your code.
Step 2 — Store your gateway's API key as a provider key
Paste the gateway's API key under Providers → Add provider; it is encrypted at rest and used only to forward your traffic. Walkthrough: Getting Started, step 2.
Step 3 — Create a FreeRouter key and pick a shape
Create the key under API Keys with the shape your code will speak — openai for the OpenAI SDKs and any OpenAI-compatible client, openrouter if your bodies already carry OpenRouter fields, anthropic or google for those SDKs (API shapes). The openrouter shape forwards your request body verbatim, so when OpenRouter serves the request it honors models and provider itself, exactly as today. FreeRouter's own routing reads only model: models and provider never decide which gateway is tried, and if the request fails over to a non-OpenRouter target those fields reach a gateway that ignores them. Express fallback with the key's routing rule instead — it works across every gateway. Walkthrough: Getting Started, step 3.
Step 4 — Check the routing rule
Tick your provider under Route this key to when you create the key (the Create a key link under a just-added provider key ticks it for you), so the key starts with a priority rule that has it as the only target — every request goes to your gateway. When you add a second provider later, the same editor on the key card becomes your failover list or %-split. Hit Test key once to see the gateway answer before you write integration code.
Step 5 — Integrate FreeRouter into your application
Point your client at https://api.freerouter.com/v1 with your fr_live_... key and a provider/model identifier — openrouter/free before the gateway account is funded, then anything it lists such as openai/gpt-4o-mini. The curl is in Quickstart — Starting Fresh; the per-SDK before/after (OpenAI, Anthropic, Vercel AI SDK, LangChain, LiteLLM, with streaming) is in Use your SDK.
Verify the setup
- Check the
X-FreeRouter-Providerresponse header names your gateway. - List valid model strings with
GET /v1/models. - Watch volume, errors, and latency on the Usage & Spend dashboard; any error code is explained in Troubleshooting.
Why this setup is powerful
Today you picked one gateway on today's criteria — price, catalog, latency, free credits. That decision is now reversible at any point, without a code deploy:
- Add, don't migrate. Sign up for another gateway, store its key under Providers, and add it to the same routing rule — as a failover backup, a %-split partner, or a canary at 5% while your current setup keeps serving the other 95%.
- Leave the current system intact. You can trial a new gateway on a small slice of traffic and compare cost, latency, and quality in the dashboard before committing — the evaluation key pattern in Routing Rules exists for exactly this.
- Re-route models, not code. When a model is deprecated or a cheaper equivalent appears, a model remap moves traffic at the router while your app keeps sending the same model string.