multi-router.aidocs

API Reference

Routers

Creating, reading, changing, enabling, disabling and deleting routers, and managing their members, aliases and tags.

The routers endpoints manage an organization's routers of every type, with their members, aliases and tags. Reading needs routers:read, changing needs routers:write, and deleting needs routers:delete. Writes take the router's canonical rt_ id. Each router type's behavior is described in Routing. Guardrails, caching and telemetry are attached to a router through Integrations.

Endpoints

MethodPathDescriptionScope
GET/v1/routersList routers, newest change first. Filter with kind and tag.routers:read
POST/v1/routersCreate a router. Returns 201. Accepts dry_run and an Idempotency-Key.routers:write
GET/v1/routers/{id}Get one router, with its tags and aliases.routers:read
PATCH/v1/routers/{id}Change the fields sent. Enables and disables a router through enabled. Accepts dry_run.routers:write
DELETE/v1/routers/{id}Delete a disabled router. Accepts dry_run.routers:delete
GET/v1/routers/{id}/membersList the members of a fallback or weighted router, in order.routers:read
POST/v1/routers/{id}/membersAdd a member: router_id, weight for weighted routers, and an optional zero-based position. Returns 201.routers:write
PATCH/v1/routers/{id}/members/{key}Change a member's weight or position. The key is the member's router id.routers:write
DELETE/v1/routers/{id}/members/{key}Remove a member.routers:delete
GET/v1/routers/{id}/routesList a Claude Proxy's resolved routes: model, provider, variant, region and provider key.routers:read
POST/v1/routers/{id}/aliasesAttach an alias label, sent as alias. Returns 201, or 200 when the alias is already here or moves from another router.routers:write
DELETE/v1/routers/{id}/aliasesDetach the alias named in the alias query parameter.routers:delete
GET/v1/routers/{id}/tagsList the router's tags.routers:read
POST/v1/routers/{id}/tagsAdd a tag, sent as tag. Returns 201, or 200 when the router already has it.routers:write
DELETE/v1/routers/{id}/tags/{key}Remove a tag.routers:delete

Member and tag writes are conditional on the router's ETag and accept dry_run. Alias writes take no If-Match.

Kinds

The kind field sets what a router is, and is fixed once created:

KindRouter typeCreate with
staticStatic routerrouting.provider, routing.model, routing.provider_key_id, routing.region for every provider except custom, routing.variant for catalog providers, and prompt.system_message_mode.
fallbackFallback routerrouting.routers: 1 to 50 static router ids, in order.
weightedWeighted routerrouting.routers: 1 to 50 objects with router_id and a positive weight.
claude_proxyClaude ProxyOptionally routing: route, region, credential_source, provider_key_id, model_group, model_keys and disabled_models. See Claude Proxy.
codex_proxyCodex ProxyOptionally routing.provider_key_id: an enabled OpenAI key of the organization. Left out, each caller's own OpenAI key is passed through. See Codex Proxy.
gemini_proxyGemini Proxyrouting.provider_key_id: an enabled Gemini key of the organization. See Gemini Proxy.
adaptive_routerAdaptive Routerrouting.model_group and routing.adaptive: credentials, and optionally member_keys, disabled, prompts, rules and default. See Adaptive Router.

Every kind takes optional name, description, tags and rate_limits (rpm and tpm). A create always makes an enabled router: enabled is accepted only as true, and false returns 400 invalid_field. Disable a router with PATCH. Static routers also take parameter_defaults, and static routers, Adaptive Routers and proxies take observability. An Adaptive Router is created without tags; add them afterwards. An alias is a label on a router, not a router: attach it with the aliases endpoint, and callers name it in the model field or in x-mr-router. See Alias.

Creating a static router

Requestbash
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-01T17:02:11Z",
    "updated_at": "2026-10-01T17:02:11Z"
  }
}
Create a fallback 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": "fallback", "name": "Support with backup", "routing": { "routers": ["rt_9Hk3Ws7PzQ", "rt_2Lw6Yd8NcV"] } }'

Router fields

FieldType
idstring
The router id. Fixed.
objectstring
Always router.
etagstring
The quoted version, for If-Match.
kindstring
static, fallback, weighted, claude_proxy, codex_proxy, gemini_proxy or adaptive_router. Fixed.
namestring
A display name.
descriptionstring or null
A description.
enabledboolean
Whether the router serves requests.
tagsarray
Tag names. Changed through the tags endpoints.
aliasesarray
Alias labels on this router. Changed through the aliases endpoints.
rate_limitsobject
rpm and tpm, or null for no limit.
routingobject
Static routers: provider, model, variant, region, provider_key_id and model_source. Fallback and weighted routers: routers. Proxies: route, region, credential_source, provider_key_id, model_group, model_keys and disabled_models; a Codex or Gemini Proxy sets only provider_key_id, and credential_source reports organization or developer. Adaptive Routers: model_group and adaptive.
promptobject
Static routers: the bound prompt in binding, and system_message_mode. See Prompt Binding.
parameter_defaultsobject
Static routers: default request parameters.
observabilityobject
Static routers, Adaptive Routers and proxies: metadata_level, request_capture and payload_sample_pct.
routesarray
Claude Proxies: the resolved routes, read-only.
created_atstring
When the router was created.
updated_atstring
When the router last changed.

See Static Router, Router Settings and Prompt Binding for every setting.

Changing a router

PATCH /v1/routers/{id} changes only the fields sent: name, description, enabled, rate_limits, routing, prompt, parameter_defaults and observability. Nested objects merge field by field. A change to a static router's routing includes routing.region, except on custom endpoints. Fallback and weighted members change through the members endpoints. A field that does not apply to the kind returns field_not_supported_for_kind. On an Adaptive Router, routing.adaptive is replaced as a whole document rather than merged, and a stale If-Match returns 412 with the current router. On a Codex Proxy or Gemini Proxy, routing.provider_key_id is the only routing field; a key that is not an enabled key of the proxy's provider returns 400 invalid_provider_key_id.

Change a router's modelbash
curl -X PATCH https://api.multi-router.ai/v1/routers/rt_9Hk3Ws7PzQ \
  -H "Authorization: Bearer $MR_API_KEY" \
  -H 'If-Match: "1"' \
  -H "Content-Type: application/json" \
  -d '{ "routing": { "model": "anthropic/claude-opus-5", "region": "global" } }'
Disable a routerbash
curl -X PATCH https://api.multi-router.ai/v1/routers/rt_9Hk3Ws7PzQ \
  -H "Authorization: Bearer $MR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": false }'
Attach an aliasbash
curl -X POST https://api.multi-router.ai/v1/routers/rt_9Hk3Ws7PzQ/aliases \
  -H "Authorization: Bearer $MR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "alias": "production" }'

Attaching an alias that is on another router moves it in one step, and the response names the previous router in moved_from. A router is deleted only once it is disabled and has no aliases.

Errors

The routers endpoints return these errors beyond the common ones:

CodeStatusMeaning
router_not_found404The id matches no router.
missing_field400A required field is missing, such as routing.region on a static router.
missing_variant400A static router on a catalog provider names no variant.
field_not_supported_for_kind400A field does not apply to the router kind, such as prompt on a fallback router.
unknown_provider400The provider is unsupported.
model_not_found400The model is absent from the catalog.
invalid_variant400The model has no offering with that variant.
region_not_offered400The offering has no such region.
provider_key_not_found400The provider key is absent from the organization.
provider_key_disabled400The provider key is disabled.
provider_key_mismatch400The provider key belongs to another provider.
invalid_member400A member is absent, or is not a static router.
too_many_members400More than 50 members.
member_exists400The router is already a member.
member_not_found404The key names no member.
tag_not_found404The router has no such tag.
router_enabled409A delete names an enabled router. Disable it first.
has_dependent_aliases409A delete names a router with aliases. Detach them first.
policy_managed409The router belongs to a tools policy, and changes through the policy.
field_not_supported_for_kind409The routes endpoint names a router that is not a Claude Proxy, or a members endpoint names a router that is not a fallback or weighted router.
model_group_changed409The Claude Proxy's model group changed at the same time. Read it again and retry.
alias_changed409The alias changed at the same time. Retry.
prompt_validation_rate_limited429Too many prompt binding checks. Retry later.
CatalogProvider Keys
Was this helpful?