Merge a category into another (console plane, human authority)

POST

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

• Production
• Local

Merge the path category (the loser) into into_category_id (the survivor), repointing all rr_/rule_ references BY cat_ id and setting merged_into on the loser in ONE transaction (D9/D10), plus a merge transition + audit/undo row. A cross-tenant or unknown into_category_id is 404 (never a cross-customer merge); merging into itself is 400. Console-only.

Authorizations

• ClerkSession

Parameters

Path Parameters

org_id

required

string

project_id

required

string

id

required

string

Request Body ^required

Merge the path category (the loser) into into_category_id (the survivor), repointing all rr_/rule_ references by cat_ id in one transaction (D9/D10). A cross-tenant or unknown into_category_id is 404 (never a cross-customer merge).

object

into_category_id

required

The survivor category id (cat_…).

string

Responses

200

Merged.

The survivor category plus how many references were repointed by the merge.

object

category

required

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

review_requests_repointed

required

integer

writing_rules_repointed

required

integer

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

409

Resource conflict (e.g. a duplicate entry).

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