Update the assistant's platform settings

Platform admins: changes the in-platform assistant's model, its ordered fallbacks, the provider base URL and the platform-wide monthly spend cap, stored in platform_settings. Null resets a setting to the environment's value. The cap is sent as a decimal USD string and stored as integer micros; the assistant alerts platform staff at 80% and refuses messages at 100% until the next month (UTC).

A security-tier change: the base URL and model decide where conversations are processed. Provider routing (no data collection, zero data retention, never DeepSeek's own API) applies whatever is set here.

At a glance

REST: PATCH /api/v1/platform/assistant/settings
MCP tool: assistant_platform_settings_update
Operation ID: assistant.platform_settings.update
Scope: Platform
Permission: platform:admin
Risk tier: security
Dry run: Supported (send Ownrecord-Dry-Run: true)
Idempotency: Idempotency-Key optional
Modes: Test and live
Authentication: API key with the platform:admin scope
Fresh sign-in: In the console, a sign-in within the last 15 minutes
Since: M11

Request

Body

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

Field	Type	Required	Description
`model`	string or null	No	The model, e.g. `deepseek/deepseek-v4.1-flash`; null: the environment's.
`fallbackModels`	array of string or null	No	Ordered fallbacks (OpenRouter `models`); null: the environment's.
`baseUrl`	string or null	No	The provider base URL, https only, on a public host; null: `OPENROUTER_BASE_URL`.
`monthlyBudgetUsd`	string or null	No	The platform-wide monthly spend cap in USD (decimal string); null: the environment's.

Response

200 OK with a JSON object:

Field	Type	Description
`object`	`"assistant_platform_settings"`
`model`	string or null	The OpenRouter model; null: `ASSISTANT_MODEL`.
`fallbackModels`	array of string or null	Ordered fallbacks; null: `ASSISTANT_FALLBACK_MODELS`.
`baseUrl`	string or null	The provider base URL; null: `OPENROUTER_BASE_URL`.
`monthlyBudgetMicros`	string or null	The platform-wide monthly spend cap in integer USD micros; null: `ASSISTANT_MONTHLY_BUDGET_USD`.
`version`	integer (at least 1)
`updatedAt`	date-time

Examples

Cap the assistant at USD 1,500 a month

HTTP

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

{
  "monthlyBudgetUsd": "1500"
}

Response (200):

JSON

{
  "object": "assistant_platform_settings",
  "model": null,
  "fallbackModels": null,
  "baseUrl": null,
  "monthlyBudgetMicros": "1500000000",
  "version": 2,
  "updatedAt": "2026-10-26T09:15:00.000Z"
}

Errors

Code	HTTP status	When	What to do
`fresh_auth_required`	403	Your last sign-in is older than 15 minutes: sign in again first.	Sign in again, then repeat the action within 15 minutes.
`validation_failed`	400	Nothing was sent, or a value is malformed (the base URL must be https).	Fix the fields listed in `details.issues` and send the request again.
`version_conflict`	409	The platform settings changed at the same time; retry.	Fetch the object again and retry the change.
`permission_denied`	403	You aren't a platform admin.	Ask an organization owner or admin for a role or scope that allows this action.
`resource_not_found`	404	The platform isn't bootstrapped yet.	Check the ID and that your credentials are scoped to the right organization, entity, brand and mode.

It can also return these common errors: api_version_unsupported, invalid_json, unsupported_media_type, authentication_required, api_key_invalid, idempotency_key_reused, idempotency_in_progress, rate_limited, internal_error.

At a glance#

Request#

Body#

Response#

Examples#

Cap the assistant at USD 1,500 a month#

Errors#