# Update the organization's assistant settings

> The assistant.settings.update operation: PATCH /api/v1/assistant/settings in the REST API and the assistant_settings_update tool in the MCP server.

Changes the organization's assistant settings (Organization → Security → Assistant): turn it on or off, allow
or stop its access to customer and financial data, and set how long conversations are kept after their last
message (1–365 days). A shorter retention applies to existing conversations at the next retention run.

A security-tier change: it decides what data reaches the assistant's language model. Needs `security:write`
(organization owners and admins). Send `expectedVersion` to make sure nobody changed them in between.

## At a glance

- **REST:** `PATCH /api/v1/assistant/settings`
- **MCP tool:** `assistant_settings_update`
- **Operation ID:** `assistant.settings.update`
- **Scope:** Organization
- **Permission:** `security:write`
- **Risk tier:** `security`
- **Dry run:** Supported (send `Ownrecord-Dry-Run: true`)
- **Idempotency:** `Idempotency-Key` optional
- **Modes:** Test and live
- **Authentication:** API key with the `security:write` scope
- **Since:** M11

## Request

### Body

A JSON object (`Content-Type: application/json`):

| Field               | Type                 | Required | Description                                                                                  |
| ------------------- | -------------------- | -------- | -------------------------------------------------------------------------------------------- |
| `enabled`           | boolean              | No       | Turn the assistant on or off for the organization's members.                                 |
| `allowCustomerData` | boolean              | No       | Let the assistant read customer and financial data. Off leaves docs, knowledge and settings. |
| `retentionDays`     | integer (1 to 365)   | No       | Days a conversation is kept after its last message (1–365).                                  |
| `expectedVersion`   | integer (at least 0) | No       | The `version` you read (0 while the defaults apply): a newer change is a conflict.           |

## Response

`200 OK` with a JSON object:

| Field               | Type                   | Description                                                                                       |
| ------------------- | ---------------------- | ------------------------------------------------------------------------------------------------- |
| `object`            | `"assistant_settings"` |                                                                                                   |
| `enabled`           | boolean                | The assistant is on for the organization's members.                                               |
| `allowCustomerData` | boolean                | The assistant may read customer and financial data; off leaves only docs, knowledge and settings. |
| `retentionDays`     | integer                | Conversations are deleted this many days after their last message.                                |
| `version`           | integer (at least 0)   | 0 while the defaults apply. Send it as `expectedVersion` to update.                               |
| `updatedAt`         | date-time or null      |                                                                                                   |
| `usage`             | object                 |                                                                                                   |
| `usage.month`       | string                 | The calendar month (UTC), `YYYY-MM`.                                                              |
| `usage.messages`    | integer (at least 0)   | Messages the organization's members sent this month.                                              |
| `usage.limit`       | integer or null        | The plan's `assistant.messages_per_month`; null without one.                                      |
| `usage.included`    | boolean                | The plan includes the assistant (`assistant.enabled`).                                            |

## Examples

### Keep the assistant away from customer data, and conversations for 30 days

```http
PATCH /api/v1/assistant/settings
Authorization: Bearer or_test_…
Content-Type: application/json

{
  "allowCustomerData": false,
  "retentionDays": 30,
  "expectedVersion": 0
}
```

Response (`200`):

```json
{
  "object": "assistant_settings",
  "enabled": true,
  "allowCustomerData": false,
  "retentionDays": 30,
  "version": 1,
  "updatedAt": "2026-10-26T09:15:00.000Z",
  "usage": {
    "month": "2026-10",
    "messages": 42,
    "limit": 1000,
    "included": true
  }
}
```

## Errors

| Code                                                                                   | HTTP status | When                                                           | What to do                                                                      |
| -------------------------------------------------------------------------------------- | ----------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed) | 400         | No setting was sent, or the retention is outside 1–365 days.   | Fix the fields listed in `details.issues` and send the request again.           |
| [`version_conflict`](https://ownrecord.io/docs/reference/errors.md#version_conflict)   | 409         | The settings changed since `expectedVersion`; read them again. | Fetch the object again and retry the change.                                    |
| [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied) | 403         | You can't change the organization's security settings.         | Ask an organization owner or admin for a role or scope that allows this action. |

It can also return these [common errors](https://ownrecord.io/docs/reference.md#common-errors): [`api_version_unsupported`](https://ownrecord.io/docs/reference/errors.md#api_version_unsupported), [`invalid_json`](https://ownrecord.io/docs/reference/errors.md#invalid_json), [`unsupported_media_type`](https://ownrecord.io/docs/reference/errors.md#unsupported_media_type), [`authentication_required`](https://ownrecord.io/docs/reference/errors.md#authentication_required), [`api_key_invalid`](https://ownrecord.io/docs/reference/errors.md#api_key_invalid), [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found), [`idempotency_key_reused`](https://ownrecord.io/docs/reference/errors.md#idempotency_key_reused), [`idempotency_in_progress`](https://ownrecord.io/docs/reference/errors.md#idempotency_in_progress), [`approval_required`](https://ownrecord.io/docs/reference/errors.md#approval_required), [`approval_rejected`](https://ownrecord.io/docs/reference/errors.md#approval_rejected), [`approval_expired`](https://ownrecord.io/docs/reference/errors.md#approval_expired), [`stale_approval`](https://ownrecord.io/docs/reference/errors.md#stale_approval), [`approval_policy_denied`](https://ownrecord.io/docs/reference/errors.md#approval_policy_denied), [`rate_limited`](https://ownrecord.io/docs/reference/errors.md#rate_limited), [`internal_error`](https://ownrecord.io/docs/reference/errors.md#internal_error).