multi-router.aidocs

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:

FieldRequiredDescription
nameYesA label shown in the dashboard, up to 80 characters.
routing.providerYesThe provider id, such as anthropic or bedrock. See Supported Providers.
routing.modelYesThe model slug, such as anthropic/claude-sonnet-4.5. A custom endpoint takes any model the endpoint serves.
routing.provider_key_idYes, through the APIThe provider key, or Org-default key in the dashboard. See Provider Key.
routing.variantYes, except on custom endpointsThe variant, such as standard or geo. See Regions & Variants.
routing.regionYes through the API, except on custom endpointsThe region. When unset in the dashboard, Multi-Router selects one as described in Regions & Variants.
routing.model_sourceNorequest (default) or router. See Model source below.
prompt.system_message_modeYes, through the APIHow a bound prompt combines with the caller's system message: merge, override or fallback.
prompt.bindingNoA prompt applied to every request. See Router Settings.
descriptionNoA description shown in the dashboard, up to 500 characters.
parameter_defaultsNoDefault request parameters. See Router Settings.
observability.metadata_levelNoRequest metadata logging. See Router Settings.
observability.request_captureNoRequest 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.

ValueDashboard labelBehavior
requestUse request modelUses the caller's model with this router's provider, provider key and settings.
routerOverride with router's modelIgnores 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:

  1. Select New router, choose Static Router under Routers, and select Continue.
  2. Under Details, enter a Name, and optionally a Description, a Bound prompt and Tags.
  3. 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.
  4. 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.

Back to Routers

Support bot

enabledstatic
productionsupportAdd tag

Answers customer questions in the help center chat widget.

rt_9Hk3Ws7PzQ·created Mar 4, 2026·updated Sep 30, 2026
Disable
OverviewTrafficActivity

Aliases

Add
production

Model

Edit
Provideranthropic
Modelanthropic/claude-sonnet-4.5
Variantstandard
Provider keyAnthropic productionllpk_8Rn3Kx5WbT
Model source
Use request modelUse the caller's model with this router's provider, credential & preset

Prompt

Edit
SourceInline
Promptsupport-system(ip_5Gk2Nw8QvL)
Revision@latestnow rev 7
Prompt composition
MergeBoth router and caller system apply (default)

Request Logging

What this router records about its requests. Capped by the administrator's Storage Policy.

Edit
Request metadataFull Metadata
Request payloadsFailures only

Settings

Per-router configuration. Persisted in the router's versioned config blob.

Parameter defaults

Merged into a request when the caller doesn't set the field. The caller's value always wins. Leave blank to not default a field.

Cancel Save settings
The page of a static router: its alias, model and provider key, bound prompt, request logging and parameter defaults. Select to enlarge.

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.

Create a static routerbash
curl -X POST https://api.multi-router.ai/v1/routers \
  -H "Authorization: Bearer $MR_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "static",
    "name": "Support bot",
    "routing": {
      "provider": "anthropic",
      "model": "anthropic/claude-sonnet-4.5",
      "variant": "standard",
      "region": "global",
      "provider_key_id": "llpk_4Vd8Qm2RtL"
    },
    "prompt": { "system_message_mode": "merge" }
  }'
Response 201json
{
  "organization_id": "org_7Tq2Wd9KxP",
  "data": {
    "id": "rt_9Hk3Ws7PzQ",
    "object": "router",
    "etag": "\"1\"",
    "kind": "static",
    "name": "Support bot",
    "description": null,
    "enabled": true,
    "tags": [],
    "aliases": [],
    "rate_limits": { "rpm": null, "tpm": null },
    "routing": {
      "provider": "anthropic",
      "model": "anthropic/claude-sonnet-4.5",
      "variant": "standard",
      "region": "global",
      "provider_key_id": "llpk_4Vd8Qm2RtL",
      "model_source": "request"
    },
    "prompt": { "binding": null, "system_message_mode": "merge" },
    "parameter_defaults": {
      "temperature": null, "max_tokens": null, "top_p": null, "stop_sequences": [],
      "response_format": null, "tool_choice": null, "parallel_tool_calls": null,
      "reasoning_effort": null, "seed": null, "verbosity": null,
      "presence_penalty": null, "frequency_penalty": null
    },
    "observability": { "metadata_level": "inherit", "request_capture": "inherit", "payload_sample_pct": null },
    "created_at": "2026-10-01T12:00:00Z",
    "updated_at": "2026-10-01T12:00:00Z"
  }
}

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.

Move a static router to Bedrock in the EUbash
curl -X PATCH https://api.multi-router.ai/v1/routers/rt_9Hk3Ws7PzQ \
  -H "Authorization: Bearer $MR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "routing": {
      "provider": "bedrock",
      "provider_key_id": "llpk_8Nc4Xr6YwB",
      "variant": "geo",
      "region": "eu-central-1"
    }
  }'

Errors

Creating and changing a static router returns the following errors, each with status 400 unless noted:

ErrorCause
missing_fieldA required field, such as provider, model, region or system_message_mode, is missing.
missing_variantA router on a catalog provider names no variant.
unknown_providerThe provider is not supported.
model_not_foundThe model is not in the catalog.
invalid_variantThe provider does not offer the variant for the model. The message lists the valid variants.
region_not_servedThe variant is not offered in the region. The message lists the available regions.
provider_key_not_foundThe provider key is not in the organization.
provider_key_mismatchThe provider key belongs to a different provider.
provider_key_disabledThe provider key is disabled.
field_not_supported_for_kindThe body sets a field that does not apply to a static router, such as routing.routers.
unknown_fieldThe body contains an unknown or read-only field other than etag. members, tags and aliases also return it.
field_read_onlyA change sends etag.
invalid_jsonThe body is not valid JSON.
region_not_supportedMulti-Router cannot serve the region.
key_residency_mismatchThe OpenAI key's region differs from the router's region.
region_not_applicableA router on a custom endpoint sets a region for a model that is not a custom endpoint model.
region_not_offeredThe custom endpoint model does not offer the region.
invalid_payload_sample_pctThe payload sample percentage is above 100.
prompt_not_foundThe bound prompt does not exist.
pinned_value_not_foundThe 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.
OverviewAdaptive Router
Was this helpful?