multi-router.aidocs

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:

ResourceEndpointsScope
Chat CompletionsPOST /v1/chat/completionsinference
MessagesPOST /v1/messagesinference
Proxy EndpointsToken counting, Responses, OpenAI Codex, Bedrock and Vertexinference
ModelsGET /v1/modelsmodels:read
Catalog/v1/catalogmodels:read
Routers/v1/routersrouters read, write and delete
Provider Keys/v1/provider-keysprovider_keys read, write and delete
Integrations/v1/integration-types, /v1/integrations and /v1/routers/{id}/integrationsintegrations read and write
Model Groups/v1/model-groupsmodel_groups read, write and delete
Prompts/v1/promptsprompts read, write and delete
Prompt repos/v1/prompt-reposprompt_repos read, write and delete
GitHub connections/v1/github/connectionsgithub read and delete
Budgets/v1/budgetsbudgets read, write and delete
Traffic/v1/traffictraffic:read, and traffic:reveal to reveal redacted values
TagsGET /v1/tagstags:read
API Tokens/v1/api-tokensapi_tokens:read
Agents/v1/agentsagents read and delete
Organizations/v1/organizationsorganizations read, write and delete
Invites/v1/people/invitesinvites read, write and delete
SSO/v1/ssosso read, write and delete
Machine Identity/v1/machine-identitymachine_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.

An authenticated requestbash
curl https://api.multi-router.ai/v1/routers \
  -H "Authorization: Bearer $MR_API_KEY"

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:

A management errorjson
{
  "error": {
    "type": "invalid_request",
    "code": "unknown_field",
    "field": "settings",
    "message": "Unknown router field: settings"
  }
}

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:

OpenAI formatjson
{
  "error": {
    "message": "no router `rt_unknown` in this organization",
    "type": "invalid_request_error",
    "code": "router_not_found"
  }
}
Anthropic formatjson
{
  "type": "error",
  "error": { "type": "not_found_error", "message": "the requested model or router was not found" }
}

The inference error types are:

TypeMeaning
invalid_request_errorThe request is invalid, or names something absent. Fix the request.
authentication_errorA machine identity token failed authentication.
rate_limit_errorA rate limit was reached. Retry later.
budget_exhaustedA budget blocks the request. Retry-After gives the seconds until it resets.
upstream_errorThe provider failed or returned an error. The status is the provider's, and error.upstream can name the provider, its code and status.
server_errorMulti-Router failed. Retry.

Codes shared by many endpoints:

CodeStatusMeaning
invalid_json400The body is not valid JSON.
invalid_body400The body does not match the endpoint's schema.
unknown_field400The 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_collection400A 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_only400A 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_field400A field has an invalid value. The field names it.
invalid_if_match400The If-Match header is not one ETag.
invalid_dry_run400dry_run is not true or false.
invalid_cursor400The cursor is not one this list returned.
insufficient_scope403The API key lacks the scope. The message names the scope.
route_not_found404No endpoint has this method and path.
version_conflict412The If-Match ETag is stale. The response carries the current object in current.
rate_limit_exceeded429Over 300 inference requests per minute for the key, counted across every inference endpoint.
budget_exhausted429A budget blocks the request.

Headers

Multi-Router reads these request headers:

HeaderUse
AuthorizationThe API key, as Bearer sk-mr-….
If-MatchThe ETag a write expects the object to have. A stale ETag returns 412.
Idempotency-KeyMakes a create safe to retry.
x-mr-routerSelects a router or a proxy by id or alias.
x-mr-feature-idLabels the feature that made the call, up to 200 characters. Adaptive Router rules match on it, and Traffic records it.
x-mr-promptNames an Adaptive Router prompt binding, as name or name@version.
x-mr-session-idGroups requests of one session in Traffic. Up to 200 characters.
x-mr-correlation-idMatches 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.

A conditional changebash
curl -X PATCH https://api.multi-router.ai/v1/routers/rt_9Hk3Ws7PzQ \
  -H "Authorization: Bearer $MR_API_KEY" \
  -H 'If-Match: "3"' \
  -H "Content-Type: application/json" \
  -d '{ "name": "Support bot v2" }'

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.

CaseResponse
Same key, same requestThe first response again, with its status.
Same key, different request409 idempotency_key_reused.
Same key while the first is running409 idempotency_in_progress.
A key longer than 255 characters or with other characters400 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.

A list responsejson
{
  "organization_id": "org_7Tq2Wd9KxP",
  "data": [ { "id": "rt_9Hk3Ws7PzQ", "object": "router", "kind": "static", "name": "Support bot" } ],
  "next_cursor": "eyJpZCI6InJ0XzlIazNXczdQelEifQ",
  "has_more": true
}

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:

PrefixResource
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
OperationsChat Completions
Was this helpful?