Getting Started

Overview

What Multi-Router is, and how its parts fit together.

Multi-Router is a platform for sending requests to AI models from many providers through one API, and for managing the routing, prompts, credentials, spend and records of those requests. Applications send OpenAI- or Anthropic-format requests to Multi-Router with one API key, and routers decide which model and provider serve each request. Teams change models, prompts and providers on the router, with no change to application code, and see every request in Traffic.

How it works

A request reaches a model in four steps:

1. An organization adds provider keys for the providers it uses, such as Anthropic, OpenAI or AWS Bedrock.
2. It creates routers, each with the model, provider and settings for one job, such as a support bot.
3. Applications call Multi-Router with an API key, naming the router in the model field.
4. Multi-Router serves the request from the router's provider, and records it in Traffic with its cost.

What you can do

Multi-Router covers these areas, each with its own section:

Next steps

The Quickstart sends a first request in a few steps. Teams moving an existing application start with Using an SDK, and Key Concepts defines the terms used across these docs.

Getting Started

Quickstart

Sending a first request through Multi-Router: a provider key, a router, an API key and a request.

This quickstart sets up a router for an Anthropic model and sends it a request. It takes a Multi-Router account and an Anthropic API key. Other providers follow the same steps, with the extra settings some need, such as a region for AWS Bedrock.

1. Add a provider key

A provider key is the organization's credential for a model provider, which Multi-Router uses to send requests there.

1. Sign in to the dashboard at https://dashboard.multi-router.ai.
2. Open LLM Provider Keys from the profile menu at the top right, and select Anthropic in the Providers list.
3. In the form, or with Add Anthropic key, enter a Name, such as Anthropic production, paste the API key, and select Save key.

The first key for a provider becomes its default key. See Provider Key.

2. Create a router

A router holds the model and settings a request is served with.

1. Open Routers in the top navigation, and select New router.
2. Under Type, keep Static Router, which is selected.
3. Under Details, name the router, such as Support bot.
4. Under Routing, choose the model, such as Claude Sonnet 4.5, its provider Anthropic and variant standard, and the key from step 1, or Org-default key.
5. Under Review & create, create the router, and copy its id with Copy router ID, such as rt_9Hk3Ws7PzQ.

See Static Router.

3. Create an API key

An API key authenticates your application to Multi-Router.

1. Open API Keys from the profile menu, and select New API key.
2. Name the key, such as quickstart, keep the Inference only access, and select Create.
3. Copy the key with Copy, and set it in your shell as MR_API_KEY.

See API Key.

4. Send a request

Send a Chat Completions request that names the router in the model field:

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": "Say hello in one sentence." }]
  }'

The response is a standard Chat Completions response, with headers such as x-mr-provider and x-mr-upstream-model showing how it was served.

5. See it in Traffic

Open Traffic in the top navigation. The request appears at the top, with its router, model, tokens, cost and latency, and selecting its request id opens its full detail. See Traffic.

Next steps

Each next step builds on the router and key from this quickstart:

Getting Started

Using an SDK

Pointing the OpenAI and Anthropic SDKs at Multi-Router.

Multi-Router speaks the OpenAI Chat Completions and Anthropic Messages formats, so the official OpenAI and Anthropic SDKs work with it by changing two settings: the base URL and the API key. The model field then names a Multi-Router router, and every other part of the application stays as it is.

OpenAI SDK

The OpenAI SDK uses the base URL https://api.multi-router.ai/v1:

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.multi-router.ai/v1",
    api_key=os.environ["MR_API_KEY"],
)

response = client.chat.completions.create(
    model="multi-router/rt_9Hk3Ws7PzQ",
    messages=[{"role": "user", "content": "Say hello in one sentence."}],
)
print(response.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.multi-router.ai/v1",
  apiKey: process.env.MR_API_KEY,
});

const response = await client.chat.completions.create({
  model: "multi-router/rt_9Hk3Ws7PzQ",
  messages: [{ role: "user", content: "Say hello in one sentence." }],
});
console.log(response.choices[0].message.content); // in an ES module

Anthropic SDK

The Anthropic SDK uses the base URL https://api.multi-router.ai:

import os
import anthropic

client = anthropic.Anthropic(
    base_url="https://api.multi-router.ai",
    api_key=os.environ["MR_API_KEY"],
)

message = client.messages.create(
    model="multi-router/rt_9Hk3Ws7PzQ",
    max_tokens=200,
    messages=[{"role": "user", "content": "Say hello in one sentence."}],
)
print(message.content[0].text)

The model field

The model field names what serves the request:

Naming a router keeps the model choice out of the application, so it changes on the router. See Chat Completions.

Multi-Router fields and headers

A few optional fields and headers add Multi-Router features to SDK requests:

response = client.chat.completions.create(
    model="multi-router/rt_9Hk3Ws7PzQ",
    messages=[{"role": "user", "content": "How do I reset my password?"}],
    user="tenant_acme",
    extra_body={"prompt_variables": {"product": "Acme Cloud", "language": "English"}},
    extra_headers={"x-mr-session-id": "conv_8812"},
)

See Prompt Variables and Request Tracing.

Getting Started

Key Concepts

The terms used across the Multi-Router docs, each with where to read more.

Multi-Router's terms fall into four areas: where models come from, how requests are routed, who can do what, and the prompts, records and spend around each request. Each term below links to the page that covers it in full.

Providers and models

Models come from providers, through the organization's keys:

Routing

Routers decide how each request is served:

Access

Accounts, organizations and credentials decide who can do what:

Prompts, records and spend

Prompts shape requests, Traffic records them, and budgets cap their cost:

Providers & Models

Overview

How Multi-Router organizes models, providers, variants and regions, and how it uses your provider keys to route each request.

Multi-Router sends each request to a model provider, such as Anthropic, OpenAI, AWS Bedrock or Google Vertex, using credentials from your own account with that provider. A router decides which model serves a request and on which provider, variant and region; the model catalog supplies the model id and price for that choice; and a provider key supplies the credentials.

Setting up routing takes three steps. You add a provider key for each provider you use (see Provider Key), create a router that targets a model on one of those providers (see Routing), and send requests to the router with a Multi-Router API key (see API Access).

Routers and API keys

Multi-Router separates what a request does from who sends it. A router is a named object in an organization that holds the behavior for the requests sent to it: which model and provider serve them, which provider key is used, which variant and region they run in, and the prompt, parameter defaults and logging applied to them. An API key holds identity: it identifies the organization a request belongs to and what the caller is permitted to do. Because an API key carries no routing configuration, the behavior of every request is set by the router it names, and changing a router changes the behavior for every caller of that router without new API keys or changes to application code.

Every router has a type, and each type encapsulates one routing behavior. A request names a router in its model field, and the router's type determines what happens next:

An alias is a stable name that points to a router. A request can name the alias in place of the router, and repointing the alias moves every caller to a different router at once. See Routing.

A static router holds the following behavior, all of which can change without changing its callers:

An API key holds the following identity and permissions:

The same router can serve several applications, each with its own API key, and one application can use several routers by naming a different router in each request. See Routing and API Access.

The building blocks

The following terms are used throughout the Providers & Models documentation.

How models are organized

The model catalog organizes each model in four levels: the model itself, the providers that serve it, the variants each provider offers, and the regions where each variant runs. Together, these four values identify exactly one entry in the catalog. The catalog entries for anthropic/claude-haiku-4.5 are organized as follows:

Models and slugs

A slug is the unique name of a model in Multi-Router, in the form publisher/name, such as anthropic/claude-haiku-4.5 or openai/gpt-5. The publisher and the provider are separate: Anthropic publishes anthropic/claude-haiku-4.5, and Anthropic, AWS Bedrock and Google Vertex all serve it. A slug identifies the model regardless of which provider serves it, is matched without regard to case, and is the name you use for a model when configuring routers and model groups.

GET /v1/models returns the chat models your organization can call: models that are active or deprecated and have an offering that is not retired from a provider for which the organization holds an enabled provider key. See Model Catalog.

curl https://api.multi-router.ai/v1/models \
  -H "Authorization: Bearer $MR_API_KEY"

Providers

A provider is the platform that runs the model and bills for its use. When a model is available from several providers, the provider determines which account is billed, the price, the regions available and the date the model is retired, and in some cases a smaller context window than the model supports elsewhere. Multi-Router uses Google Vertex for Anthropic models and serves Google's Gemini models through the Gemini provider. See Supported Providers.

Variants and regions

A variant is one way a provider offers a model. Most providers offer a single standard variant; AWS Bedrock offers in_region, geo and global inference scopes; and several providers offer dated snapshots and faster or quantized builds. A region is a location where a variant runs, and the model id and price can differ from one region to another. When a router leaves the region unset, Multi-Router uses the provider key's region on AWS Bedrock, the organization default region on xAI, and global elsewhere, and Google Vertex always uses the location set on the provider key. Multi-Router never moves a request out of the selected region. See Regions & Variants.

The model tuple

The tuple (model, provider, variant, region) identifies one catalog entry: a specific model, served by a specific provider, in a specific variant and region. Each tuple has its own model id, which is the id Multi-Router sends to the provider, and its own price. The following are some of the tuples for anthropic/claude-haiku-4.5:

Routers, keys and the catalog

A router connects a request to providers, provider keys and the catalog, and each kind of router does so differently. A static router stores a model, provider and variant and optionally a region, so moving an application to a different provider, variant or region requires a change to the router and no change to the application.

A request sent through an alias uses the provider key and catalog checks of the router the alias points to.

Addressing a router

A request selects its router through the model field or the x-mr-router header:

A router named in model takes precedence over the header. A disabled router returns router_disabled, and an unknown router returns router_not_found.

The request lifecycle

The request lifecycle is the sequence of checks and calls Multi-Router performs for each Chat Completions or Messages request:

1. Rate limit. Multi-Router counts the request against the API key's rate limit, and returns 429 rate_limit_exceeded when it is reached.
2. Body checks. The body must be valid JSON within the endpoint's size limit, with a non-empty list of messages.
3. Router selection. Multi-Router selects the router as described in Addressing a router.
4. API key scope. An API key limited to specific routers receives 404 for any other router.
5. Budget check. A router over its budget returns 429 budget_exhausted with a Retry-After header.
6. Attempt. For a static router, and for each member a fallback or weighted router tries, Multi-Router applies the router's bound prompt and parameter defaults, translates the request to the provider's API, loads the provider key, checks the request against the catalog entry (model, mode, lifecycle, provider, variant and request features), selects the region, and calls the provider with the entry's model id. It retries rate limits, overloads, temporary server errors, timeouts and connection failures, honoring the provider's retry delay.
7. Response. Multi-Router converts the provider's response to the format of the request, OpenAI for Chat Completions and Anthropic for Messages, and adds the routing headers.
8. Cost and Traffic. Multi-Router prices the token usage, counts the cost toward budgets, and records the request in Traffic according to the router's Request Logging settings.

Fallback behavior

Fallback behavior is how a fallback or weighted router handles a failed attempt: failures in the member's configuration, a budget refusal, a catalog check, a timeout, or a rate limit, authentication or server error from the provider move the request to the next member, while an invalid request returns its error at once. See Fallback Router for the full list.

Response headers

Multi-Router adds the following headers to Chat Completions and Messages responses:

Requests can carry the following headers:

Costs

Multi-Router calculates the cost of each request from the token counts the provider reports and the catalog price of the region the request was served in. Cache reads and writes, long context rates, the fast service tier and web search calls use their own prices, and for Anthropic the region is the one Anthropic reports the request ran in. A custom variant replaces list prices with negotiated prices. Each cost appears in Traffic and counts toward budgets, while the provider bills your account directly at your agreed rates. A streamed response is priced when the stream ends, including a stream the client stops early. See Model Catalog and Custom Models & Pricing.

Traffic

Traffic is the dashboard's record of each request that reaches a router. The router's Request Logging settings control what it keeps: Request metadata (None, Failures only, Anonymous Metadata or Full Metadata) and Request payloads (None, Failures only, Sample or All Payloads). Cost counts toward budgets at every logging level. The columns that relate to providers and models are:

The request detail view also shows Model requested, Model served, Session, Correlation ID, TTFT and Router overhead. See Observability.

Example

This example sends a request to Claude Haiku 4.5 on AWS Bedrock in the United States and reads how it was served:

1. In LLM Provider Keys, add an AWS Bedrock key with the AWS Region us-east-1 and Access key (SigV4). Its id is llpk_4Vd8Qm2RtL.
2. Create a static router on Bedrock geo, which returns the router id rt_9Hk3Ws7PzQ.
3. Send a Chat Completions request to multi-router/rt_9Hk3Ws7PzQ with a correlation id.
4. Read the response headers, and find the request in Traffic.

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": "haiku-us",
    "routing": {
      "provider": "bedrock",
      "model": "anthropic/claude-haiku-4.5",
      "variant": "geo",
      "region": "us-east-1",
      "provider_key_id": "llpk_4Vd8Qm2RtL"
    },
    "prompt": { "system_message_mode": "merge" }
  }'

curl https://api.multi-router.ai/v1/chat/completions \
  -H "Authorization: Bearer $MR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "x-mr-correlation-id: order-4411" \
  -d '{
    "model": "multi-router/rt_9Hk3Ws7PzQ",
    "messages": [{ "role": "user", "content": "Hello" }]
  }'

x-mr-request-id: req_8Fq2LmXo1c
x-mr-correlation-id: order-4411
x-mr-provider: bedrock
x-mr-upstream-model: anthropic/claude-haiku-4.5
x-mr-upstream-wire-id: us.anthropic.claude-haiku-4-5-20251001-v1:0
x-mr-region: us-east-1
x-mr-policy: static
x-mr-attempts: 1

The router names the key's region, us-east-1, and the geo variant keeps inference in the United States. In Traffic, the request's row shows Router rt_9Hk3Ws7PzQ, Vendor bedrock, Variant geo, Region us-east-1, the wire id above, the input and output tokens, and a cost at $1.10 per million input tokens and $5.50 per million output tokens.

Pages in this section

The Providers & Models pages cover the following:

Routing, Agents & Editors, Observability and Budgets & Spend Control cover routers, Claude Proxies, Traffic and spending limits.

Providers & Models

Supported Providers

The model providers Multi-Router routes to, the settings each provider key needs, the request features each provider supports, and how requests and responses are translated.

Multi-Router routes requests to several kinds of model provider. Model publishers such as Anthropic, OpenAI and Google serve their own models. Inference platforms such as Fireworks, Groq and Together serve open models. Cloud platforms such as AWS Bedrock and Google Vertex serve models from many publishers across regions. Multi-Router also routes to custom endpoints that implement the OpenAI Chat Completions API. Your application calls every provider through the same two endpoints, Chat Completions and Messages, and Multi-Router translates each request into the provider's own API and each response back.

Providers

A provider is a company or cloud platform that serves models to Multi-Router, identified by a provider id that router configurations use and the x-mr-provider response header returns. A router whose provider does not serve its model returns provider_not_offered.

Provider endpoints

The provider endpoints are the hosts Multi-Router calls for each provider, with the authentication it uses and the regions it serves. A self-hosted installation allows outbound HTTPS on port 443 to the hosts of the providers it uses.

DeepSeek, Fireworks, Groq, Mistral, Together, xAI, Z.ai and custom endpoints use the OpenAI Chat Completions format, and Multi-Router sends them the same request it sends OpenAI, with max_tokens sent as max_completion_tokens. Regions are described in Regions & Variants.

Provider-specific behavior

Custom endpoints

The custom provider sends requests to an endpoint that implements the OpenAI Chat Completions API, such as a self-hosted model server. Its provider key holds the Base URL, the API format (OpenAI Chat Completions) and the API key, and Multi-Router appends /chat/completions to the base URL, which must use HTTPS and a public DNS name, with no port, credentials, query string or fragment. A router on a custom endpoint can name any model the endpoint serves, and requests skip the catalog checks. Requests carry no price unless the model is registered with a price in Custom Models & Pricing.

Feature support

Feature support shows which request features each provider supports: streaming responses, tool calls, parallel tool calls, image input, structured output that follows a JSON schema, reasoning, and prompt caching. Per model means some of the provider's models support the feature, and the Models page lists the features of each model. A request that uses a feature its model lacks returns an error named for the feature; see Model Catalog.

Claude features by endpoint

Claude models on Anthropic, Vertex and Bedrock support some features on only one of the two endpoints, as follows:

Input content

Input content is the set of content types a request message can contain. Requests can contain text, images, tool calls and tool results; images are sent as a URL or, on Chat Completions, as a data: URL with base64 data. Google Vertex accepts base64 images only, AWS Bedrock receives URL images after Multi-Router downloads them, and Cohere receives text only. On Chat Completions, a tool message keeps its text parts, and a content part of any type other than text and image returns not_supported. The Messages endpoint also accepts thinking blocks, and removes other block types, such as redacted_thinking and search result blocks, before sending the request.

Translation between API formats

Translation is the conversion of a request into the provider's API and of the response back into the format of the request. Multi-Router accepts OpenAI Chat Completions requests at /v1/chat/completions and Anthropic Messages requests at /v1/messages, and either format can target any provider. Messages, system prompts, text, tools, tool choice, tool calls and results, stop sequences, temperature, top_p and maximum tokens are converted for every provider. Other fields are converted when the provider's API has an equivalent and removed otherwise, and fields Multi-Router does not recognize are removed.

The anthropic-beta request header is forwarded to Anthropic and Google Vertex. Reasoning text from the model is omitted from Chat Completions responses. Tool call ids pass through unchanged in both directions, so a tool result names the id the provider issued: toolu_ ids from Claude, call_ ids from OpenAI, and the function name from Gemini.

The following requests return an error:

Streaming

Streaming returns the response as server-sent events in the format of the endpoint, whatever format the provider streams in. Multi-Router always asks the provider for token usage, so Traffic records token counts whether or not the request asks for them.

Token usage

Token usage is the count of tokens the provider reports, returned in the format of the endpoint:

Response fields

Response fields follow the format of the endpoint, with the following values set by Multi-Router. The model field returns the value the request sent, such as the router name, and the x-mr-upstream-model and x-mr-upstream-wire-id headers name the model that served it. The id is the provider's response id, prefixed with chatcmpl- on Chat Completions. created is the time Multi-Router built the response, and Messages responses return stop_sequence as null. Stop reasons are mapped as follows:

Provider errors and retries

A provider error is a failure the provider returns after Multi-Router sends the request. Multi-Router returns it with a Multi-Router error code and an upstream object holding the provider, the provider's error code and its HTTP status; the provider's own message is not passed through, because it can contain account details.

{
  "error": {
    "message": "upstream provider rate limited this request after multiple retries",
    "type": "upstream_error",
    "code": "upstream_rate_limit",
    "upstream": { "provider": "anthropic", "code": "max_attempts_exceeded", "status": 529 }
  }
}

On the Messages endpoint, the same failures use Anthropic error types chosen by status: invalid_request_error for 400, rate_limit_error for 429, overloaded_error for 503 and api_error otherwise, with the upstream object included.

Multi-Router retries a provider request that fails with HTTP 429, 500, 502, 503, 504 or 529, a timeout or a connection failure, for up to five attempts. Waits double from one second with up to 25% random jitter, up to 60 seconds, and a whole-second Retry-After from the provider replaces the computed wait. Retries stop when another attempt would run past five minutes from the first, and a 429 that reports exhausted credit is returned at once. These rules apply to every provider and to custom endpoints, and Claude Proxy requests are sent once, without retries.

Limits

Limits are the size and time bounds Multi-Router applies to provider requests:

Claude Code and Claude Desktop

A Claude Proxy forwards requests from Claude Code and Claude Desktop to Anthropic, AWS Bedrock or Google Vertex in their native API formats, replacing only the model id, so every feature of those APIs is available. See Agents & Editors.

Providers & Models

Provider Key

Add, configure, rotate, transfer and remove the credentials Multi-Router uses to call model providers.

A provider key is the credential for one of your accounts with a model provider, such as an Anthropic API key or an AWS Bedrock access key, and Multi-Router uses it to call that provider on your behalf. Each provider key belongs to one organization, each organization holds its own keys, and each organization has one default key per provider. Provider keys are created and changed in the dashboard, on the LLM Provider Keys page in the profile menu, or through the API with /v1/provider-keys. Provider key secrets are encrypted at rest and in transit, and a saved secret is never displayed or returned.

Who can manage provider keys

Provider keys are managed by the admins of the organization that holds them. An admin of a named organization adds, edits, disables, deletes, transfers and sets default keys for that organization, and an account admin does the same for the keys held by the account itself. Organization members use the organization's keys through its routers.

The provider keys page

The provider keys page shows every key in the selected organization, grouped by provider. The Providers list on the left shows each provider with its number of keys and the name of its default key, or Not configured when it has none, and selecting a provider shows its keys with a summary such as 2 keys · default production. Each key row shows the following:

Each row offers the following actions:

Adding a provider key

Adding a provider key stores a credential for one provider in the selected organization:

1. Open LLM Provider Keys from the profile menu.
2. Select the provider in the Providers list. A provider with no keys opens the new-key form directly; otherwise select Add <Provider> key.
3. Complete the form titled New <Provider> key, then select Save key.

Name is required and up to 80 characters, names are labels and can repeat, and Description is optional and up to 2,000 characters. Multi-Router trims spaces from the secret and rejects an empty one, and checks every provider setting when the key is saved. A Google Vertex key is verified with Google when it is saved; the secrets of other providers are checked by the provider, so an invalid secret returns the provider's authentication error on the first request that uses it. A key added while its provider has no default becomes the default.

Obtaining a provider secret

Each provider issues the secret Multi-Router stores. Create a key that only Multi-Router uses:

The default key

The default key is the key an organization uses for a provider when a router names no key. A key added while its provider has no default becomes the default, so the first key for each provider is the default, and Make default on another enabled key of the same provider replaces it. Disabling the default key leaves it as the default, so requests that rely on it fail until it is enabled again or another key is made the default. Deleting the default key makes the oldest enabled key of the same provider the default, and leaves the provider with no default when it has no other enabled key; a key enabled later becomes the default only through Make default.

Which key a request uses

Multi-Router selects the provider key for each request from the router that serves it:

Static routers created with POST /v1/routers name a key in routing.provider_key_id, which must be an enabled key of the router's provider in the same organization. Static routers created in the dashboard can select Org-default key instead, which follows the default as it changes, starting with the next request. See Routing.

Editing a key

Editing changes a key's details without changing its secret. Edit opens a panel titled Edit <name> with Name and Description, plus Region for an OpenAI key, and Google Cloud project ID and Google Cloud location for a Google Vertex key; select Save to apply it. A changed Vertex project or location is verified with Google before it is saved. The provider, the secret, and the region and credentials of an AWS Bedrock key are fixed; to change them, add a new key.

Rotating a key

Rotating a key replaces it with a new key that holds a new secret, without interrupting requests:

1. Add a new provider key with the new secret.
2. If the old key is the default for its provider, select Make default on the new key.
3. Change every router, Claude Proxy and model group that names the old key to the new key, and change the key in any policy that names it.
4. Disable the old key and confirm that requests continue to succeed.
5. Delete the old key, then revoke the old secret with the provider.

With the API, POST /v1/provider-keys/{id}/rotate replaces the secret of a key in place, keeping its id, so routers, Claude Proxies and model groups that name the key need no change.

Disabling and deleting a key

Disabling a key stops Multi-Router from using it while keeping it for later use. Requests already in progress complete, and new requests from routers that name the key, or that rely on it as the default, return provider_key_disabled. A key named by a Claude Proxy can be disabled only after the Claude Proxy's key is replaced or removed. Enabling a Google Vertex key verifies it with Google again.

Deleting a key removes it permanently. A key must be disabled before it is deleted, and a key named by a model in a model group can be deleted only after it is removed from the group. Routers that name a deleted key return router_pinned_key_missing until they are changed to another key.

Copying and moving keys between organizations

Transfer copies or moves a provider key to another organization in the same account. It requires the admin role in both organizations, and an account admin is an admin of every organization in the account.

1. Select Transfer on the key's row, and choose Copy or Move.
2. Choose the Destination org. The list shows the organizations in the account where you are an admin, other than the current one, and shows the account itself under the account's name.
3. Change Name in destination and Description if needed; both start with the key's current values.
4. Select Copy to <organization> or Move to <organization>.

The secret, provider settings, enabled state and fingerprint carry over. The transferred key becomes the destination's default when it is enabled and the destination has no default for its provider. When the destination already holds a key of the same provider with the same secret, the panel warns An identical key already exists in <organization> as <name>, and the transfer can still proceed.

Security practices

Security practices for provider keys follow from how Multi-Router uses them:

Errors

Requests and router changes return the following errors for provider keys, each with HTTP status 400:

The dashboard reports the following when a key action is refused:

Managing keys with the API

The /v1/provider-keys endpoints act on the provider keys of the API key's organization. Reads never return a secret; a create or rotate returns the new secret once. Scopes are cumulative: provider_keys:delete includes write, and write includes read.

Each key has its id, prefixed llpk_, used in provider_key_id, with name, description, provider, key_prefix, enabled, is_default, its etag, and the provider's section: bedrock with region, auth_mode and access_key_id; vertex with project_id and region; openai with data_residency; or custom with base_url and api_format. See Provider Keys in the API Reference for every field and error.

curl "https://api.multi-router.ai/v1/provider-keys?limit=50&cursor=$NEXT_CURSOR" \
  -H "Authorization: Bearer $MR_API_KEY"

{
  "organization_id": "org_7Tq2Wd9KxP",
  "data": [
    {
      "id": "llpk_4Vd8Qm2RtL",
      "object": "provider_key",
      "name": "Bedrock production",
      "description": null,
      "provider": "bedrock",
      "bedrock": { "region": "us-east-1", "auth_mode": "sigv4", "access_key_id": "AKIAIOSFODNN7EXAMPLE" },
      "key_prefix": "wJalrXUtnF",
      "enabled": true,
      "is_default": true,
      "etag": "\"3\"",
      "created_at": "2026-09-12T17:47:43Z",
      "updated_at": "2026-09-30T08:12:09Z"
    }
  ],
  "next_cursor": null,
  "has_more": false
}

Providers & Models

Regions & Variants

Choose which build of a model serves a request and where it runs, and keep inference within a region or geography.

A variant is one way a provider offers a model, and a region is a location where that variant runs. The variant and region determine the model id sent to the provider, the price, and where inference takes place, which makes them the settings that control data residency, latency and cost. A static router names its variant and can name its region; when the router leaves the region unset, Multi-Router takes it from the provider key or the organization.

Variants

A variant distinguishes offerings of the same model on the same provider that differ in where inference runs, in serving speed, or in the build of the model. Each variant has an id, which routers and the API use, and a display name, which the dashboard shows.

Snapshots

A snapshot is a variant pinned to one dated build of a model, for applications that need the model's behavior to stay fixed. On Anthropic, the standard variant sends the undated model id, such as claude-haiku-4-5, which Anthropic points at its current build, and the snapshot variant 20251001 sends the dated id claude-haiku-4-5-20251001 at the same price. On AWS Bedrock the snapshot is combined with the inference scope, as in geo-20241022 (Geo, Snapshot 22 Oct 2024) and in_region-20240620, and some Bedrock models offer revisions such as in_region-v1-0. Fireworks, Together and xAI name snapshots by build number, such as 0813 and 0309.

Variant lifecycle

Each variant has its own lifecycle status, so a model can be retired in one variant or on one provider and remain available in another, such as a model retired on Anthropic whose AWS Bedrock geo variant is deprecated. A deprecated variant continues to serve requests, and its responses carry the x-mr-model-deprecated header. A router on a retired variant returns router_variant_retired, and the error message lists the variants of the model that the provider still serves. A router always uses the variant it names, and Multi-Router does not substitute another variant.

Regions

A region is a location where a variant is offered, and each region has its own model id and price. What the region controls depends on the provider:

Google Vertex locations

Google Vertex offers three types of location, and the models available differ from one location to another:

AWS Bedrock

AWS Bedrock offers each model in up to three inference scopes, and the AWS region that receives the request is the router's region or, when the router names none, the provider key's region. The inference scope then determines where the request runs:

The geo variant covers the following geographies. Some regions belong to two geographies, and the model determines which applies: ap-northeast-1, for example, is in the Japan geography for Claude Haiku 4.5 and in the Asia Pacific geography for other models. The Models page shows the model id for each region.

The global variant is also offered in regions outside these geographies, such as sa-east-1, af-south-1, me-central-1 and mx-central-1. The in_region variant is offered for the fewest models; Claude Haiku 4.5, for example, is offered on Bedrock in geo and global only. A Bedrock provider key's region is chosen from the AWS regions listed in the dashboard's key form, and a router can name any region the catalog lists for its variant. A Bedrock API key works only in the region it was created for, so a router that uses one must use that region.

Choosing a variant and region

The variant and region to choose depend on the residency, availability and price the application requires:

How the region is selected

Multi-Router selects the region for each request from the router, the provider key and the organization, in the following order for each provider:

Multi-Router sends every request to the selected region and never switches it to another region. When the model is not offered in the selected region, the request returns region_not_served and the error message lists the regions where the model is available.

Organization default region

The organization default region is the region used by routers on providers whose provider keys carry no region, such as xAI, when the router names no region. Organization admins set it in the Default region card on the Organizations page, which opens from Manage Organizations in the profile menu.

Examples

Configuring a router

A static router sets its variant in routing.variant and its region in routing.region. Through the API, both are required for every provider except custom endpoints; in the dashboard, the region can be left to inherit. Multi-Router checks both against the catalog when the router is created with POST /v1/routers or changed with PATCH /v1/routers/{id}, and rejects a variant the provider does not offer for the model and a region the variant does not offer. The offerings and regions of a model are read with GET /v1/catalog/models/{publisher}/{model}; see Catalog.

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": "haiku-eu",
    "routing": {
      "provider": "bedrock",
      "model": "anthropic/claude-haiku-4.5",
      "variant": "geo",
      "region": "eu-central-1",
      "provider_key_id": "llpk_4Vd8Qm2RtL"
    },
    "prompt": { "system_message_mode": "merge" }
  }'

Dashboard region picker

The dashboard's model picker lists every variant of a model with its display name and description, and the region picker lists every region of the selected variant with its model id and price. The region picker's options depend on the provider:

For AWS Bedrock, Google Vertex and xAI, the picker preselects the provider key's region, then the organization default region, then the first region the variant offers, and a note under the picker states which source it used. When neither the router, the key nor the organization supplies a region, the picker warns that requests will fail.

Custom endpoints

Routers on a custom endpoint take no variant. They can set a region only when the model is a custom model registered with regions, and a custom model offered in several regions requires one; see Custom Models & Pricing.

Claude Proxy routes

A Claude Proxy route is the provider and variant a Claude Proxy sends Claude Code and Claude Desktop traffic to, and each route except Custom requires a region that the route serves:

A Bedrock API key used by a Claude Proxy must have been created for the route's region. See Agents & Editors.

Traffic

Traffic records the variant and the region of every request. The Variant and Region columns are hidden by default and are turned on in the Columns picker, and the request detail view shows both. The Region column shows the region the request was billed at, and for Anthropic this is the region Anthropic reports the request ran in. The x-mr-region response header reports the region the request was sent to.

Errors

Router changes and requests return the following errors for variants and regions:

Providers & Models

AWS Bedrock

Connect an AWS account to Multi-Router and route requests to the models AWS Bedrock serves.

AWS Bedrock is Amazon's managed model platform, serving models from Anthropic, Amazon, Meta, Mistral, DeepSeek, Qwen, OpenAI, Moonshot, Nvidia and Z.ai in AWS regions under your AWS account. Multi-Router calls Bedrock with a provider key that holds AWS credentials and a default region. AWS bills usage to the account that owns the credentials, and Multi-Router records the cost of each request at the catalog price of the region and inference scope that served it.

Preparing your AWS account

The AWS account that serves requests needs model access and an IAM identity whose credentials Multi-Router uses:

1. Bedrock enables serverless models automatically on first use. Before the first call to an Anthropic model, submit Anthropic's one-time use-case form in the Bedrock console. Models sold through AWS Marketplace subscribe on first use, so the identity that makes the first call needs aws-marketplace:Subscribe and aws-marketplace:ViewSubscriptions, or an administrator with those permissions calls each model once.
2. Create an IAM user for Multi-Router and attach a policy that allows bedrock:InvokeModel and bedrock:InvokeModelWithResponseStream, such as the policy below. To use a Bedrock API key, also allow bedrock:CallWithBearerToken.
3. Create the credential Multi-Router will use: an access key for the IAM user, or a long-term Bedrock API key.

These actions cover every request Multi-Router sends to Bedrock, including streaming. Requests through geo inference profiles are authorized against the profile and against the foundation model in every region of the geography, and requests through global profiles are also authorized against the region-less foundation model resource, which the policy lists. A service control policy that limits aws:RequestedRegion must allow every region of the geography for geo profiles, and the value unspecified for global profiles.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "MultiRouterBedrockInvoke",
      "Effect": "Allow",
      "Action": [
        "bedrock:InvokeModel",
        "bedrock:InvokeModelWithResponseStream"
      ],
      "Resource": [
        "arn:aws:bedrock:*::foundation-model/*",
        "arn:aws:bedrock:::foundation-model/*",
        "arn:aws:bedrock:*:<ACCOUNT_ID>:inference-profile/*"
      ]
    },
    {
      "Sid": "MultiRouterBedrockApiKey",
      "Effect": "Allow",
      "Action": "bedrock:CallWithBearerToken",
      "Resource": "*"
    }
  ]
}

Adding a Bedrock provider key

A Bedrock provider key holds one set of AWS credentials and the AWS region requests go to by default. To add one, open LLM Provider Keys in the dashboard, add a key, select AWS Bedrock, and choose Access key (SigV4) or API key (bearer) at the top of the form:

The key's region is one of us-east-1, us-east-2, us-west-2, ca-central-1, sa-east-1, eu-central-1, eu-west-1, eu-west-2, eu-west-3, eu-north-1, eu-south-1, ap-south-1, ap-southeast-1, ap-southeast-2, ap-northeast-1, ap-northeast-2 and ap-northeast-3, and a router can name any region the catalog lists for its variant. When the key is saved, Multi-Router checks the region, the access key id format and the session token length, and AWS checks the credentials on the first request. Multi-Router uses a Bedrock API key only in the key's region.

Temporary credentials with a session token expire, and AWS short-term Bedrock API keys last at most 12 hours, so long-running routers use an IAM user access key or a long-term Bedrock API key. The region and credentials of a saved key are fixed, and changing them means adding a new key; see Provider Key.

Regions and inference scopes

Each Bedrock request goes to one AWS region, which is the router's region or, when the router names none, the provider key's region. The router's variant then sets where inference runs: in_region keeps it in that region, geo keeps it in that region's geography, and global lets AWS run it in any region. A model not offered in the selected region and variant returns region_not_served with the regions where it is available. See Regions & Variants.

Models and features

Bedrock features depend on the model's publisher:

A request with a json_object or json_schema response format returns an error for every Bedrock model. Multi-Router downloads images sent as URLs and passes them to Bedrock as image data: an image URL must use HTTPS and return HTTP 200, with a PNG, JPEG, GIF or WebP content type, and an image of at most 5 MiB, within 10 seconds.

Errors and retries

Bedrock errors reach the caller as Multi-Router errors, with the AWS error in the response's upstream object. Multi-Router retries HTTP 429, 500, 502, 503, 504 and 529 responses, timeouts and connection failures, with exponential backoff and any whole-second retry delay AWS sends, within five minutes of the first attempt. Each attempt must receive a response within 120 seconds, so long outputs use streaming. When retries are exhausted, the request returns 429 upstream_rate_limit with the upstream code max_attempts_exceeded.

Errors that occur after a streaming response has started are returned as an error event in the stream.

Pricing

Bedrock prices differ by region and inference scope. Multi-Router records the cost of each request at the price of the region and variant that served it, including separate rates for prompt cache reads and cache writes on Claude models, and sends requests on Bedrock's standard on-demand tier. See Model Catalog.

Claude Code on Bedrock

A Claude Proxy on a Bedrock route serves Claude Code in its Bedrock mode. The Claude Proxy routes are Bedrock (Global), Bedrock (Geo) and Bedrock (In-region), each with a region set on the Claude Proxy, and the route and region decide where inference runs, whatever inference profile prefix the client sends. Multi-Router forwards the request body unchanged, replaces the model id with the route's id for the proxy's region, and signs the request with the organization's Bedrock key. Claude Proxy requests are sent to Bedrock once, without retries, and Bedrock's status and error body are returned to the client unchanged. The dashboard generates the environment for each developer:

export CLAUDE_CODE_USE_BEDROCK=1
export CLAUDE_CODE_SKIP_BEDROCK_AUTH=1
export ANTHROPIC_BEDROCK_BASE_URL='https://api.multi-router.ai/bedrock'
export ANTHROPIC_AUTH_TOKEN='<Multi-Router API key>'
export ANTHROPIC_CUSTOM_HEADERS='X-MR-Router: <router id>'

See Agents & Editors.

Providers & Models

Google Vertex

Connect a Google Cloud project to Multi-Router and route requests to Anthropic's Claude models on Vertex AI.

Google Vertex AI is Google Cloud's managed model platform, and Multi-Router uses it to serve Anthropic's Claude models from your Google Cloud project. A Vertex provider key holds a service account, its project and a location, and Multi-Router calls Vertex as that service account. Usage is billed by Google to the project, and Vertex quotas apply per project, model and location. Google's Gemini models are served through the Gemini provider; see Supported Providers.

Preparing your Google Cloud project

The Google Cloud project that serves requests needs the Vertex AI API, access to the Claude models, and a service account Multi-Router can use:

1. Enable the Vertex AI API in the project.
2. In Vertex AI Model Garden, enable each Claude model you will use.
3. Create a service account in the project. Its email ends in @<project-id>.iam.gserviceaccount.com; Google-managed accounts, such as the Compute Engine default service account, are not accepted.
4. Grant the service account the Vertex AI User role (roles/aiplatform.user), which allows Vertex AI predictions.
5. Create a JSON key for the service account and download it. If your organization enforces the iam.disableServiceAccountKeyCreation policy, an organization policy administrator must allow key creation for the project first.

Adding a Vertex provider key

A Vertex provider key holds one service account and the location requests run in. To add one, open LLM Provider Keys in the dashboard, add a key, and select Google Vertex:

The service account JSON must be the unmodified key file Google issues: its type is service_account, its token_uri is https://oauth2.googleapis.com/token, and it contains the project_id, the client_email of a service account in that project, a private_key_id and an RSA private_key. A file that breaks these rules is rejected with a message beginning Vertex service-account or metadata validation failed.

Multi-Router verifies the service account with Google when the key is saved and when its location is edited, and when it is enabled or made the default unless Multi-Router already holds a valid access token for it. A failed verification shows Google's response, such as Google OAuth token endpoint returned HTTP 400 (invalid_grant). Verification confirms that Google accepts the key file; the service account's role and model access are checked by the first request. A saved key's name, description and location can be edited, and later requests use the new location. The service account JSON is fixed, so rotating it means adding a new key and moving routers to it; see Provider Key.

Locations

The location is the Google Cloud location that runs each request, and for static routers it is always the location set on the provider key. Current Claude models are offered in the global, us and eu locations, and Claude Sonnet 4.6, Claude Opus 4.6 and earlier models are also offered in single regions such as us-east5, europe-west1 and asia-southeast1. A request for a model not offered in the key's location returns region_not_served with the locations where it is available.

To serve requests from several locations, add one provider key per location, using the same service account JSON in each, and set each router to the key for its location. Claude Proxies set the location on the Claude Proxy instead, so one key serves every location. See Regions & Variants for what each location type means.

Models and features

Multi-Router serves Anthropic's Claude models on Vertex, and a request for another publisher's model on Vertex returns publisher_not_supported. Claude models on Vertex support the following features:

Access tokens

An access token is the short-lived credential Multi-Router obtains from the service account to call Vertex, and Multi-Router renews it automatically before it expires. When the service account key is deleted in Google Cloud, requests continue until the current access token expires, within an hour, and then fail with a 503. To stop access immediately, disable the service account in Google Cloud or disable the provider key in Multi-Router.

Errors and retries

Vertex errors reach the caller as Multi-Router errors with Google's status in the response's upstream object. Multi-Router retries rate limits, server errors, timeouts and connection failures with exponential backoff, honoring any retry delay Google sends, for up to five attempts within five minutes.

Pricing

Vertex prices differ by location: for Claude Sonnet 4.5 and later models, the us, eu and single-region locations cost more than global, and earlier models cost the same in every location. Multi-Router bills each request at the price of the location that served it, including prompt cache reads, 5-minute and 1-hour cache writes, and long-context rates for prompts above the model's long-context threshold. See Model Catalog.

Claude Code on Vertex

A Claude Proxy on the Vertex AI route serves Claude Code in its Vertex mode. Multi-Router forwards the request body unchanged and sends it with the organization's Vertex key, the key's project, the location set on the Claude Proxy and the model id of the routed model; Claude Code's project and region settings are required by Claude Code and do not select the project or location. Claude Proxy requests are sent to Vertex once, without retries, and errors use Google's error format. The dashboard generates the environment for each developer:

export CLAUDE_CODE_USE_VERTEX=1
export CLAUDE_CODE_SKIP_VERTEX_AUTH=1
export ANTHROPIC_VERTEX_BASE_URL='https://api.multi-router.ai/vertex'
export ANTHROPIC_VERTEX_PROJECT_ID='<project id>'
export CLOUD_ML_REGION='<location>'
export ANTHROPIC_AUTH_TOKEN='<Multi-Router API key>'
export ANTHROPIC_CUSTOM_HEADERS='X-MR-Router: <router id>'

See Agents & Editors.

Providers & Models

Model Catalog

The catalog of every model Multi-Router serves: identities, capabilities, limits, prices, lifecycle and updates.

For each model, the catalog records the identity, mode, capabilities and limits, and for each offering of the model it records the provider, variant, regions, model ids and prices. Multi-Router uses the catalog to check every request before calling the provider, to select the model id sent upstream, and to compute the cost of each request. The catalog is versioned and published by Multi-Router, and every installation serves one catalog version at a time.

Model entries

A model entry describes one model independently of where it is served. The Models page shows these fields in the Baseline panel of each model:

The Baseline panel also lists the model's capabilities, input modalities and aliases, with a link to the publisher's documentation.

Modes

The mode is the type of work a model performs. The Chat Completions and Messages endpoints serve chat models, and a request for a model of another mode returns wrong_endpoint_for_mode.

Capabilities and modalities

Capabilities are the request features a model supports, and modalities are the content types it accepts and produces, such as text, image, audio, video and PDF. Multi-Router checks every chat request against the model's capabilities and its image input modality, and rejects a request that uses a feature the model lacks before calling the provider:

Offerings

An offering is one way to call a model: a provider and variant, with the regions where it is available. Each region carries the model id Multi-Router sends to the provider and the price. An offering can set limits or capabilities that differ from the model's baseline, such as a smaller context window on one provider, and an expanded offering on the Models page shows them as Capability overrides and as Context or Max output with the baseline value. The Offerings panel lists each offering's Vendor, Variant, Regions and Pricing, marks whether the variant is a fixed snapshot or a rolling version the provider updates, and marks custom offerings. Expanding an offering shows every region with its model id and prices. See Regions & Variants.

Prices

Prices are set for each region of each offering, in US dollars per million tokens unless noted, and are the providers' published list prices.

Multi-Router computes the cost of each request from the token counts, the number of web searches and the service tier the provider reports, and the price of the region the request was served in, and records it in Traffic, where it also counts toward budgets. A price part the catalog omits is charged at zero, and an offering whose provider publishes no price shows No pricing published on the Models page. Negotiated rates are applied with Custom Models & Pricing.

Lifecycle

The lifecycle status records whether a model is still offered. Each model has its own status, and each offering of a model can also have a status of its own:

A model or offering with a scheduled retirement time becomes retired at that time, without a new catalog version. Claude Proxies serve active models only, and refuse a deprecated or retired model with HTTP 404 and a message that names its status.

Browsing the catalog

The Models page in the dashboard lists every model in the catalog, including models from providers the organization holds no key for, together with the organization's model groups and the installation's custom models.

The Price column shows the lowest-to-highest input and output prices across every region, a model priced by unit shows its unit price, and a model with no published price shows a dash. Selecting a model opens its Baseline and Offerings panels. In an expanded offering that publishes more than one rate, the Rate switch selects among the rates it publishes, such as Standard, Long Context, Batch, Priority, Flex, Fast and Tools.

Listing models with the API

GET /v1/models lists the chat models the API token's organization can call: models that are active or deprecated and have an offering that is not retired from a provider for which the organization holds an enabled provider key, together with custom endpoint models when the organization holds a Custom endpoint key. The endpoint requires the models:read scope and returns the OpenAI list format, sorted by publisher and slug. In each entry, owned_by is the publisher and created is the publication time of the catalog version in effect, which is the same for every model. The full catalog, with every model's offerings, regions and prices, is read with GET /v1/catalog/models and GET /v1/catalog/models/{publisher}/{model}, with the same scope; see Catalog.

curl https://api.multi-router.ai/v1/models \
  -H "Authorization: Bearer $MR_API_KEY"

{
  "object": "list",
  "data": [
    { "id": "anthropic/claude-haiku-4.5", "object": "model", "created": 1790812800, "owned_by": "anthropic" },
    { "id": "anthropic/claude-sonnet-4.6", "object": "model", "created": 1790812800, "owned_by": "anthropic" }
  ]
}

With an x-mr-router header that names a Claude Proxy, the endpoint returns the models that Claude Proxy serves in the Anthropic format, which Claude Code uses to list its models, sorted by id. Each entry carries the model id the proxy's route uses, the display name, the release date at midnight UTC, and the token limits. A header that names any other kind of router returns 404.

{
  "data": [
    {
      "type": "model",
      "id": "claude-sonnet-4-6",
      "display_name": "Claude Sonnet 4.6",
      "created_at": "2026-02-17T00:00:00Z",
      "max_input_tokens": 1000000,
      "max_tokens": 128000
    }
  ],
  "has_more": false,
  "first_id": "claude-sonnet-4-6",
  "last_id": "claude-sonnet-4-6"
}

Catalog updates

Multi-Router publishes the catalog as numbered versions at models.multi-router.ai, and a published version never changes. A new version adds models and offerings, updates prices, and records deprecations and retirements. Multi-Router manages catalog updates on the hosted service. On a self-hosted installation, the server administrator controls them on the Catalog tab of the Admin page:

Every fetched version is validated before use, a version that fails validation is skipped, and automatic updates only move forward. Upgrading the server installs the catalog bundled with the new release when it is newer than the version in effect. While an installation serves a catalog bundled with its release, the Models page shows a banner stating the version and that model data may be out of date. See Self-Hosting.

Errors

Catalog checks on chat requests return HTTP 400 with the following errors, in addition to the capability errors above. In a fallback router, a member that fails a catalog check is skipped and the next member is tried.

Providers & Models

Model Group

Define named sets of approved models, and use them to control which models people and Claude Code can call.

A model group is a named list of models that an organization approves for a purpose, such as the models engineers can use from Claude Code. Each member of a group is a model on a specific provider, optionally pinned to a variant and region, so a group describes exactly where each approved model runs. A model group belongs to one organization and has an id prefixed with mg_.

Members

A member is one approved model in a group, defined by the following fields:

Multi-Router checks every member against the catalog when the group is saved: the model must exist, the provider must offer it, and the variant and region, when given, must be an active offering. Members on a custom endpoint skip the catalog checks. A group holds at most 100 members and contains each model at most once, and an empty group is valid but serves no requests. Group names are up to 80 characters and descriptions up to 2,000 characters, names can repeat, and a group carries up to 20 tags of up to 80 characters each. Multi-Router trims every field, lowercases provider ids and tags, and removes duplicate tags.

On the Models page, a member whose model, offering or region is no longer in the catalog is marked Stale, and a custom endpoint member is marked Custom. A provider key pinned to a member cannot be deleted or moved to another organization until the member no longer names it.

Where model groups are used

A model group takes effect through the Claude Proxies and tools policies that name it:

Both uses run on the Custom route with organization credentials, so a group used by either must contain only Claude models that Claude Proxies serve, and every member must name a variant and a region. The Claude Proxy or policy assigns a provider key to each model in the group, so each member can run on a different provider, variant and region, such as one model on Anthropic and another on AWS Bedrock geo in eu-central-1. A model added to a group that a Claude Proxy uses is served once the Claude Proxy assigns it a provider key.

Managing groups in the dashboard

Model groups are managed on the Models page. The Show filter switches between All, Models and Groups, and each group appears as a row marked Group with its name and id. Organization admins create, edit and delete groups; organization members can view them.

1. Select New group, and enter the Group name and an optional Description.
2. Select Add models. The picker lists models with their publisher, vendors, offerings, context window and price; open a model to choose an offering, which is a vendor and variant, and its region.
3. Select Create group, which reads Add & create while picked models are still to be added.

Expanding a group's row shows Group details (id, members, publishers, creation and change dates, and description), Used by, with the number of Claude Proxies and policies that use the group and links to the routers, and Tags, where the group's tags are edited. Edit group changes the name, description and members, and shows Reach, the number of routers and policies a change affects, before it is saved.

Editing and deleting groups

An edit to a group applies to every Claude Proxy that uses it without editing the Claude Proxy, and must keep every member a model the Claude Proxy serves. A group named by a policy cannot be edited or deleted; to change the models a policy allows, select a different group in the policy. A group used by a Claude Proxy cannot be deleted until the Claude Proxy uses a different group.

API

The /v1/model-groups endpoints manage the model groups of the API token's organization. Scopes are cumulative: model_groups:delete includes write, and write includes read.

curl -X POST https://api.multi-router.ai/v1/model-groups \
  -H "Authorization: Bearer $MR_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Engineering models",
    "description": "Approved for Claude Code",
    "members": [
      { "provider": "anthropic", "model": "anthropic/claude-sonnet-4.5", "variant": "standard", "region": "global" },
      { "provider": "bedrock", "model": "anthropic/claude-haiku-4.5", "variant": "geo", "region": "eu-central-1" }
    ],
    "tags": ["production"]
  }'

{
  "organization_id": "org_7Tq2Wd9KxP",
  "data": {
    "id": "mg_4kT9wQx2Lp",
    "object": "model_group",
    "etag": "\"1\"",
    "name": "Engineering models",
    "description": "Approved for Claude Code",
    "members": [
      { "provider": "anthropic", "model": "anthropic/claude-sonnet-4.5", "variant": "standard", "region": "global", "provider_key_id": null },
      { "provider": "bedrock", "model": "anthropic/claude-haiku-4.5", "variant": "geo", "region": "eu-central-1", "provider_key_id": null }
    ],
    "tags": ["production"],
    "created_at": "2026-09-30T18:02:11Z",
    "updated_at": "2026-09-30T18:02:11Z"
  }
}

Members and tags change only through their own endpoints, each conditional on the group's ETag. A member is selected by its full model slug in the model query parameter:

curl -X DELETE "https://api.multi-router.ai/v1/model-groups/mg_4kT9wQx2Lp/members?model=anthropic/claude-haiku-4.5" \
  -H "Authorization: Bearer $MR_API_KEY" \
  -H 'If-Match: "1"'

The routers response lists each router that uses the group:

{
  "organization_id": "org_7Tq2Wd9KxP",
  "data": [
    { "id": "rt_Qm7c2HsP0a", "object": "router", "name": "claude-code-eng", "kind": "claude_proxy" }
  ],
  "next_cursor": null,
  "has_more": false
}

Errors

Creating, editing and deleting model groups return the following errors:

Providers & Models

Custom Models & PricingEnterprise

Apply negotiated provider prices to catalog models, and add models served from your own endpoints with their own prices.

Custom models extend the model catalog with entries a server administrator defines. A custom variant copies a catalog offering, such as Claude Sonnet 4.5 on Google Vertex, and gives it the prices from your agreement with the provider, so the costs Multi-Router records match what you pay. A custom endpoint model adds a model the catalog does not carry, served by an endpoint you operate, with its own wire ids and prices.

Custom variants

A custom variant is a copy of one catalog offering, identified by the model, provider and variant, with new prices. The copy keeps the offering's regions, wire ids, capabilities, limits, lifecycle and retirement date, and is added to the model as a new variant on the same provider, so the catalog offering stays available beside it. Because it is a copy, later catalog changes to the source offering, including price changes and retirement, do not change it. A router or model group member that names the custom variant is billed at the negotiated prices, and routers that name the catalog variant continue at list price.

To create a custom variant in the dashboard:

1. On the Models page, select Clone with new pricing.
2. Under Model, search the catalog by name or slug and select the model.
3. Under Offering to copy, select the offering. Each row shows its Vendor, Variant, Regions and List pricing.
4. Under Name and prices, enter a name, such as Vertex (Negotiated Pricing), and edit the prices, which are prefilled with the list prices for every region. A price box left empty is not charged.
5. Select Create custom variant.