multi-router.aidocs

API Reference

Chat Completions

POST /v1/chat/completions: OpenAI-compatible chat requests to any provider.

POST /v1/chat/completions sends a conversation to a model and returns its reply, in the OpenAI Chat Completions format, for every provider Multi-Router supports. It needs the inference scope, accepts bodies up to 4 MiB, and streams with server-sent events when stream is true.

The model field

The model field names a router or a model:

FormExampleServed by
A routermulti-router/rt_9Hk3Ws7PzQThe router, with its model, prompt and settings.
An aliasmulti-router/productionThe router the alias points to.
A provider and modelanthropic/claude-sonnet-4.5The organization's default provider key for the provider.
A model nameclaude-sonnet-4-5A router or alias with that id, or the provider the name belongs to.
A catalog offeringanthropic/claude-sonnet-4.5:anthropic:standardThat exact model, provider and variant.

A router named in the model field takes precedence over the x-mr-router header. See Routing and Supported Providers.

Request body

The body takes the OpenAI Chat Completions fields:

FieldType
modelstring, required
A router, alias, provider and model, or model name.
messagesarray, required
The conversation, as system, user, assistant and tool messages.
streamboolean
Streams the reply as server-sent events.
stream_options.include_usageboolean
Adds token usage to the last streamed chunk.
max_tokensinteger
The most tokens to generate. max_completion_tokens is also accepted.
temperaturenumber
Sampling temperature.
top_pnumber
Nucleus sampling.
stopstring or array
Stop sequences.
toolsarray
Function tools the model can call.
tool_choicestring or object
none, auto, required, or a named function.
parallel_tool_callsboolean
Allows several tool calls in one turn.
response_formatobject
text, json_object, or json_schema with a schema.
reasoning_effortstring
Reasoning effort for reasoning models.
seedinteger
Seed for repeatable sampling where the provider supports it.
userstring
The caller's end user, recorded in Traffic as the customer id.
prompt_variablesobject
Values for the router's bound prompt variables. See Prompt Variables.

Other OpenAI fields, such as presence_penalty, logprobs, metadata and service_tier, are passed to providers that support them. See Prompt Variables.

Example

A request to a router and its response, which echoes the request's model field:

Requestbash
curl https://api.multi-router.ai/v1/chat/completions \
  -H "Authorization: Bearer $MR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "multi-router/rt_9Hk3Ws7PzQ",
    "messages": [{ "role": "user", "content": "Summarize ticket 4521 in one sentence." }],
    "max_tokens": 200
  }'
Response 200json
{
  "id": "chatcmpl-8Kd2Qx9WmB",
  "object": "chat.completion",
  "created": 1790000000,
  "model": "multi-router/rt_9Hk3Ws7PzQ",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "The customer was charged twice for March and wants a refund." },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 412,
    "completion_tokens": 18,
    "total_tokens": 430,
    "prompt_tokens_details": { "cached_tokens": 0 }
  }
}

Errors

Beyond the common errors, Chat Completions returns these:

CodeStatusMeaning
router_not_found400The router or alias is absent from the organization.
router_disabled400The router is disabled.
model_not_found400The model is absent from the catalog.
unknown_model400A model name matches no router, alias or model.
model_not_found404The request names a router outside the API key's routers.
unknown_provider400The provider prefix is unsupported.
no_provider_key_configured400The organization has no provider key for the provider.
provider_key_disabled400The provider key in use is disabled.
missing_prompt_variables400The request leaves out a variable of the router's prompt.
not_supported400A parameter the provider cannot serve, such as n above 1, or a tool type other than function.
empty_messages400The messages array is empty.
OverviewMessages
Was this helpful?