Skip to content
Formbricks Hub Formbricks Hub Formbricks Hub
Support
API Reference

Taxonomy

List taxonomy-capable fields
client.taxonomy.listFields(TaxonomyListFieldsParams { tenant_id } query, RequestOptionsoptions?): TaxonomyListFieldsResponse { data }
GET/v1/taxonomy/fields
ModelsExpand Collapse
Run { id, cluster_count, created_at, 17 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
scope_type: "field" | "directory"

Taxonomy input scope. field covers one (source_type, source_id, field_id) field scope. directory covers all text feedback records for the tenant/directory and must not include source_type, source_id, or field_id.

Accepts one of the following:
"field"
"directory"
source_id: string

Empty string is the canonical "no source" bucket.

source_type: string
status: "pending" | "running" | "succeeded" | 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?: string

Sanitized failure message; present on failed runs.

error_code?: "insufficient_data" | "service_unavailable" | "generation_failed" | 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?: string

Human-readable field label; absent when unknown.

finished_at?: string
formatdate-time
metrics?: Record<string, unknown>

Opaque run metrics recorded by the taxonomy service.

params?: Record<string, unknown>

Opaque run parameters recorded by Hub.

started_at?: string
formatdate-time
Node { 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" | "branch" | "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?: Array<Node { id, created_at, label, 13 more } >

Child nodes, present when the tree is returned hierarchically.

Node { 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" | "branch" | "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?: Array<Node { id, created_at, label, 13 more } >

Child nodes, present when the tree is returned hierarchically.

Node { id, created_at, label, 13 more }
cluster_id?: string

Cluster this node summarizes; typically present on leaf nodes.

formatuuid
description?: string
metadata?: Record<string, unknown>
original_label?: string

Label as originally generated, before any rename.

parent_id?: string

Parent node ID; absent for the root node.

formatuuid
removed_at?: string

Set when the node has been soft-removed.

formatdate-time
removed_by?: string

Actor that soft-removed the node.

cluster_id?: string

Cluster this node summarizes; typically present on leaf nodes.

formatuuid
description?: string
metadata?: Record<string, unknown>
original_label?: string

Label as originally generated, before any rename.

parent_id?: string

Parent node ID; absent for the root node.

formatuuid
removed_at?: string

Set when the node has been soft-removed.

formatdate-time
removed_by?: string

Actor that soft-removed the node.

TaxonomyRuns

List taxonomy runs
client.taxonomy.runs.list(RunListParams { tenant_id, field_id, limit, 3 more } query, RequestOptionsoptions?): RunListResponse { data }
GET/v1/taxonomy/runs
Start a taxonomy run
client.taxonomy.runs.start(RunStartParams { tenant_id, actor_id, field_id, 4 more } body, RequestOptionsoptions?): RunStartResponse { in_progress, run }
POST/v1/taxonomy/runs
Get a taxonomy run
client.taxonomy.runs.retrieve(stringrunID, RunRetrieveParams { tenant_id } query, RequestOptionsoptions?): Run { id, cluster_count, created_at, 17 more }
GET/v1/taxonomy/runs/{run_id}
Get a taxonomy run's tree
client.taxonomy.runs.getTree(stringrunID, RunGetTreeParams { tenant_id } query, RequestOptionsoptions?): RunGetTreeResponse { root, run }
GET/v1/taxonomy/runs/{run_id}/tree
Count feedback records per taxonomy node
client.taxonomy.runs.retrieveRecordCounts(stringrunID, RunRetrieveRecordCountsParams { tenant_id } query, RequestOptionsoptions?): RunRetrieveRecordCountsResponse { counts }
GET/v1/taxonomy/runs/{run_id}/record-counts

TaxonomyRunsActive

Get the active taxonomy tree for a scope
client.taxonomy.runs.active.getTree(ActiveGetTreeParams { tenant_id, field_id, scope_type, 2 more } query, RequestOptionsoptions?): ActiveGetTreeResponse { root, run }
GET/v1/taxonomy/runs/active/tree

TaxonomyNodes

Rename a taxonomy node
client.taxonomy.nodes.rename(stringnodeID, NodeRenameParams { actor_id, label, tenant_id } body, RequestOptionsoptions?): Node { id, created_at, label, 13 more }
PATCH/v1/taxonomy/nodes/{node_id}
Soft-remove a taxonomy node
client.taxonomy.nodes.softRemove(stringnodeID, NodeSoftRemoveParams { actor_id, tenant_id } params, RequestOptionsoptions?): Node { id, created_at, label, 13 more }
DELETE/v1/taxonomy/nodes/{node_id}
List feedback records for a taxonomy node
client.taxonomy.nodes.listRecords(stringnodeID, NodeListRecordsParams { tenant_id, limit } query, RequestOptionsoptions?): NodeListRecordsResponse { data, limit }
GET/v1/taxonomy/nodes/{node_id}/records