Rename / re-describe a category (agent plane, metadata only)

PUT

/v1/categories/{id}

• Production
• Local

Update a category’s name and/or description; metadata ONLY (D10). Renaming never breaks a reference because nothing keys on the name. Any agent in the customer may edit (the shared-registry exception); a rename/redescribe undo row is written (the audit/undo safety net, D11).

Authorizations

• AgentKey
  mailbox:read

Parameters

Path Parameters

id

required

string

Request Body ^required

Rename / re-describe a category; metadata ONLY (D10). Either field may be omitted (unchanged).

object

name

string

description

string

Responses

200

Ok

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

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