Upsert one UI preference

PATCH

/ui-preferences

curl --request PATCH \
  --url https://example.com/api/v1/ui-preferences \
  --header 'Content-Type: application/json' \
  --data '{ "section_key": "example", "mode": "basic", "expected_updated_at": "2026-04-15T12:00:00Z" }'

• API v1

Creates or updates the stored disclosure mode for a section key.

Payloads include optional concurrency token expected_updated_at.

Request Body^required

Media typeapplication/json

object

section_key

required

Canonical progressive disclosure section key

string

<= 96 characters /^[a-z0-9-]+:[a-z0-9-]+:[a-z0-9-]+$/

mode

required

Disclosure visibility mode for the section

string

Allowed values: basic advanced

expected_updated_at

Optional optimistic concurrency token

string format: date-time

nullable

Responses

200

UI preference persisted

Media typeapplication/json

object

section_key

required

Canonical progressive disclosure section key

string

<= 96 characters /^[a-z0-9-]+:[a-z0-9-]+:[a-z0-9-]+$/

mode

required

Disclosure visibility mode for the section

string

Allowed values: basic advanced

updated_at

required

string format: date-time

nullable

persisted

required

boolean

Example

{
  "mode": "basic"
}

400

Validation error

Media typeapplication/json

object

error

required

string

code

Optional machine-readable error code, for example sync_in_progress or preview_stale

string

Example^generated

{
  "error": "example",
  "code": "example"
}

401

Authentication required

Media typeapplication/json

object

error

required

string

code

Optional machine-readable error code, for example sync_in_progress or preview_stale

string

Example^generated

{
  "error": "example",
  "code": "example"
}

409

Concurrency conflict

Media typeapplication/json

object

error

required

string

code

Optional machine-readable error code, for example sync_in_progress or preview_stale

string

Example^generated

{
  "error": "example",
  "code": "example"
}

429

Preference updates are being rate-limited

Media typeapplication/json

object

error

required

string

code

Optional machine-readable error code, for example sync_in_progress or preview_stale

string

Example^generated

{
  "error": "example",
  "code": "example"
}

500

Failed to save preference

Media typeapplication/json

object

error

required

string

code

Optional machine-readable error code, for example sync_in_progress or preview_stale

string

Example^generated

{
  "error": "example",
  "code": "example"
}