Upsert one complexity tier

PATCH

/complexity-tiers

curl --request PATCH \
  --url https://example.com/api/v1/complexity-tiers \
  --header 'Content-Type: application/json' \
  --data '{ "section_key": "example", "tier": "beginner", "expected_updated_at": "2026-04-15T12:00:00Z", "interaction_delta": 1, "advanced_toggle_delta": 1, "last_suggested_tier": "beginner", "suggestion_dismissed_at": "2026-04-15T12:00:00Z" }'

• API v1

Creates or updates the stored complexity tier for a section key.

Payloads include optional concurrency token expected_updated_at. Activity deltas are bounded and may be used to drive non-intrusive progression suggestions.

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-]+$/

tier

required

Progressive complexity tier for the section

string

Allowed values: beginner intermediate advanced

expected_updated_at

Optional optimistic concurrency token

string format: date-time

nullable

interaction_delta

Optional bounded interaction counter increment

integer

advanced_toggle_delta

Optional bounded advanced-toggle counter increment

integer

last_suggested_tier

Any of:

string

Progressive complexity tier for the section

string

Allowed values: beginner intermediate advanced

suggestion_dismissed_at

string format: date-time

nullable

Responses

200

Complexity tier 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-]+$/

tier

required

Progressive complexity tier for the section

string

Allowed values: beginner intermediate advanced

interaction_count

required

integer

advanced_toggle_count

required

integer

last_suggested_tier

required

Any of:

string

Progressive complexity tier for the section

string

Allowed values: beginner intermediate advanced

suggestion_dismissed_at

required

string format: date-time

nullable

updated_at

required

string format: date-time

nullable

persisted

required

boolean

Example

{
  "tier": "beginner",
  "last_suggested_tier": "beginner"
}

400

Validation error

Media typeapplication/json

object

error

required

string

Example^generated

{
  "error": "example"
}

401

Authentication required

Media typeapplication/json

object

error

required

string

Example^generated

{
  "error": "example"
}

409

Concurrency conflict

Media typeapplication/json

object

error

required

string

Example^generated

{
  "error": "example"
}

429

Complexity tier updates are being rate-limited

Media typeapplication/json

object

error

required

string

Example^generated

{
  "error": "example"
}

500

Failed to save complexity tier

Media typeapplication/json

object

error

required

string

Example^generated

{
  "error": "example"
}