Skip to content
Support

Taxonomy

List taxonomy-capable fields
GET/v1/taxonomy/fields
ModelsExpand Collapse
Run = object { id, cluster_count, created_at, 16 more }

A persisted taxonomy generation run.

id: string
formatuuid
cluster_count: number
formatint64
created_at: string
formatdate-time
embedding_count: number
formatint64
field_id: string
node_count: number
formatint64
record_count: number
formatint64
source_id: string

Empty string is the canonical "no source" bucket.

source_type: string
status: "pending" or "running" or "succeeded" or 2 more

Lifecycle state of a taxonomy run. Allowed transitions are pending -> running|failed|canceled and running -> succeeded|failed|canceled.

Accepts one of the following:
"pending"
"running"
"succeeded"
"failed"
"canceled"
tenant_id: string
updated_at: string
formatdate-time
error: optional string

Sanitized failure message; present on failed runs.

error_code: optional "insufficient_data" or "service_unavailable" or "generation_failed" or 2 more

Machine-readable reason a taxonomy run failed or a prerequisite was not met.

Accepts one of the following:
"insufficient_data"
"service_unavailable"
"generation_failed"
"invalid_output"
"internal_error"
field_label: optional string

Human-readable field label; absent when unknown.

finished_at: optional string
formatdate-time
metrics: optional map[unknown]

Opaque run metrics recorded by the taxonomy service.

params: optional map[unknown]

Opaque run parameters recorded by Hub.

started_at: optional string
formatdate-time
Node = object { id, created_at, label, 13 more }

A node in a taxonomy tree. Non-root nodes have a parent; leaf nodes reference the cluster they summarize.

id: string
formatuuid
created_at: string
formatdate-time
label: string
level: number

Depth in the tree; the root is level 0.

formatint64
node_type: "root" or "branch" or "leaf"

Position of a node within the taxonomy tree.

Accepts one of the following:
"root"
"branch"
"leaf"
run_id: string
formatuuid
sort_order: number
formatint64
updated_at: string
formatdate-time
children: optional array of Node { id, created_at, label, 13 more }

Child nodes, present when the tree is returned hierarchically.

cluster_id: optional string

Cluster this node summarizes; typically present on leaf nodes.

formatuuid
description: optional string
metadata: optional map[unknown]
original_label: optional string

Label as originally generated, before any rename.

parent_id: optional string

Parent node ID; absent for the root node.

formatuuid
removed_at: optional string

Set when the node has been soft-removed.

formatdate-time
removed_by: optional string

Actor that soft-removed the node.

TaxonomyRuns

List taxonomy runs
GET/v1/taxonomy/runs
Start a taxonomy run
POST/v1/taxonomy/runs
Get a taxonomy run
GET/v1/taxonomy/runs/{run_id}
Get a taxonomy run's tree
GET/v1/taxonomy/runs/{run_id}/tree

TaxonomyRunsActive

Get the active taxonomy tree for a scope
GET/v1/taxonomy/runs/active/tree

TaxonomyNodes

Rename a taxonomy node
PATCH/v1/taxonomy/nodes/{node_id}
Soft-remove a taxonomy node
DELETE/v1/taxonomy/nodes/{node_id}
List feedback records for a taxonomy node
GET/v1/taxonomy/nodes/{node_id}/records