Model Remaps

A remap rewrites one incoming model to a fixed provider/model before a key's routing rule runs — migrate models, arbitrage cost, or canary a replacement with zero client changes.

What a remap is

Every remap lives on a FreeRouter key, next to its routing rule, and maps one incoming model id to one destination: a stored provider key plus a literal upstream model id. When a request arrives carrying that model, FreeRouter serves it from the destination instead of the rule's normal targets. Your application keeps sending the same model id it always has — the swap happens entirely inside FreeRouter.

Typical uses:

• Model migration — a gateway deprecates a model. Point the old id at its replacement; clients keep calling the old id until you update them (or forever).
• Cost arbitrage — serve a premium model id from a cheaper gateway's equivalent, pocketing the spread.
• Canary a replacement — send a slice of traffic to the new model (see percentages), compare quality, then cut over.
• Catch-all fallback — route every model without its own rule to one safe default (see matching).

How matching works

Matching is by exact incoming model id, trimmed and case-insensitive. Two extra rules decide ties:

• Use * as the incoming model to catch everything without its own rule — an exact match always beats the catch-all.
• If two rules could match (two exact rules can't — each model id appears at most once per key), the first listed wins.

Remaps apply to every API shape (OpenAI, OpenRouter, Anthropic, Google), because matching keys off the request's normalized model, not its wire format.

Percentages and fall-through

Each remap carries a percent (1–100, default 100), rolled per request. At 100% every matching request is rewritten. Below 100%, that share is rewritten and the rest falls through to the key's normal targets — so percent: 20 is a 20% canary with the other 80% following the rule untouched.

Example

Keep sending z-ai/glm-4.5-flash from your app: 20% is served from Darkbloom's model, 80% follows the normal rule, and every other model goes to the Vercel fallback:

{
  "strategy": "priority",
  "targets": [
    { "provider_key_id": "<openrouter-key-id>", "gateway": "openrouter" }
  ],
  "model_remaps": [
    { "match": "z-ai/glm-4.5-flash", "percent": 20,
      "provider_key_id": "<darkbloom-key-id>", "gateway": "darkbloom",
      "upstream_model": "qwen3.6-35b-a3b-vl-mtp-mxfp8" },
    { "match": "*",
      "provider_key_id": "<vercel-key-id>", "gateway": "vercel",
      "upstream_model": "fallback-model" }
  ]
}

Reliability: remaps fail safe

A remap never makes a key less reliable than its rule alone:

• If the destination errors retryably — 5xx, 429, or a timeout — FreeRouter fails over to the normal targets, exactly like ordinary failover.
• A definitive answer from the destination (success or a non-retryable client error) returns directly.
• A remap whose destination can't be served — deleted or disabled provider key, kill-switched or non-routable gateway — is treated as no match, and normal routing runs.

The upstream model is sent literally

The upstream_model id goes to the destination provider exactly as written — FreeRouter skips its usual model-id translation for remapped requests, because the remap is the mapping. In the dashboard's Model remaps editor, the upstream-model field offers the destination's live model list, fetched from that provider through your stored key, so ids are chosen, not typed.

Limits

• Max 20 remaps per key.
• Model ids (match and upstream) max 200 characters.
• Each incoming model id appears at most once per key (case-insensitive).
• Switched-off remaps still count toward the 20-per-key limit — delete, don't disable, what you won't use.

Setting remaps

Three writers, one stored shape:

• Dashboard — the per-key Model remaps editor on the API Keys tab, with the live upstream-model picker per destination row. Each row has an on/off switch: a switched-off remap stays saved but never matches, so you can stage a remap, test the base rule, and enable it later.
• Management API — model_remaps on PUT /api/v1/keys/:id/routing (or routing on POST /api/v1/keys). Destinations attach stored provider keys by UUID and go through the same workspace checks as targets. See PUT routing.
• MCP — the set_routing tool. See MCP Server.

Deleting a provider key strips it from remaps as well as targets; disabling keeps the references, so re-enabling restores them. After saving, the dashboard confirms the proxy cache reloaded the new rule.

Seeing remaps in flight

• The dashboard Logs tab marks remap-served attempts with a remap badge (expand a row for the attempt path).
• X-FreeRouter-Attempts counts the remap try like any other attempt.
• Request logs keep the client-requested model — the rewrite is visible in the attempt stages, not the top-line model.

Limitations

• Playground and Test-key don't evaluate remaps. Both exercise the key's base targets with a fixed test model, so a green test means base connectivity, not remap correctness. Verify remaps with live traffic and check the Logs tab for the remap badge.
• GET /v1/models ignores remaps — there's no model in the request to match on.