multi-router.aidocs

Routing

Overview

Routers hold the behavior and routing rules for your requests; API keys identify who sends them.

A router is a named object in an organization that decides how requests sent to it are served: which model and provider answer them, which provider key pays for them, where inference runs, and which prompt, parameter defaults and logging apply. An API key identifies the organization a request belongs to and what the caller is permitted to do, and carries no routing configuration. Every request therefore takes its behavior from the router it names, and changing a router changes the behavior for every caller of that router without new API keys or changes to application code.

Router types

Every router has a type, chosen when it is created, and each type encapsulates one routing behavior:

Router typeBehavior
Static routerSends every request to one model on one provider, in a set variant and region, with a set provider key.
Adaptive RouterServes the members of one model group, with rules on the feature, customer and requested model that choose a member, a fallback list or a weighted split.
Fallback routerTries its member static routers in order until one succeeds.
Weighted routerPicks one member static router per request at random, in proportion to its weight.
Claude ProxyServes Claude Code and Claude Desktop, forwarding requests in their native format to Anthropic, AWS Bedrock or Google Vertex.
Codex ProxyServes Codex CLI, forwarding OpenAI Responses requests to OpenAI.
Gemini ProxyServes Gemini CLI, forwarding Gemini requests to Google.

The dashboard groups static, adaptive, fallback and weighted routers under Routers, which route requests to a model, and the Claude Proxy, Codex Proxy and Gemini Proxy under Proxies, which pass existing client traffic through. An alias is a second name that points to a router and can be repointed; it is not a router type. See Alias.

Router ids and names

Every router has an id, assigned by Multi-Router when the router is created, in the form rt_ followed by 10 characters, such as rt_9Hk3Ws7PzQ. The id never changes, and requests and Traffic refer to a router by its id or by one of its aliases. A router also has a name, which is a label for the dashboard; a request selects a router by its id or alias, and two routers can share a name. Writes to /v1/routers/{id} take the router's id. Aliases are labels on a router, listed in its aliases field and managed with /v1/routers/{id}/aliases; see Alias.

Selecting a router

A request selects its router through the model field or the x-mr-router header:

RequestResult
"model": "multi-router/rt_9Hk3Ws7PzQ"The router with that id serves the request.
"model": "multi-router/production"The router that the alias production points to serves the request.
"model": "rt_9Hk3Ws7PzQ"The router with that id or alias serves the request.
x-mr-router: rt_9Hk3Ws7PzQThe header's router serves the request when the model field names no router.

A router named in the model field takes precedence over the header. When a static router is selected with the header, its Model source decides whether the request's model or the router's model is used; see Static Router. An Adaptive Router can be named in either place. A Claude Proxy, Codex Proxy or Gemini Proxy is selected with the header on its own endpoints; naming a proxy in the model field returns router_misconfigured.

Send a request to a routerbash
curl https://api.multi-router.ai/v1/chat/completions \
  -H "Authorization: Bearer $MR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "multi-router/rt_9Hk3Ws7PzQ",
    "messages": [{ "role": "user", "content": "Hello" }]
  }'

How a request flows through a router

The router is selected after the API key's rate limit and the request body are checked, and before budgets and the provider call. A static router serves the request itself; a fallback or weighted router hands it to one of its member static routers, and the member's model, provider key, region, prompt binding, parameter defaults and request logging apply. An Adaptive Router plans the request with its rules and sends it to the chosen members of its model group. Each response carries headers that name the provider, model and region that served it, how the router was selected, and how many members were tried. See the request lifecycle in Providers & Models.

Errors

Selecting a router returns the following errors:

ErrorStatusCause
router_not_found400No router or alias with that id exists in the organization.
router_disabled400The router, the alias, or the router the alias points to is disabled.
router_misconfigured400The router has no model, a fallback or weighted router has no members, or a proxy was named in the model field.
model_not_found404Any routing error for an API key limited to specific routers, including a router outside its list, so its responses reveal nothing about other routers.
Custom Models & PricingStatic Router
Was this helpful?