Get the organization's assistant settings

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`	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: validation_failed, api_version_unsupported, authentication_required, api_key_invalid, resource_not_found, dry_run_not_supported, rate_limited, internal_error.

At a glance#

Request#

Query parameters#

Response#

Examples#

The defaults#

Errors#