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 API key and pick its API shape.
- Attach a routing rule from the FreeRouter key to the provider key.
- Integrate FreeRouter into your application.
Step 1 — Pick a gateway and sign up
1
Choose one gateway to start
Browse the supported gateways — OpenRouter has the broadest model catalog and is the common default; Vercel AI Gateway fits Vercel-hosted apps; Cloudflare AI Gateway adds edge caching and rate limiting. Sign up with the one that matches your criteria today. If you are just experimenting, weigh the free-credit offers: some gateways grant free credits to new accounts, which makes the first integration effectively free while you learn the shape of the API.
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 the gateway key as a provider key
2
Providers → Add provider
In the dashboard, open Providers, choose your gateway, and paste the API key from that gateway's own dashboard. FreeRouter encrypts it at rest, never returns it after save, and uses it only to forward your traffic. (Cloudflare also asks for your account ID and gateway name — the form's How to find this links show where each value lives.)
Step 3 — Create a FreeRouter key and pick a shape
3
API Keys → Create key
Open API Keys and create a key. Pick the API shape your code will speak: the default
openai shape works with the OpenAI SDKs and any OpenAI-compatible client, and the openrouter shape is an equally good pick — it accepts the same bodies plus OpenRouter's models fallback array. Copy the fr_live_... secret; it is shown only once. See API shapes if your stack already speaks Anthropic or Google.Step 4 — Attach a routing rule to the provider key
4
One target, priority strategy
On the new key, open the routing editor, keep the priority strategy, and add your provider as the only target. With a single target every request goes to your gateway — and when you add a second provider later, the same editor becomes your failover list or %-split. Hit the key card's Test key button to send a tiny live completion through the rule 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 such as openai/gpt-4o-mini. Copy-paste snippets for curl, Python, and Node — including streaming — live in Quickstart — Starting Fresh:
curl https://api.freerouter.com/v1/chat/completions \
-H "Authorization: Bearer $FREEROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "openai/gpt-4o-mini",
"messages": [{ "role": "user", "content": "Hello from FreeRouter!" }]
}'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.
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.