Update the organization's assistant settings

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`	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`	409	The settings changed since `expectedVersion`; read them again.	Fetch the object again and retry the change.
`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: api_version_unsupported, invalid_json, unsupported_media_type, authentication_required, api_key_invalid, resource_not_found, idempotency_key_reused, idempotency_in_progress, approval_required, approval_rejected, approval_expired, stale_approval, approval_policy_denied, rate_limited, internal_error.

At a glance#

Request#

Body#

Response#

Examples#

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

Errors#