Set a category's risk-dial overrides (console plane, human authority)

PATCH

/v1/admin/orgs/{org_id}/projects/{project_id}/categories/{id}/risk-dial

• Production
• Local

Set / clear the per-category risk-dial OVERRIDES (D12). For each field, a non-null value SETS the override; an explicit JSON null RESETS it back to inherit (null = account default); an omitted field is unchanged. Console-only (never an MCP tool, D17). A foreign id is 404.

Authorizations

• ClerkSession
• AgentKey
  account:admin

Parameters

Path Parameters

org_id

required

string

project_id

required

string

id

required

string

Request Body ^required

Set / clear a category’s risk-dial overrides (console plane, D12). For each field, a non-null value SETS the override; an explicit JSON null RESETS it to inherit; an omitted field is unchanged.

object

min_confidence

number format: double

nullable

first_contact_gate

boolean

nullable

drift_demote_after

integer

nullable

canary_rate

number format: double

nullable

graduate_min_approvals

integer

nullable

graduate_min_age_hours

integer

nullable

Responses

200

Ok

One category’s risk-dial OVERRIDE columns (null = inherit the account default; D12) alongside the resolved effective dial. A null field means the category inherits that value from the account default.

object

category_id

required

string

min_confidence

number format: double

nullable

first_contact_gate

boolean

nullable

drift_demote_after

integer

nullable

canary_rate

number format: double

nullable

graduate_min_approvals

integer

nullable

graduate_min_age_hours

integer

nullable

effective

required

The RESOLVED risk dial for a category: the account default with any per- category override applied (null override = inherit; D12). Every field is a concrete value already in force.

object

min_confidence

required

number format: double

first_contact_gate

required

boolean

drift_demote_after

required

integer

canary_rate

required

number format: double

graduate_min_approvals

required

integer

graduate_min_age_hours

required

integer

auto_send_cap_per_day

required

integer

400

Invalid request.

The canonical error envelope. error is a stable machine code.

object

error

required

Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).

string

Example

forbidden

message

Human-readable detail (never leaks internals).

string

Example

missing required scope

reason

Machine-readable quota reason. inbox_limit_exceeded means billing account inbox capacity across all organizations and projects sharing that account; enrollment_token_mailbox_budget_exhausted means the enrollment key lifetime creation allowance. Read message for recovery; inbox counts are separate from sending quotas.

string

used

Consumed plus reserved units.

integer format: int64

delta

Requested additional units.

integer format: int64

limit

integer format: int64

remaining

integer format: int64

consumed

integer format: int64

reserved

integer format: int64

next_reset_at

Next UTC usage-period boundary; pending reservations survive this boundary.

string format: date-time

upgrade_required

boolean

401

Missing or invalid credential.

The canonical error envelope. error is a stable machine code.

object

error

required

Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).

string

Example

forbidden

message

Human-readable detail (never leaks internals).

string

Example

missing required scope

reason

Machine-readable quota reason. inbox_limit_exceeded means billing account inbox capacity across all organizations and projects sharing that account; enrollment_token_mailbox_budget_exhausted means the enrollment key lifetime creation allowance. Read message for recovery; inbox counts are separate from sending quotas.

string

used

Consumed plus reserved units.

integer format: int64

delta

Requested additional units.

integer format: int64

limit

integer format: int64

remaining

integer format: int64

consumed

integer format: int64

reserved

integer format: int64

next_reset_at

Next UTC usage-period boundary; pending reservations survive this boundary.

string format: date-time

upgrade_required

boolean

403

Authenticated but lacking the required scope, or out of quota.

The canonical error envelope. error is a stable machine code.

object

error

required

Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).

string

Example

forbidden

message

Human-readable detail (never leaks internals).

string

Example

missing required scope

reason

Machine-readable quota reason. inbox_limit_exceeded means billing account inbox capacity across all organizations and projects sharing that account; enrollment_token_mailbox_budget_exhausted means the enrollment key lifetime creation allowance. Read message for recovery; inbox counts are separate from sending quotas.

string

used

Consumed plus reserved units.

integer format: int64

delta

Requested additional units.

integer format: int64

limit

integer format: int64

remaining

integer format: int64

consumed

integer format: int64

reserved

integer format: int64

next_reset_at

Next UTC usage-period boundary; pending reservations survive this boundary.

string format: date-time

upgrade_required

boolean

404

Resource not found.

The canonical error envelope. error is a stable machine code.

object

error

required

Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).

string

Example

forbidden

message

Human-readable detail (never leaks internals).

string

Example

missing required scope

reason

Machine-readable quota reason. inbox_limit_exceeded means billing account inbox capacity across all organizations and projects sharing that account; enrollment_token_mailbox_budget_exhausted means the enrollment key lifetime creation allowance. Read message for recovery; inbox counts are separate from sending quotas.

string

used

Consumed plus reserved units.

integer format: int64

delta

Requested additional units.

integer format: int64

limit

integer format: int64

remaining

integer format: int64

consumed

integer format: int64

reserved

integer format: int64

next_reset_at

Next UTC usage-period boundary; pending reservations survive this boundary.

string format: date-time

upgrade_required

boolean