# Update vocabulary settings

Change the organization's vocabulary settings. Needs the right to manage the team vocabulary. Send the `revision` you read as `expected_revision`; a newer stored revision answers 409. Switching on `automatic` sharing makes the caller the person whose rights it writes with; saving while it is paused does the same and resumes it.

#### Request Body

**`learn_from_corrections`** boolean optional

Whether corrections teach private vocabulary.

**`learned_sharing_mode`** string optional

`approval` or `automatic`.

**`share_threshold`** integer optional

Colleagues needed, from 3 to 50.

**`shared_target_list_id`** string optional

A list the caller can edit; an explicit null means the organization list.

**`suggestions_enabled`** boolean optional

Whether suggestions are collected.

**`expected_revision`** integer required

The `revision` the caller read; a different stored revision answers 409.

## Returns

The updated vocabulary settings:

**`learn_from_corrections`** boolean

Whether a person's corrections teach their own private vocabulary.

**`learned_sharing_mode`** string

How words several colleagues taught reach the shared list: `approval` (an administrator approves each) or `automatic`.

**`share_threshold`** integer

How many colleagues must have taught a word before it is proposed for the shared list.

**`shared_target_list_id`** string

The list shared words go to; the organization list unless another list was chosen.

**`suggestions_enabled`** boolean

Whether suggestions are collected.

**`automatic_state`** string

`off` in approval mode; `active`, or `paused` when automatic sharing stopped by itself.

**`automatic_paused_reason`** string or null

Why automatic sharing is paused, when it is.

**`revision`** integer

The settings revision; send it back as `expected_revision`.

**`editable`** boolean

Whether the caller may change the settings.

Example

```bash cURL
curl -X PATCH "https://api.aitronos.com/v1/vocabulary/settings" \
  -H "X-API-Key: $FREDDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"share_threshold": 5, "expected_revision": 4}'
```


```python Python
import os
import requests

api_key = os.environ["FREDDY_API_KEY"]

response = requests.patch(
    "https://api.aitronos.com/v1/vocabulary/settings",
    headers={"X-API-Key": api_key},
    json={"share_threshold": 5, "expected_revision": 4},
)

print(response.json())
```


```javascript JavaScript
const apiKey = process.env.FREDDY_API_KEY;

const response = await fetch('https://api.aitronos.com/v1/vocabulary/settings', {
  method: 'PATCH',
  headers: {
    'X-API-Key': apiKey,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({"share_threshold": 5, "expected_revision": 4})
});

const data = await response.json();
console.log(data);
```

**Response:**


```json 200 OK
{
  "learn_from_corrections": true,
  "learned_sharing_mode": "approval",
  "share_threshold": 5,
  "shared_target_list_id": "voclist_1b7d5e9f3a2c4680",
  "suggestions_enabled": true,
  "automatic_state": "off",
  "automatic_paused_reason": null,
  "revision": 5,
  "editable": true
}
```

Errors

```json 401 Unauthorized
{
  "success": false,
  "error": {
    "code": "AUTHENTICATION_REQUIRED",
    "message": "Authentication required. Please provide a valid API key.",
    "system_message": "Missing or invalid authorization header",
    "type": "authentication_error",
    "status": 401,
    "details": {},
    "trace_id": "req_7d1e4b9a2c",
    "timestamp": "2026-10-24T09:30:00Z"
  }
}
```


```json 403 Forbidden
{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "You do not have permission to perform this action.",
    "system_message": "Caller lacks the rights this operation needs.",
    "type": "authorization_error",
    "status": 403,
    "details": {},
    "trace_id": "req_7d1e4b9a2c",
    "timestamp": "2026-10-24T09:30:00Z"
  }
}
```


```json 409 Conflict
{
  "success": false,
  "error": {
    "code": "VOCABULARY_SETTINGS_REVISION_CONFLICT",
    "message": "The settings changed since you loaded them. Reload and try again.",
    "system_message": "Stale expected_revision.",
    "type": "client_error",
    "status": 409,
    "details": {
      "current_revision": 5
    },
    "trace_id": "req_7d1e4b9a2c",
    "timestamp": "2026-10-24T09:30:00Z"
  }
}
```


```json 422 Unprocessable Entity
{
  "success": false,
  "error": {
    "code": "VOCABULARY_SETTINGS_INVALID",
    "message": "This vocabulary setting is not valid.",
    "system_message": "Invalid vocabulary setting.",
    "type": "validation_error",
    "status": 422,
    "details": {
      "field": "share_threshold"
    },
    "trace_id": "req_7d1e4b9a2c",
    "timestamp": "2026-10-24T09:30:00Z"
  }
}
```

## Related Resources

- [Vocabulary API](/api-reference/vocabulary/_index) — Overview of lists, entries and settings.
- [Create an access grant](/api-reference/access-control/create-grant) — Share a vocabulary list with people, teams or the whole organization.