Routing
Static Router
The base router type: one model on one provider, in a set variant and region, with a set provider key.
A static router sends every request to one model on one provider. It stores the model, the provider, the variant, an optional region and a provider key, which together identify one catalog entry and the account that pays for it, along with the prompt binding, parameter defaults and request logging applied to each request. Static routers are the members of fallback and weighted routers, and moving an application to a different model, provider or region requires a change to its static router and no change to the application.
Fields
A static router has the following fields:
| Field | Required | Description |
|---|---|---|
name | Yes | A label shown in the dashboard, up to 80 characters. |
routing.provider | Yes | The provider id, such as anthropic or bedrock. See Supported Providers. |
routing.model | Yes | The model slug, such as anthropic/claude-sonnet-4.5. A custom endpoint takes any model the endpoint serves. |
routing.provider_key_id | Yes, through the API | The provider key, or Org-default key in the dashboard. See Provider Key. |
routing.variant | Yes, except on custom endpoints | The variant, such as standard or geo. See Regions & Variants. |
routing.region | Yes through the API, except on custom endpoints | The region. When unset in the dashboard, Multi-Router selects one as described in Regions & Variants. |
routing.model_source | No | request (default) or router. See Model source below. |
prompt.system_message_mode | Yes, through the API | How a bound prompt combines with the caller's system message: merge, override or fallback. |
prompt.binding | No | A prompt applied to every request. See Router Settings. |
description | No | A description shown in the dashboard, up to 500 characters. |
parameter_defaults | No | Default request parameters. See Router Settings. |
observability.metadata_level | No | Request metadata logging. See Router Settings. |
observability.request_capture | No | Request payload logging. See Router Settings. |
Model source
Model source decides which model a static router uses when a request selects it with the x-mr-router header. A router named in the model field always uses its own model.
| Value | Dashboard label | Behavior |
|---|---|---|
request | Use request model | Uses the caller's model with this router's provider, provider key and settings. |
router | Override with router's model | Ignores the request's model and always uses this router's model. |
With Use request model, the request's model must be one the router's provider serves, and the router's variant and region apply to it; a request model that names a different provider or variant returns router_vendor_conflict or router_variant_conflict. A fallback or weighted router selected with the header always uses its members' own models.
Creating a static router in the dashboard
A static router is created on the Routers page in four steps:
- Select New router, choose Static Router under Routers, and select Continue.
- Under Details, enter a Name, and optionally a Description, a Bound prompt and Tags.
- Under Routing, select Choose model, pick the model's offering (provider and variant), and choose the Key and Region. The Resolves to panel shows the model id, price, billing account and context window of the choice. To call your own endpoint, select Use a custom endpoint instead, enter the Model, and choose the Custom endpoint key.
- Under Review & create, check each row and select Create router.
A static router can be created without a model and configured later; until it has one, its status is unconfigured and requests to it return router_misconfigured. On the router's page, the Model panel shows the Provider, Model, Variant, Region (when one is set), Provider key and Model source. Edit changes the model, provider, variant, region and key, and Model source changes in place.
Creating a static router with the API
POST /v1/routers creates a router. The routing goes in routing: provider, model, provider_key_id, and variant and region for every provider except custom endpoints; Prompt composition goes in prompt.system_message_mode. An optional Idempotency-Key header makes the create safe to retry. Keys do not expire, and a key that completed a request stays tied to it: a retry with the same key and request returns the original response, and a different request with the same key returns 409 idempotency_key_reused. A retry while the first request is still running returns 409 idempotency_in_progress. A failed create releases the key, so a corrected request can reuse it. dry_run=true validates the router without saving it. The response is 201 with the router, a Location header and its ETag. See Routers in the API Reference.
Changing a static router
PATCH /v1/routers/{id} changes a static router's name, description, enabled state, rate limits, routing, prompt, parameter defaults and request logging. A field left out keeps its value, nested objects such as routing merge field by field, and a change to routing includes routing.region, except on custom endpoints. An unknown or read-only field returns unknown_field, except etag, which returns field_read_only. members, tags and aliases also return unknown_field and change through their own endpoints. The router's id and type are fixed. An If-Match header with the router's ETag makes the change apply only if the router has not changed since it was read, and returns 412 version_conflict otherwise. Multi-Router validates the whole router after the change before saving it, and the change applies to the next request.
Errors
Creating and changing a static router returns the following errors, each with status 400 unless noted:
| Error | Cause |
|---|---|
missing_field | A required field, such as provider, model, region or system_message_mode, is missing. |
missing_variant | A router on a catalog provider names no variant. |
unknown_provider | The provider is not supported. |
model_not_found | The model is not in the catalog. |
invalid_variant | The provider does not offer the variant for the model. The message lists the valid variants. |
region_not_served | The variant is not offered in the region. The message lists the available regions. |
provider_key_not_found | The provider key is not in the organization. |
provider_key_mismatch | The provider key belongs to a different provider. |
provider_key_disabled | The provider key is disabled. |
field_not_supported_for_kind | The body sets a field that does not apply to a static router, such as routing.routers. |
unknown_field | The body contains an unknown or read-only field other than etag. members, tags and aliases also return it. |
field_read_only | A change sends etag. |
invalid_json | The body is not valid JSON. |
region_not_supported | Multi-Router cannot serve the region. |
key_residency_mismatch | The OpenAI key's region differs from the router's region. |
region_not_applicable | A router on a custom endpoint sets a region for a model that is not a custom endpoint model. |
region_not_offered | The custom endpoint model does not offer the region. |
invalid_payload_sample_pct | The payload sample percentage is above 100. |
prompt_not_found | The bound prompt does not exist. |
pinned_value_not_found | The pinned prompt revision or commit does not exist. |
router_not_found (404) | The router does not exist. |
policy_managed (409) | A tools policy created the router. |
version_conflict (412) | The If-Match ETag is stale. The response carries the current router. |
idempotency_in_progress (409) | A request with the same Idempotency-Key is still running. |
idempotency_key_reused (409) | The Idempotency-Key was used with a different request. |