# Create or replace an Auto model rule

Save the Auto model rule of the organisation, a department or an assistant. The body replaces the scope's whole rule: a setting you leave out inherits from the layer above. The rule is checked against the models the scope allows and the inherited effort range, an assistant editor's attempt to loosen an enforced limit is refused, and the saved rule comes back with its clashes. Creating and updating both answer `200 OK`. See [Auto Model](/docs/documentation/core-concepts/auto-model).

## Authentication

Requires authentication (Bearer token or `x-api-key`). Organisation and department rules need the `manage_users` capability; an assistant's rule is also open to that assistant's editors, who cannot loosen anything enforced above (`403 AUTO_MODEL_LOOSENS_ENFORCED`). An organisation admin saving values looser than the rules above is not refused: the rule is stored and its `clashes` say which values have no effect. Requires the Auto model to be switched on for the organisation.

#### Path Parameters

**`organization_id`** string required

The organisation (`org_` prefix).

**`scope_type`** string required

`organization`, `department` or `assistant`.

**`scope_id`** string required

The organisation id, a department id (`dept_`) or an assistant id (`asst_`) of this organisation.

#### Request Body

**`settings`** object required

The rule's settings; every field is optional and an omitted or `null` field inherits. Unknown fields are refused.

- **`enabled`** boolean — `false` switches Auto off for this scope and below.
- **`preset`** string — `balanced`, `faster`, `lower_cost`, `best_quality` or `custom`.
- **`weights`** object — `quality`, `speed`, `cost` (each 0 to 1, at least 0.05, adding up to 1; normalised on save). Only with `preset: "custom"`, and required then.
- **`pool`** object — `mode`: `all_allowed` (every model the scope allows, including future ones) or `pick`; `models`: model keys, used with `pick`.
- **`effort`** object — `min` and `max`, each `off`, `low`, `medium`, `high` or `max`; must overlap the inherited range.
- **`max_chf_per_message`** string or number — Cost limit per message in CHF (above 0, at most 100, up to 4 decimals); cannot raise an inherited limit.
- **`allow_priority_tier`** boolean — Whether Auto may use the priority speed tier.


**`enforced`** boolean optional · Defaults to `false`

Lock this rule's preset for every scope and person below it. An enforced rule must set a `preset`.

**`people_can_choose`** boolean optional

Whether people below this scope may choose their own preset; `null` (the default) inherits.

**`locked_reason`** string optional

Up to 280 characters, shown to people who cannot change the setting because of this rule.

## Returns

Returns `200 OK` with the saved [Auto model rule object](/docs/api-reference/objects/auto-model-rule-object), including its `clashes`.

Request

```bash cURL
curl -X PUT https://api.aitronos.com/v1/organizations/org_7d2c9e41a5b84f0e/auto-model/rules/department/dept_5a1c7e2b9d4f4a8e \
  -H "X-API-Key: $FREDDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {"preset": "lower_cost", "max_chf_per_message": "0.10"},
    "enforced": true,
    "people_can_choose": false,
    "locked_reason": "Support runs on a fixed budget"
  }'
```


```python Python SDK
from aitronos import Aitronos

client = Aitronos(api_key="your-api-key")

rule = client.auto_model.put_auto_model_rule(
    organization_id="org_7d2c9e41a5b84f0e",
    scope_type="department",
    scope_id="dept_5a1c7e2b9d4f4a8e",
    settings={"preset": "lower_cost", "max_chf_per_message": "0.10"},
    enforced=True,
    people_can_choose=False,
    locked_reason="Support runs on a fixed budget",
)
print(rule)
```


```python Python
import os
import requests

response = requests.put(
    "https://api.aitronos.com/v1/organizations/org_7d2c9e41a5b84f0e/auto-model/rules/department/dept_5a1c7e2b9d4f4a8e",
    headers={"X-API-Key": os.environ["FREDDY_API_KEY"]},
    json={
        "settings": {"preset": "lower_cost", "max_chf_per_message": "0.10"},
        "enforced": True,
        "people_can_choose": False,
        "locked_reason": "Support runs on a fixed budget",
    },
)
print(response.json())
```


```javascript JavaScript
const response = await fetch(
  'https://api.aitronos.com/v1/organizations/org_7d2c9e41a5b84f0e/auto-model/rules/department/dept_5a1c7e2b9d4f4a8e',
  {
    method: 'PUT',
    headers: { 'X-API-Key': process.env.FREDDY_API_KEY, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      settings: { preset: 'lower_cost', max_chf_per_message: '0.10' },
      enforced: true,
      people_can_choose: false,
      locked_reason: 'Support runs on a fixed budget',
    }),
  },
);
const rule = await response.json();
console.log(rule.clashes);
```

200 OK

```json
{
  "exists": true,
  "scope": {"type": "department", "id": "dept_5a1c7e2b9d4f4a8e", "name": "Support", "people": 37, "sub_departments": 0},
  "settings": {"preset": "lower_cost", "max_chf_per_message": "0.10"},
  "enforced": true,
  "people_can_choose": false,
  "locked_reason": "Support runs on a fixed budget",
  "inherited": {
    "preset": "balanced",
    "weights": {"quality": 0.6, "speed": 0.2, "cost": 0.2},
    "effort": {"min": "low", "max": "high"},
    "max_chf_per_message": "0.50",
    "allow_priority_tier": false,
    "people_can_choose": true,
    "enabled": true,
    "pool": {"mode": "all_allowed", "models": []},
    "locked_by": null,
    "locked_reason": null,
    "provenance": {
      "preset": {"layer": "platform", "scope_id": null, "name": "Platform default"},
      "effort": {"layer": "organization", "scope_id": "org_7d2c9e41a5b84f0e", "name": "Organisation"},
      "max_chf_per_message": {"layer": "organization", "scope_id": "org_7d2c9e41a5b84f0e", "name": "Organisation"}
    }
  },
  "bounds": {
    "effort": {"min": "low", "max": "high"},
    "max_chf_per_message": "0.50",
    "models": ["ftg-4", "ftg-4-pro", "ftg-4-light"],
    "excluded": []
  },
  "clashes": [
    {"kind": "shadows", "rule": {"type": "assistant", "id": "asst_2b9e4c1d7a3f4e6b", "name": "Support Bot"}, "setting": "preset", "value": null, "people": 37}
  ],
  "updated_at": "2026-10-24T12:05:00Z",
  "updated_by": {"id": "usr_3e8b1f6c2a7d4c9e", "name": "Alex Meier"}
}
```

Errors

```json 422 Unprocessable Entity
{
  "success": false,
  "error": {
    "code": "AUTO_MODEL_RULE_INVALID",
    "message": "This Auto model rule isn't valid. Check the highlighted setting.",
    "type": "validation_error",
    "status": 422,
    "details": {"field": "settings", "reason": "value_error"},
    "trace_id": "641d4f27-68ac-4da5-893a-4c5a36b4f3c3",
    "timestamp": "2026-10-27T04:51:34Z"
  }
}
```


```json 422 Unprocessable Entity (model)
{
  "success": false,
  "error": {
    "code": "AUTO_MODEL_MODEL_NOT_ALLOWED",
    "message": "One of the picked models isn't allowed here.",
    "type": "validation_error",
    "status": 422,
    "details": {"models": ["ftg-4-pro"]},
    "trace_id": "2f1e0d9c-8b7a-4c6d-9e5f-4a3b2c1d0e9f",
    "timestamp": "2026-10-27T04:51:34Z"
  }
}
```


```json 422 Unprocessable Entity (effort)
{
  "success": false,
  "error": {
    "code": "AUTO_MODEL_EFFORT_RANGE_EMPTY",
    "message": "This thinking-effort range doesn't overlap the range set above it.",
    "type": "validation_error",
    "status": 422,
    "details": {"inherited": {"min": "low", "max": "high"}},
    "trace_id": "3a2b1c0d-9e8f-4a7b-8c6d-5e4f3a2b1c0d",
    "timestamp": "2026-10-27T04:51:34Z"
  }
}
```


```json 403 Forbidden
{
  "success": false,
  "error": {
    "code": "AUTO_MODEL_LOOSENS_ENFORCED",
    "message": "This rule would loosen a limit set above it, which you can't change.",
    "type": "authorization_error",
    "status": 403,
    "details": {"setting": "max_chf_per_message", "locked_by": {"layer": "department", "scope_id": "dept_5a1c7e2b9d4f4a8e", "name": "Support"}},
    "trace_id": "4b3c2d1e-0f9a-4b8c-9d7e-6f5a4b3c2d1e",
    "timestamp": "2026-10-27T04:51:34Z"
  }
}
```


```json 404 Not Found
{
  "success": false,
  "error": {
    "code": "AUTO_MODEL_SCOPE_NOT_FOUND",
    "message": "We couldn't find that department or assistant in this organisation.",
    "type": "client_error",
    "status": 404,
    "details": {"scope_type": "department", "scope_id": "dept_doesnotexist"},
    "trace_id": "9c729929-ce98-41c6-8b7d-142d9a13862f",
    "timestamp": "2026-10-27T04:51:33Z"
  }
}
```


```json 404 Not Found (switched off)
{
  "success": false,
  "error": {
    "code": "AUTO_MODEL_NOT_ENABLED",
    "message": "Auto isn't available for this organisation.",
    "type": "client_error",
    "status": 404,
    "details": {"feature": "auto_model"},
    "trace_id": "5c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
    "timestamp": "2026-10-27T04:51:33Z"
  }
}
```

## Related Resources

- [Auto Model concept](/docs/documentation/core-concepts/auto-model)
- [Auto model rule object](/docs/api-reference/objects/auto-model-rule-object)
- [Get an Auto model rule](/docs/api-reference/auto-model/get-rule)
- [Preview an Auto model rule](/docs/api-reference/auto-model/simulate)
- [Delete an Auto model rule](/docs/api-reference/auto-model/reset-rule)
- [List Auto model rules](/docs/api-reference/auto-model/list-rules)