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
| Method | Path | Description | Scope |
|---|---|---|---|
| GET | /v1/routers | List routers, newest change first. Filter with kind and tag. | routers:read |
| POST | /v1/routers | Create 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}/members | List the members of a fallback or weighted router, in order. | routers:read |
| POST | /v1/routers/{id}/members | Add 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}/routes | List a Claude Proxy's resolved routes: model, provider, variant, region and provider key. | routers:read |
| POST | /v1/routers/{id}/aliases | Attach 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}/aliases | Detach the alias named in the alias query parameter. | routers:delete |
| GET | /v1/routers/{id}/tags | List the router's tags. | routers:read |
| POST | /v1/routers/{id}/tags | Add 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:
| Kind | Router type | Create with |
|---|---|---|
static | Static router | routing.provider, routing.model, routing.provider_key_id, routing.region for every provider except custom, routing.variant for catalog providers, and prompt.system_message_mode. |
fallback | Fallback router | routing.routers: 1 to 50 static router ids, in order. |
weighted | Weighted router | routing.routers: 1 to 50 objects with router_id and a positive weight. |
claude_proxy | Claude Proxy | Optionally routing: route, region, credential_source, provider_key_id, model_group, model_keys and disabled_models. See Claude Proxy. |
codex_proxy | Codex Proxy | Optionally 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_proxy | Gemini Proxy | routing.provider_key_id: an enabled Gemini key of the organization. See Gemini Proxy. |
adaptive_router | Adaptive Router | routing.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
Router fields
| Field | Type |
|---|---|
id | string |
| The router id. Fixed. | |
object | string |
| Always router. | |
etag | string |
| The quoted version, for If-Match. | |
kind | string |
| static, fallback, weighted, claude_proxy, codex_proxy, gemini_proxy or adaptive_router. Fixed. | |
name | string |
| A display name. | |
description | string or null |
| A description. | |
enabled | boolean |
| Whether the router serves requests. | |
tags | array |
| Tag names. Changed through the tags endpoints. | |
aliases | array |
| Alias labels on this router. Changed through the aliases endpoints. | |
rate_limits | object |
| rpm and tpm, or null for no limit. | |
routing | object |
| 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. | |
prompt | object |
| Static routers: the bound prompt in binding, and system_message_mode. See Prompt Binding. | |
parameter_defaults | object |
| Static routers: default request parameters. | |
observability | object |
| Static routers, Adaptive Routers and proxies: metadata_level, request_capture and payload_sample_pct. | |
routes | array |
| Claude Proxies: the resolved routes, read-only. | |
created_at | string |
| When the router was created. | |
updated_at | string |
| 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.
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:
| Code | Status | Meaning |
|---|---|---|
router_not_found | 404 | The id matches no router. |
missing_field | 400 | A required field is missing, such as routing.region on a static router. |
missing_variant | 400 | A static router on a catalog provider names no variant. |
field_not_supported_for_kind | 400 | A field does not apply to the router kind, such as prompt on a fallback router. |
unknown_provider | 400 | The provider is unsupported. |
model_not_found | 400 | The model is absent from the catalog. |
invalid_variant | 400 | The model has no offering with that variant. |
region_not_offered | 400 | The offering has no such region. |
provider_key_not_found | 400 | The provider key is absent from the organization. |
provider_key_disabled | 400 | The provider key is disabled. |
provider_key_mismatch | 400 | The provider key belongs to another provider. |
invalid_member | 400 | A member is absent, or is not a static router. |
too_many_members | 400 | More than 50 members. |
member_exists | 400 | The router is already a member. |
member_not_found | 404 | The key names no member. |
tag_not_found | 404 | The router has no such tag. |
router_enabled | 409 | A delete names an enabled router. Disable it first. |
has_dependent_aliases | 409 | A delete names a router with aliases. Detach them first. |
policy_managed | 409 | The router belongs to a tools policy, and changes through the policy. |
field_not_supported_for_kind | 409 | The 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_changed | 409 | The Claude Proxy's model group changed at the same time. Read it again and retry. |
alias_changed | 409 | The alias changed at the same time. Retry. |
prompt_validation_rate_limited | 429 | Too many prompt binding checks. Retry later. |