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
| Method | Path | Description | Scope |
|---|---|---|---|
| GET | /v1/model-groups | List model groups. Paginated. | model_groups:read |
| POST | /v1/model-groups | Create 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}/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. Returns 201. | model_groups:write |
| PATCH | /v1/model-groups/{id}/members | Change the member named by the model query parameter. | model_groups:write |
| DELETE | /v1/model-groups/{id}/members | Remove the member named by the model query parameter. | 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 |
Member and tag writes are conditional on the group's ETag.
Body
A create has these fields:
| Field | Type |
|---|---|
name | string, required |
| 1 to 80 characters. | |
description | string or null |
| Up to 2,000 characters. | |
members | array |
| Up to 100 members, each with provider, model, and optionally variant, region and provider_key_id. | |
tags | array |
| 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.
Errors
| Code | Status | Meaning |
|---|---|---|
invalid_model_group | 400 | The body is malformed or a field is invalid. |
model_group_not_found | 404 | The id matches no model group. |
model_not_found | 404 | The group has no member with that model. |
tag_not_found | 404 | The group has no such tag. |
model_group_member_exists | 409 | The model 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. |
model_group_referenced | 409 | A delete names a group that routers use. |
model_group_policy_managed | 409 | The group belongs to a tools policy. |
model_group_incompatible_with_claude_proxy | 409 | The change would leave a Claude Proxy using the group with models it cannot serve. |
Was this helpful?