multi-router.aidocs

API Reference

Model Groups

Creating, reading, changing and deleting model groups, their members and tags, and finding the routers that use them.

The model groups endpoints manage an organization's model groups, the approved sets of models that Claude Proxies and tools policies use. They need the model_groups:read, model_groups:write or model_groups:delete scope. See Model Group.

Endpoints

MethodPathDescriptionScope
GET/v1/model-groupsList model groups. Paginated.model_groups:read
POST/v1/model-groupsCreate a model group. Returns 201. Accepts an Idempotency-Key.model_groups:write
GET/v1/model-groups/{id}Get one model group.model_groups:read
PATCH/v1/model-groups/{id}Change name and description.model_groups:write
DELETE/v1/model-groups/{id}Delete a group no router or policy uses. 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. Returns 201.model_groups:write
PATCH/v1/model-groups/{id}/membersChange the member named by the model query parameter.model_groups:write
DELETE/v1/model-groups/{id}/membersRemove the member named by the model query parameter.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

Member and tag writes are conditional on the group's ETag.

Body

A create has these fields:

FieldType
namestring, required
1 to 80 characters.
descriptionstring or null
Up to 2,000 characters.
membersarray
Up to 100 members, each with provider, model, and optionally variant, region and provider_key_id.
tagsarray
Tag names.

A member PATCH takes provider, variant, region and provider_key_id, with null clearing a field; the member is selected by its full model slug in ?model=, never in the body.

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",
    "members": [
      { "provider": "anthropic", "model": "anthropic/claude-opus-5" },
      { "provider": "anthropic", "model": "anthropic/claude-sonnet-4.5" }
    ]
  }'
Change one memberbash
curl -X PATCH "https://api.multi-router.ai/v1/model-groups/mg_4kT9wQx2Lp/members?model=anthropic/claude-sonnet-4.5" \
  -H "Authorization: Bearer $MR_API_KEY" \
  -H 'If-Match: "2"' \
  -H "Content-Type: application/json" \
  -d '{ "provider_key_id": "llpk_4Vd8Qm2RtL" }'

Errors

CodeStatusMeaning
invalid_model_group400The body is malformed or a field is invalid.
model_group_not_found404The id matches no model group.
model_not_found404The group has no member with that model.
tag_not_found404The group has no such tag.
model_group_member_exists409The model 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.
model_group_referenced409A delete names a group that routers use.
model_group_policy_managed409The group belongs to a tools policy.
model_group_incompatible_with_claude_proxy409The change would leave a Claude Proxy using the group with models it cannot serve.
IntegrationsPrompts
Was this helpful?