multi-router.aidocs

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:

FieldRequiredDescription
providerYesThe provider id, such as anthropic or bedrock, or custom for a custom endpoint. See Supported Providers.
modelYesThe model slug, such as anthropic/claude-sonnet-4.5. Multi-Router accepts any capitalization of the slug and returns the catalog's form.
variantNoThe variant of the model on the provider, such as standard or geo. See Regions & Variants.
regionNoThe region of the variant. A member with a region must also name a variant.
provider_key_idNoA provider key to pin to the member: an enabled key of the member's provider in the same organization. An OpenAI key must be set to the member's region.

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 Adaptive Routers, Claude Proxies and tools policies that name it:

Used byMeaning of membership
Adaptive RoutersThe members the router serves, each on its own provider, variant and region. Rules choose among them, and a request for a model outside the group is refused.
Claude ProxiesOn the Custom route, the models the Claude Proxy serves. A request for a model outside the group is refused.
Tools policiesOn the Custom route, the models the people assigned to the policy can call from Claude Code or Claude Desktop. The Portal lists them under Allowed models.

The Claude Proxy and tools policy 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.

Engineering · org_7Tq2Wd9KxP

All models· Models• modified

New groupSave view
Show:
AllModelsGroups
Status:
AllActiveDeprecated
Filters
Search id / name / alias / vendor id…
Models2 of 2 · 2 groups · 0 models
1–2 of 225 / page
Columns
NameKindPublisherVendorsCapabilitiesContextPrice
Engineering modelsgroupmg_4kT9wQx2Lp1 publisherAnthropicBedrock2 models, 2 variants across 2 vendors200K$1.10–$3.00 in $5.50–$15.00 out
Group details
ID
mg_4kT9wQx2Lp
Members
2
Publishers
anthropic
Created
9/30/2026
Last changed
9/30/2026
Description
Approved for Claude Code
Used by
Claude proxies1
Auto routers0
Policies1

Changes here apply to all 2 consumers.

claude-code-engrt_Qm7c2HsP0a
Tags
productionAdd tag
Delete blocked
Remove this group from the consumers above before deleting it.
Members — what this group allows
Edit group
ModelPublisherVendorVariantRegionContextPrice
Claude Sonnet 4.5AnthropicAnthropicStandardglobal200K$3.00 · $15.00
Claude Haiku 4.5AnthropicBedrockGeoeu-central-1200K$1.10 · $5.50
Bedrock EUgroupmg_7HcXr2Nq0b1 publisherBedrock2 models, 1 variant across 1 vendor200K$1.10–$3.30 in $5.50–$16.50 out
The Models page filtered to Groups, with the Engineering models group expanded. Select to enlarge.
  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.
Engineering · org_7Tq2Wd9KxP

All models· Models

New groupSave view
Show:
AllModelsGroups
Status:
AllActiveDeprecated
Filters
Search id / name / alias / vendor id…
Models281 of 281 · 0 groups · 281 models
1–25 of 28125 / page
Columns
New model group
Engineering models
Approved for Claude Code
ModelPublisherVendorVariantRegionContextPrice
Claude Sonnet 4.5AnthropicAnthropicStandardglobal200K$3.00 · $15.00
ModelsClaude Haiku 4.5Anthropic5 ways to call it
VendorVariantReleaseRegion5 shown
VendorVariantRegionsContextPrice
  • Anthropic1 Oct 2025 snapshotsnapshotPinned to the 1 Oct 2025 model snapshot.1 region200K$1.00 · $5.00
  • AnthropicStandardrollingThe vendor's ordinary endpoint for this model.1 region200K$1.00 · $5.00
  • BedrockGeosnapshotInference stays inside one geography (US, EU, APAC, Japan or Australia).18 regions200K$1.10 · $5.50
  • BedrockGlobalsnapshotInference may run in any AWS region. Cheapest, with no residency guarantee.33 regions200K$1.00 · $5.00
  • Vertex AIStandardsnapshotThe vendor's ordinary endpoint for this model.4 regions200K$1.00–1.10 · $5.00–5.50
Region is not picked here. It is resolved per call from whatever the chosen variant serves — client geo intent first, then the router region, then the provider key region, then the organization default.
1 variant ticked
CancelAdd to group
CancelAdd & create
NameKindPublisherVendorsCapabilitiesContextPrice
Claude Haiku 4.5AnthropicAnthropic×2Bedrock×2Vertex AI200K$1.00–1.10 / $5.00–5.50
Claude Opus 4.5AnthropicAnthropic×2Bedrock×2Vertex AI200K$5.00–5.50 / $25.00–27.50
Claude Sonnet 4.5AnthropicAnthropic×2Bedrock×2Vertex AI200K$3.00–3.30 / $15.00–16.50
The New model group panel with one member added and a Bedrock Geo offering staged from the picker. Select to enlarge.

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.

MethodPathDescriptionScope
POST/v1/model-groupsCreate a group. Returns 201 with the group. Accepts an Idempotency-Key.model_groups:write
GET/v1/model-groupsList groups, paged with limit (1 to 200, default 50) and cursor.model_groups:read
GET/v1/model-groups/{id}Get one group.model_groups:read
PATCH/v1/model-groups/{id}Change name or description; description: null clears it.model_groups:write
DELETE/v1/model-groups/{id}Delete a group. Accepts dry_run.model_groups:delete
GET/v1/model-groups/{id}/routersList the routers that use the group.model_groups:read
GET/v1/model-groups/{id}/membersList the members.model_groups:read
POST/v1/model-groups/{id}/membersAdd a member.model_groups:write
PATCH/v1/model-groups/{id}/membersChange the member named by ?model=: its provider, variant, region or provider_key_id.model_groups:write
DELETE/v1/model-groups/{id}/membersRemove the member named by ?model=.model_groups:delete
GET/v1/model-groups/{id}/tagsList the group's tags.model_groups:read
POST/v1/model-groups/{id}/tagsAdd a tag, sent as tag.model_groups:write
DELETE/v1/model-groups/{id}/tags/{key}Remove a tag.model_groups:delete
Create a model groupbash
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"]
  }'
Response 201json
{
  "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:

Remove a memberbash
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:

GET /v1/model-groups/mg_4kT9wQx2Lp/routersjson
{
  "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:

ErrorStatusCause
invalid_model_group400The body is not valid JSON, is missing a required field such as a member's provider or model, or is over 64 KB.
invalid_name400The name is empty or over 80 characters.
invalid_description400The description is over 2,000 characters.
invalid_tags400A tag breaks the tag rules, or the group has more than 20 tags.
too_many_members400The group has more than 100 members.
invalid_member400A member has an empty model or names a provider Multi-Router does not support.
model_not_found400A member names a model that is not in the catalog.
provider_offering_not_found400A member's provider does not offer its model.
variant_required400A member names a region without a variant.
variant_not_found400A member's provider does not offer its variant.
offering_not_active400A member's variant is deprecated or retired.
region_not_served400A member's variant is not offered in its region. The message lists the available regions.
region_not_supported400The catalog lists a member's region, but Multi-Router cannot serve it.
duplicate_member400The group contains the same model twice.
provider_key_not_found400A member's provider key is not in the organization.
provider_key_disabled400A member's provider key is disabled.
provider_key_mismatch400A member's provider key is for a different provider.
key_residency_mismatch400An OpenAI member's provider key is set to a different region than the member.
model_group_not_found404The group does not exist in the organization.
model_group_referenced409The group is used by a Claude Proxy and cannot be deleted. The message lists the routers.
model_group_policy_managed409The group is named by a policy and cannot be edited or deleted.
model_group_incompatible_with_claude_proxy409An edit adds a model that a Claude Proxy using the group does not serve.
model_group_member_exists409A member add names a model that is already a member.
use_sub_collection400A PATCH sends members or tags, which change through their own endpoints. The valid field of the error lists the endpoint path template, such as /v1/model-groups/{id}/members; {id} is not replaced with the object id.
version_conflict412The If-Match ETag is stale. The response carries the current group.
Model CatalogCustom Models & Pricing
Was this helpful?