Skip to content
Extrovert Extrovert Docs

Create a category from the console

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

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters ”
org_id
required
string
project_id
required
string

Request Body required

Section titled “Request Body required ”

Create a human-authored shared category from the console.

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

Section titled “ Responses ”

201

Section titled “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

Section titled “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

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

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