Skip to content
Extrovert Extrovert Docs

Browse the category registry (Review Loop, agent plane)

GET
/v1/categories

List the customer’s categories (id + name + description + scope + state) so a sending agent can fuzzy-match an existing one before composing. The optional match is a pure lexical/substring filter (NO LLM on our side); the agent does the semantic matching. Categories are CUSTOMER-scoped and agent- attributed (the deliberate cross-agent-404 exception); identity is opaque cat_ ids (D10).

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Query Parameters

Section titled “Query Parameters ”
match
string

Lexical substring filter over name+description+slug (every token must match; NO LLM).

sort
string
default: popular
Allowed values: popular messages_7d messages_90d last_used pending_reviews name

30-day popularity by default; last use and category ID break ties. Semantic fit remains the agent’s choice.

limit
integer
default: 100 >= 1 <= 200
page
string

Opaque next_cursor from the preceding page. Keep match and sort unchanged.

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Ok

object
items
required
Array<object>

A category (cat_…) in the registry (Review Loop, D9/D10). name + description are the skill-style metadata an agent fuzzy-matches against (NO LLM on our side; the agent does the matching). Categories are CUSTOMER-scoped and agent-attributed; nothing keys on the name (renames never break a reference).

object
message_count_7d

Logical accepted messages created in the last 7 days in the authorized project.

integer
message_count_30d

Logical accepted messages created in the last 30 days in the authorized project.

integer
message_count_90d

Logical accepted messages created in the last 90 days in the authorized project.

integer
last_used_at

Most recent accepted message creation time; absent when unused.

string format: date-time
pending_review_count

Current nonterminal reviews across composers in the authorized project.

integer
active_rule_count

Active category rules visible in the authorized project; excludes retired and superseded versions.

integer
id
required

Opaque category id (cat_…).

string
name
required
string
description
required
string
scope
required
string
Allowed values: org_shared agent_private
state
required
string
Allowed values: supervised auto_notify auto_silent
merged_into

Survivor category id when this one was merged/soft-deleted (cat_…).

string
created_by_agent_id
string
author_kind
required
string
Allowed values: agent human connection
rule_high_water
required
integer
rules_version
required
integer
never_graduate

Human lock pinning the category at supervised (no live auto-send; D16).

boolean
clean_approval_count

Clean human-approve-as-is count toward the maturity gate (D16).

integer
drift_count

Human edit/reject count in a graduated category toward drift auto-demote (K; §7).

integer
graduated_at

When the category was last graduated (omitted if never).

string format: date-time
graduated_by

Who last graduated it (‘human:’); empty if never/demoted.

string
created_at
string format: date-time
updated_at
string format: date-time
total
required
integer
next_cursor

Opaque next page cursor.

string

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
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

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
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