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:
| Field | Required | Description |
|---|---|---|
provider | Yes | The provider id, such as anthropic or bedrock, or custom for a custom endpoint. See Supported Providers. |
model | Yes | The model slug, such as anthropic/claude-sonnet-4.5. Multi-Router accepts any capitalization of the slug and returns the catalog's form. |
variant | No | The variant of the model on the provider, such as standard or geo. See Regions & Variants. |
region | No | The region of the variant. A member with a region must also name a variant. |
provider_key_id | No | A 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 by | Meaning of membership |
|---|---|
| Adaptive Routers | The 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 Proxies | On the Custom route, the models the Claude Proxy serves. A request for a model outside the group is refused. |
| Tools policies | On 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.
- Select New group, and enter the Group name and an optional Description.
- 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.
- 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.
| Method | Path | Description | Scope |
|---|---|---|---|
| POST | /v1/model-groups | Create a group. Returns 201 with the group. Accepts an Idempotency-Key. | model_groups:write |
| GET | /v1/model-groups | List 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}/routers | List the routers that use the group. | model_groups:read |
| GET | /v1/model-groups/{id}/members | List the members. | model_groups:read |
| POST | /v1/model-groups/{id}/members | Add a member. | model_groups:write |
| PATCH | /v1/model-groups/{id}/members | Change the member named by ?model=: its provider, variant, region or provider_key_id. | model_groups:write |
| DELETE | /v1/model-groups/{id}/members | Remove the member named by ?model=. | model_groups:delete |
| GET | /v1/model-groups/{id}/tags | List the group's tags. | model_groups:read |
| POST | /v1/model-groups/{id}/tags | Add a tag, sent as tag. | model_groups:write |
| DELETE | /v1/model-groups/{id}/tags/{key} | Remove a tag. | model_groups:delete |
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:
The routers response lists each router that uses the group:
Errors
Creating, editing and deleting model groups return the following errors:
| Error | Status | Cause |
|---|---|---|
invalid_model_group | 400 | The body is not valid JSON, is missing a required field such as a member's provider or model, or is over 64 KB. |
invalid_name | 400 | The name is empty or over 80 characters. |
invalid_description | 400 | The description is over 2,000 characters. |
invalid_tags | 400 | A tag breaks the tag rules, or the group has more than 20 tags. |
too_many_members | 400 | The group has more than 100 members. |
invalid_member | 400 | A member has an empty model or names a provider Multi-Router does not support. |
model_not_found | 400 | A member names a model that is not in the catalog. |
provider_offering_not_found | 400 | A member's provider does not offer its model. |
variant_required | 400 | A member names a region without a variant. |
variant_not_found | 400 | A member's provider does not offer its variant. |
offering_not_active | 400 | A member's variant is deprecated or retired. |
region_not_served | 400 | A member's variant is not offered in its region. The message lists the available regions. |
region_not_supported | 400 | The catalog lists a member's region, but Multi-Router cannot serve it. |
duplicate_member | 400 | The group contains the same model twice. |
provider_key_not_found | 400 | A member's provider key is not in the organization. |
provider_key_disabled | 400 | A member's provider key is disabled. |
provider_key_mismatch | 400 | A member's provider key is for a different provider. |
key_residency_mismatch | 400 | An OpenAI member's provider key is set to a different region than the member. |
model_group_not_found | 404 | The group does not exist in the organization. |
model_group_referenced | 409 | The group is used by a Claude Proxy and cannot be deleted. The message lists the routers. |
model_group_policy_managed | 409 | The group is named by a policy and cannot be edited or deleted. |
model_group_incompatible_with_claude_proxy | 409 | An edit adds a model that a Claude Proxy using the group does not serve. |
model_group_member_exists | 409 | A member add names a model that is already a member. |
use_sub_collection | 400 | A 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_conflict | 412 | The If-Match ETag is stale. The response carries the current group. |