# Get the organization's assistant settings

> The assistant.settings.get operation: GET /api/v1/assistant/settings in the REST API and the assistant_settings_get tool in the MCP server.

Returns the organization's settings for the in-platform assistant (Organization → Security → Assistant):

- `enabled`: whether members can use the assistant (on by default);
- `allowCustomerData`: whether it may read customer and financial data. Off leaves only the docs, the tax
  knowledge base and settings (on by default);
- `retentionDays`: conversations are deleted this many days after their last message (90 by default).

`usage` shows this month's messages (UTC) against the plan's `assistant.messages_per_month`. `version` is 0 while
the defaults apply.

## At a glance

- **REST:** `GET /api/v1/assistant/settings`
- **MCP tool:** `assistant_settings_get`
- **Operation ID:** `assistant.settings.get`
- **Scope:** Organization
- **Permission:** `security:read`
- **Risk tier:** `read`
- **Dry run:** Not supported
- **Idempotency:** Not needed (read only)
- **Modes:** Test and live
- **Authentication:** API key with the `security:read` scope
- **Since:** M11

## Request

### Query parameters

This operation takes no query parameters.

## 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

### The defaults

```http
GET /api/v1/assistant/settings
Authorization: Bearer or_test_…
```

Response (`200`):

```json
{
  "object": "assistant_settings",
  "enabled": true,
  "allowCustomerData": true,
  "retentionDays": 90,
  "version": 0,
  "updatedAt": null,
  "usage": {
    "month": "2026-10",
    "messages": 42,
    "limit": 1000,
    "included": true
  }
}
```

## Errors

| Code                                                                                   | HTTP status | When                                                 | What to do                                                                      |
| -------------------------------------------------------------------------------------- | ----------- | ---------------------------------------------------- | ------------------------------------------------------------------------------- |
| [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied) | 403         | You can't read 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): [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed), [`api_version_unsupported`](https://ownrecord.io/docs/reference/errors.md#api_version_unsupported), [`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), [`dry_run_not_supported`](https://ownrecord.io/docs/reference/errors.md#dry_run_not_supported), [`rate_limited`](https://ownrecord.io/docs/reference/errors.md#rate_limited), [`internal_error`](https://ownrecord.io/docs/reference/errors.md#internal_error).