# Auto model

Auto picks the model, the reasoning effort and the speed tier for every message sent with `model: "auto"`, inside the rules an organisation sets. These endpoints read and change those rules, show who gets what, preview a rule, hold each person's own priority, explain a single reply's pick, and report what Auto spent.

Read [Auto Model](/docs/documentation/core-concepts/auto-model) first: it explains the layers (organisation, departments, assistant, person, chat), what "enforced" and "people can choose" mean, and how a pick is made.

## Availability

Every endpoint here sits behind the `auto_model` feature switch. While it is off for the caller's organisation, each one answers `404` with code `AUTO_MODEL_NOT_ENABLED` (`error.details.feature` is `auto_model`), so a client can hide the feature instead of treating it as a wrong address. Key on the code, not the message.

The organisation is the one in the path where there is one; otherwise the request's current organisation (the `X-Organization-Id` header, or the token's organisation).

## Endpoints

### Rules (organisation admins, assistant editors)

- [List Auto model rules](/docs/api-reference/auto-model/list-rules) — `GET /v1/organizations/{organization_id}/auto-model/rules`
- [Get an Auto model rule](/docs/api-reference/auto-model/get-rule) — `GET /v1/organizations/{organization_id}/auto-model/rules/{scope_type}/{scope_id}`
- [Create or replace an Auto model rule](/docs/api-reference/auto-model/update-rule) — `PUT /v1/organizations/{organization_id}/auto-model/rules/{scope_type}/{scope_id}`
- [Delete an Auto model rule](/docs/api-reference/auto-model/reset-rule) — `DELETE /v1/organizations/{organization_id}/auto-model/rules/{scope_type}/{scope_id}`
- [Preview an Auto model rule](/docs/api-reference/auto-model/simulate) — `POST /v1/organizations/{organization_id}/auto-model/simulate`
- [Check who gets what](/docs/api-reference/auto-model/get-effective-settings) — `GET /v1/organizations/{organization_id}/auto-model/effective`
- [Set a member's primary department](/assets/set-primary-department.6fcb4d3279c9dca14f79a0f3a84dda0ad07ff85db955150a3d01388050bbd9d1.31e6e729.md) — `PUT /v1/organizations/{organization_id}/members/{user_id}/primary-department`


### People

- [Get the Auto model option catalogue](/docs/api-reference/auto-model/get-catalog) — `GET /v1/auto-model/catalog`
- [Get my Auto priority](/docs/api-reference/auto-model/get-my-choice) — `GET /v1/users/me/auto-model`
- [Set my Auto priority](/docs/api-reference/auto-model/set-my-choice) — `PUT /v1/users/me/auto-model`
- [Get why Auto picked a reply's model](/docs/api-reference/threads/get-message-route) — `GET /v1/threads/{thread_id}/messages/{message_id}/route`


### Analytics

- [Get Auto model analytics](/docs/api-reference/auto-model/analytics) — `GET /v1/analytics/auto-model/{org_id}`


### In other endpoints

- [Create a response](/docs/api-reference/responses/create) — `model: "auto"`, `auto_choice`, `auto_retry`
- [Streaming events](/docs/api-reference/objects/streaming-event-object) — `response.model_selected`
- [Update per-thread user state](/docs/api-reference/threads/update-per-thread-user-state) — `auto_choice`
- [List models](/docs/api-reference/models/list) — the `auto` entry


## Objects

- [Auto model rule object](/docs/api-reference/objects/auto-model-rule-object)
- [Auto model route object](/docs/api-reference/objects/auto-model-route-object)


## Error codes

| Code | HTTP | When |
|  --- | --- | --- |
| `AUTO_MODEL_NOT_ENABLED` | 404 | Auto is not switched on for the organisation |
| `AUTO_MODEL_SCOPE_NOT_FOUND` | 404 | The department, assistant or person is not in the organisation |
| `AUTO_MODEL_RULE_INVALID` | 422 | A rule's settings fail validation; `details.field` names the setting |
| `AUTO_MODEL_MODEL_NOT_ALLOWED` | 422 | A picked model the organisation or assistant does not allow; `details.models` lists them |
| `AUTO_MODEL_EFFORT_RANGE_EMPTY` | 422 | The effort range does not overlap the inherited one |
| `AUTO_MODEL_LOOSENS_ENFORCED` | 403 | An assistant editor tries to loosen an enforced limit or lock; `details.locked_by` names the layer |
| `AUTO_MODEL_CHOICE_LOCKED` | 409 | A person's or chat's priority while a rule decides it; `details.locked_by`, `details.reason` |
| `AUTO_MODEL_PRIMARY_DEPARTMENT_INVALID` | 422 | The member is not in that department |
| `AUTO_MODEL_POOL_EMPTY` | 422 | A turn with no model left; `details.rule`, `details.why` |
| `AUTO_MODEL_ROUTE_NOT_FOUND` | 404 | No Auto choice is recorded for that message (or it expired after 90 days) |


Another organisation in the path answers the platform's `403 ORGANIZATION_ACCESS_DENIED`, the same as every organisation endpoint.

## Related Resources

- [Auto Model concept](/docs/documentation/core-concepts/auto-model)
- [List models](/docs/api-reference/models/list)
- [Create a response](/docs/api-reference/responses/create)