API reference
10 operations in taxonomy. Raw spec: openapi.json.
GET
/api/v1/taxonomy/categoriesGET /api/taxonomy/categories — the two-level category tree, flat and ordered (roots and subcategories interleaved by sort order; `parent_id` reconstructs the tree).
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
include_retired | query | boolean | No | Include retired nodes (admin editors + the manifest want them; pickers default to false). |
Responses
| Status | Description |
|---|---|
200 |
Security: bearer
POST
/api/v1/taxonomy/categoriesPOST /api/taxonomy/categories — create a root category, or a subcategory when `parent_id` names a root of this org.
Request body
CreateTaxonomyNodeRequest
Responses
| Status | Description |
|---|---|
200 | |
404 | parent category not found |
409 | duplicate sibling name or idempotency key reused |
Security: bearer
PATCH
/api/v1/taxonomy/categories/{id}PATCH /api/taxonomy/categories/{id} — rename / edit description / re-sort (root or subcategory).
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes |
Request body
UpdateTaxonomyNodeRequest
Responses
| Status | Description |
|---|---|
200 | |
404 | node not visible in scope (rls_sparse) |
409 | duplicate sibling name, version conflict, or idempotency key reused |
Security: bearer
POST
/api/v1/taxonomy/categories/{id}/reparentPOST /api/taxonomy/categories/{id}/reparent — move a SUBCATEGORY under a different root. Roots cannot be reparented (that would grow a third level or orphan children).
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes |
Request body
ReparentCategoryRequest
Responses
| Status | Description |
|---|---|
200 | |
404 | node or new parent not visible in scope (rls_sparse) |
409 | version conflict or idempotency key reused |
Security: bearer
POST
/api/v1/taxonomy/categories/{id}/retirePOST /api/taxonomy/categories/{id}/retire — soft-retire a root or subcategory. Idempotent like the type surface.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes |
Request body
RetireTaxonomyNodeRequest
Responses
| Status | Description |
|---|---|
200 | |
404 | node not visible in scope (rls_sparse) |
409 | version conflict or idempotency key reused |
Security: bearer
GET
/api/v1/taxonomy/typesGET /api/taxonomy/types — the org's ticket types; active-only unless `include_retired`.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
include_retired | query | boolean | No | Include retired nodes (admin editors + the manifest want them; pickers default to false). |
Responses
| Status | Description |
|---|---|
200 |
Security: bearer
POST
/api/v1/taxonomy/typesPOST /api/taxonomy/types — create a ticket type.
Request body
CreateTaxonomyNodeRequest
Responses
| Status | Description |
|---|---|
200 | |
409 | duplicate name or idempotency key reused |
Security: bearer
PATCH
/api/v1/taxonomy/types/{id}PATCH /api/taxonomy/types/{id} — rename / edit description / re-sort. Behavior-neutral: nothing keys off these trees.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes |
Request body
UpdateTaxonomyNodeRequest
Responses
| Status | Description |
|---|---|
200 | |
404 | node not visible in scope (rls_sparse) |
409 | duplicate name, version conflict, or idempotency key reused |
Security: bearer
POST
/api/v1/taxonomy/types/{id}/retirePOST /api/taxonomy/types/{id}/retire — soft-retire: pickers hide the node, existing tickets keep their reference. Idempotent: retiring an already-retired node returns its current state.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes |
Request body
RetireTaxonomyNodeRequest
Responses
| Status | Description |
|---|---|
200 | |
404 | node not visible in scope (rls_sparse) |
409 | version conflict or idempotency key reused |
Security: bearer
POST
/api/v1/tickets/{id}/move-boardPOST /api/tickets/{id}/move-board — move a ticket to another board with the status remapped through the SEMANTIC categories (typed 409 listing the target statuses when the current category has no counterpart). SLA state is preserved by default; `reset_sla` re-initializes the clocks. Audited, emits `ticket.board_moved`, all in one transaction. Instant- first (IF1/IF2): idempotency-keyed, version-gated, read-your-write.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes |
Request body
MoveBoardRequest
Responses
| Status | Description |
|---|---|
200 | |
404 | ticket or target board not visible in scope (rls_sparse) |
409 | no matching semantic status on the target board, version conflict, or idempotency key reused |
422 | validation error |
Security: bearer