Browse the category registry (Review Loop, agent plane)

GET

/v1/categories

• Production
• Local

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

• AgentKey
  mailbox:read

Parameters

Query Parameters

match

string

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

Responses

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

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

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

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

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