Propose a new category (agent plane)

POST

/v1/categories

• Production
• Local

Create a category on the fly (D9). It stands IMMEDIATELY (author_kind=agent, state supervised) and writes a create audit/undo row. Returns the cat_…; match the registry first so you do not duplicate an existing bucket.

Authorizations

• AgentKey
  mailbox:read

Request Body ^required

Propose a new category on the fly (D9). It stands immediately (author_kind= agent, state supervised) and writes a create audit/undo row.

object

name

required

Display name (mutable metadata; never a reference key).

string

description

Skill-style matcher text the agent reads (mutable).

string

scope

Defaults to org_shared.

string

Allowed values: org_shared agent_private

Responses

201

Created.

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

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

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