API Reference
Overview
Conventions shared by every /v1 endpoint: authentication, errors, headers, conditional writes, idempotency, pagination and ids.
The Multi-Router API is a REST API at https://api.multi-router.ai/v1 that sends requests to models and manages everything an organization configures: routers, provider keys, model groups, prompts, budgets, people, single sign-on and machine identity. Requests and responses are JSON, and every request authenticates with an API key. The pages in this section list each endpoint with its scope, request, response and errors; the conventions on this page apply to all of them. The full contract is published as OpenAPI 3.1 at GET /v1/openapi.yaml, which needs no API key.
Resources
The API groups its endpoints by resource:
| Resource | Endpoints | Scope |
|---|---|---|
| Chat Completions | POST /v1/chat/completions | inference |
| Messages | POST /v1/messages | inference |
| Proxy Endpoints | Token counting, Responses, OpenAI Codex, Bedrock and Vertex | inference |
| Models | GET /v1/models | models:read |
| Catalog | /v1/catalog | models:read |
| Routers | /v1/routers | routers read, write and delete |
| Provider Keys | /v1/provider-keys | provider_keys read, write and delete |
| Integrations | /v1/integration-types, /v1/integrations and /v1/routers/{id}/integrations | integrations read and write |
| Model Groups | /v1/model-groups | model_groups read, write and delete |
| Prompts | /v1/prompts | prompts read, write and delete |
| Prompt repos | /v1/prompt-repos | prompt_repos read, write and delete |
| GitHub connections | /v1/github/connections | github read and delete |
| Budgets | /v1/budgets | budgets read, write and delete |
| Traffic | /v1/traffic | traffic:read, and traffic:reveal to reveal redacted values |
| Tags | GET /v1/tags | tags:read |
| API Tokens | /v1/api-tokens | api_tokens:read |
| Agents | /v1/agents | agents read and delete |
| Organizations | /v1/organizations | organizations read, write and delete |
| Invites | /v1/people/invites | invites read, write and delete |
| SSO | /v1/sso | sso read, write and delete |
| Machine Identity | /v1/machine-identity | machine_identity read, write and delete |
Authentication
Each request sends an API key in the Authorization header as a bearer token. Keys are created on the API Keys page, and their scopes decide which endpoints they reach. A missing or invalid key returns 401, and a key without the endpoint's scope returns 403 insufficient_scope, with a message that names the scope. Management scopes are named for their resource and level, such as routers:write: GET needs read, POST and PATCH need write, DELETE needs delete, and each level includes the ones below it. A few GET endpoints need write, and integrations have no delete level, as their pages note. See Authentication and Scope.
An API key belongs to one organization, and acts on that organization. Endpoints that manage the whole account, such as creating organizations, inviting people, configuring SSO or registering machine identity issuers, need a key of the account organization, and return 403 to a key of a named organization. A key limited to some routers cannot manage organizations, invites or agents, and returns 403 router_scoped_token.
Errors
Management endpoints return errors with a type, a stable code and a message, and, when they apply, the field at fault, the valid values, and details:
Inference endpoints use the OpenAI error format, except Messages, token counting and a Claude Proxy's model list, which use the Anthropic format, and the Claude Proxy's Bedrock and Vertex endpoints, which use those platforms' formats:
The inference error types are:
| Type | Meaning |
|---|---|
invalid_request_error | The request is invalid, or names something absent. Fix the request. |
authentication_error | A machine identity token failed authentication. |
rate_limit_error | A rate limit was reached. Retry later. |
budget_exhausted | A budget blocks the request. Retry-After gives the seconds until it resets. |
upstream_error | The provider failed or returned an error. The status is the provider's, and error.upstream can name the provider, its code and status. |
server_error | Multi-Router failed. Retry. |
Codes shared by many endpoints:
| Code | Status | Meaning |
|---|---|---|
invalid_json | 400 | The body is not valid JSON. |
invalid_body | 400 | The body does not match the endpoint's schema. |
unknown_field | 400 | The body sends a field the endpoint does not accept. On routers it is also returned for every read-only field except etag, on provider keys for read-only fields such as id and provider, and on prompts for current_version and variables. The field names it. |
use_sub_collection | 400 | A PATCH body sends a list that has its own endpoints: a budget's model_caps, alerts or overrides; a model group's members or tags; a prompt's tags; a prompt repo's files or tags; or an issuer's organization_ids. Change them through those endpoints. On routers, members, tags and aliases return unknown_field. For budgets, model groups, prompts and prompt repos, the valid field of the error lists the endpoint path template, such as /v1/budgets/{id}/alerts; {id} is not replaced with the object id. |
field_read_only | 400 | A PATCH body sends a read-only field. Budgets, model groups, prompt repos, invites, SSO, organizations and machine identity return it for every read-only field other than the lists that return use_sub_collection; prompts for every read-only field except current_version and variables (unknown_field) and tags (use_sub_collection); routers only for etag; provider keys for etag, custom and bedrock.access_key_id, bedrock.auth_mode and bedrock.session_token. |
invalid_field | 400 | A field has an invalid value. The field names it. |
invalid_if_match | 400 | The If-Match header is not one ETag. |
invalid_dry_run | 400 | dry_run is not true or false. |
invalid_cursor | 400 | The cursor is not one this list returned. |
insufficient_scope | 403 | The API key lacks the scope. The message names the scope. |
route_not_found | 404 | No endpoint has this method and path. |
version_conflict | 412 | The If-Match ETag is stale. The response carries the current object in current. |
rate_limit_exceeded | 429 | Over 300 inference requests per minute for the key, counted across every inference endpoint. |
budget_exhausted | 429 | A budget blocks the request. |
Headers
Multi-Router reads these request headers:
| Header | Use |
|---|---|
Authorization | The API key, as Bearer sk-mr-…. |
If-Match | The ETag a write expects the object to have. A stale ETag returns 412. |
Idempotency-Key | Makes a create safe to retry. |
x-mr-router | Selects a router or a proxy by id or alias. |
x-mr-feature-id | Labels the feature that made the call, up to 200 characters. Adaptive Router rules match on it, and Traffic records it. |
x-mr-prompt | Names an Adaptive Router prompt binding, as name or name@version. |
x-mr-session-id | Groups requests of one session in Traffic. Up to 200 characters. |
x-mr-correlation-id | Matches a request to the caller's own logs, and is returned on the response. |
Every response carries x-mr-request-id, and successful inference responses carry the x-mr-* headers that describe how they were served. Reads and writes of a changeable object return its ETag, and creates return a Location header. See Request Tracing.
Changing objects
Objects that can change carry an etag, a quoted counter such as "3", equal to the response's ETag header. Sending it back in If-Match makes a write apply only if nobody changed the object in between; a stale ETag returns 412 version_conflict with the current object, so the caller can read it again and decide. Writes to an object's sub-collections, such as a router's members or tags, are conditional on the parent's ETag.
PATCH changes only the fields sent. A field left out keeps its value, a field sent as null is cleared, nested objects merge field by field, and fields marked as replaced whole, such as a budget's scope, take the value sent. Unknown fields are refused with unknown_field. Read-only fields are refused with field_read_only on invites, SSO and organizations, and on budgets, model groups, prompt repos and machine identity other than the lists below. On prompts, read-only fields return field_read_only except current_version and variables, which return unknown_field. On routers, only etag returns field_read_only, and other read-only fields such as id and kind return unknown_field. On provider keys, etag, custom, bedrock.access_key_id, bedrock.auth_mode and bedrock.session_token return field_read_only, and other read-only fields such as id and provider return unknown_field. Lists change through their own endpoints, not the parent's PATCH. Sending one in a PATCH returns use_sub_collection: a budget's model_caps, alerts and overrides, a model group's members and tags, a prompt's tags, a prompt repo's files and tags, and an issuer's organization_ids. For budgets, model groups, prompts and prompt repos, the error's valid field lists the endpoint path template, such as /v1/budgets/{id}/alerts; {id} is not replaced with the object id. On routers, members, tags and aliases return unknown_field.
Endpoints that accept dry_run=true validate the request and return the result without saving anything. Each page notes which endpoints accept it.
Idempotency
An Idempotency-Key makes a create request safe to retry: after a successful response, a retry with the same key and the same request returns that response again, including its Location header. A failed request releases the key, so its retry runs again. Keys are kept per organization and do not expire, and a key that completed a request stays tied to it. Keys hold up to 255 visible ASCII characters, and each create uses a new one, such as a UUID. Creates accept a key, and a provider key transfer requires one.
| Case | Response |
|---|---|
| Same key, same request | The first response again, with its status. |
| Same key, different request | 409 idempotency_key_reused. |
| Same key while the first is running | 409 idempotency_in_progress. |
| A key longer than 255 characters or with other characters | 400 invalid_idempotency_key. |
Pagination
Lists return a page of results in data, with next_cursor and has_more. Pass limit, from 1 to 200 with a default of 50, and cursor set to the previous page's next_cursor, and continue until next_cursor is null. A filtered page can hold fewer results than the limit while more follow.
Responses and ids
Management responses carry organization_id and the object in data. Each object names its type in object. Deletes return organization_id, the id, the object and "deleted": true. Integrations and their router attachments differ: they return the object itself with an integer version, and deletes return 204; see Integrations. Times are RFC 3339. Amounts are integers in millionths of a US dollar. Model slugs, such as anthropic/claude-sonnet-4.5, are catalog model ids. Ids start with a prefix for their kind:
| Prefix | Resource |
|---|---|
rt_ | Router |
llpk_ | Provider key |
int_ | Integration |
inta_ | Integration attachment |
mg_ | Model group |
bdg_ | Budget |
bdr_ | Budget alert |
ip_ | Inline prompt |
pf_ | GitHub prompt |
pr_ | Prompt repo |
org_ | Organization |
per_ | Person |
inv_ | Invite |
tok_ | API key |
wl_ | Agent |
mii_ | Machine identity issuer |
mib_ | Machine identity binding |
req_ | Request |
sk-mr- | API key value |