Skip to content
Extrovert Extrovert Docs

Propose graduating a category (agent plane; cannot flip the bit)

POST
/v1/categories/{id}/graduation-request

RECORD an agent’s request to graduate this category (D16/D6). It writes a durable, NON-MUTATING request transition (evidence for the human to review) and returns the current graduation gate status. It does NOT change the category state; flipping the graduation bit is a human (console) action. A never_graduate category records the request but stays locked. A foreign id is 404.

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters ”
id
required
string

Request Body

Section titled “Request Body ”

Record an agent’s request to graduate a category (D16/D6). evidence is an opaque agent-supplied object stored on the request transition for the human to review. It does NOT flip the bit.

object
evidence
object
key
additional properties
any

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Ok

The graduation gate status toward the NEXT rung (Review Loop, D16). Reports clean approvals (N / needed), category age, the maturity gate (auto_silent precondition), the drift counter vs K, and whether a human graduate would succeed right now (can_graduate). Read-only; agents propose but never flip the bit.

object
category_id
required
string
state
required
string
Allowed values: supervised auto_notify auto_silent
next_state
required

The rung a graduate would move to (empty if none).

string
never_graduate
required

Pinned at supervised (high-stakes lock).

boolean
clean_approval_count
required
integer
graduate_min_approvals
required
integer
approvals_met
required
boolean
age_hours
required
number format: double
graduate_min_age_hours
required
integer
age_met
required
boolean
maturity_gate_met
required
boolean
drift_count
required
integer
drift_demote_after
required
integer
can_graduate
required
boolean

400

Section titled “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

401

Section titled “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

403

Section titled “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

404

Section titled “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