Rename / re-describe a category (console plane, human authority)

PATCH

/v1/admin/orgs/{org_id}/projects/{project_id}/categories/{id}

• Production
• Local

Rename / re-describe a category with author_kind=human (metadata only, D10); writes a rename/redescribe audit/undo row. Console-only (never an MCP tool, D17). Customer-scoped; a foreign id is 404.

Authorizations

• ClerkSession

Parameters

Path Parameters

org_id

required

string

project_id

required

string

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