# Nodes

## Rename

`client.taxonomy.nodes.rename(stringnodeID, NodeRenameParamsbody, RequestOptionsoptions?): Node`

**patch** `/v1/taxonomy/nodes/{node_id}`

Renames a taxonomy node's label and records a rename event attributed to actor_id. Tenant-scoped;
returns 404 if the node does not belong to the tenant. While a tenant data purge runs for the same
tenant_id, the request is rejected with HTTP 409 (code `tenant_write_conflict`) and may be retried.

### Parameters

- `nodeID: string`

- `body: NodeRenameParams`

  - `actor_id: string`

  - `label: string`

    New node label.

  - `tenant_id: string`

### Returns

- `Node`

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

  - `id: string`

  - `created_at: string`

  - `label: string`

  - `level: number`

    Depth in the tree; the root is level 0.

  - `node_type: "root" | "branch" | "leaf"`

    Position of a node within the taxonomy tree.

    - `"root"`

    - `"branch"`

    - `"leaf"`

  - `run_id: string`

  - `sort_order: number`

  - `updated_at: string`

  - `children?: Array<Node>`

    Child nodes, present when the tree is returned hierarchically.

    - `Node`

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

      - `id: string`

      - `created_at: string`

      - `label: string`

      - `level: number`

        Depth in the tree; the root is level 0.

      - `node_type: "root" | "branch" | "leaf"`

        Position of a node within the taxonomy tree.

        - `"root"`

        - `"branch"`

        - `"leaf"`

      - `run_id: string`

      - `sort_order: number`

      - `updated_at: string`

      - `children?: Array<Node>`

        Child nodes, present when the tree is returned hierarchically.

      - `cluster_id?: string`

        Cluster this node summarizes; typically present on leaf nodes.

      - `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.

      - `removed_at?: string`

        Set when the node has been soft-removed.

      - `removed_by?: string`

        Actor that soft-removed the node.

  - `cluster_id?: string`

    Cluster this node summarizes; typically present on leaf nodes.

  - `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.

  - `removed_at?: string`

    Set when the node has been soft-removed.

  - `removed_by?: string`

    Actor that soft-removed the node.

### Example

```typescript
import FormbricksHub from '@formbricks/hub';

const client = new FormbricksHub({
  apiKey: process.env['HUB_API_KEY'], // This is the default and can be omitted
});

const node = await client.taxonomy.nodes.rename('019f177f-9abe-78cd-8008-f40b58e3147d', {
  actor_id: 'user-42',
  label: 'Authentication Problems',
  tenant_id: 'org-123',
});

console.log(node.id);
```

## Soft Remove

`client.taxonomy.nodes.softRemove(stringnodeID, NodeSoftRemoveParamsparams, RequestOptionsoptions?): Node`

**delete** `/v1/taxonomy/nodes/{node_id}`

Soft-removes a taxonomy node (sets removed_at/removed_by) and records a soft_remove event
attributed to actor_id. The node is retained for audit but excluded from tree responses.
Tenant-scoped; returns 404 if the node does not belong to the tenant. While a tenant data purge
runs for the same tenant_id, the request is rejected with HTTP 409 (code `tenant_write_conflict`).

### Parameters

- `nodeID: string`

- `params: NodeSoftRemoveParams`

  - `actor_id: string`

    Identifier of the actor performing the removal (recorded in the audit event).

  - `tenant_id: string`

    Tenant that owns the node.

### Returns

- `Node`

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

  - `id: string`

  - `created_at: string`

  - `label: string`

  - `level: number`

    Depth in the tree; the root is level 0.

  - `node_type: "root" | "branch" | "leaf"`

    Position of a node within the taxonomy tree.

    - `"root"`

    - `"branch"`

    - `"leaf"`

  - `run_id: string`

  - `sort_order: number`

  - `updated_at: string`

  - `children?: Array<Node>`

    Child nodes, present when the tree is returned hierarchically.

    - `Node`

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

      - `id: string`

      - `created_at: string`

      - `label: string`

      - `level: number`

        Depth in the tree; the root is level 0.

      - `node_type: "root" | "branch" | "leaf"`

        Position of a node within the taxonomy tree.

        - `"root"`

        - `"branch"`

        - `"leaf"`

      - `run_id: string`

      - `sort_order: number`

      - `updated_at: string`

      - `children?: Array<Node>`

        Child nodes, present when the tree is returned hierarchically.

      - `cluster_id?: string`

        Cluster this node summarizes; typically present on leaf nodes.

      - `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.

      - `removed_at?: string`

        Set when the node has been soft-removed.

      - `removed_by?: string`

        Actor that soft-removed the node.

  - `cluster_id?: string`

    Cluster this node summarizes; typically present on leaf nodes.

  - `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.

  - `removed_at?: string`

    Set when the node has been soft-removed.

  - `removed_by?: string`

    Actor that soft-removed the node.

### Example

```typescript
import FormbricksHub from '@formbricks/hub';

const client = new FormbricksHub({
  apiKey: process.env['HUB_API_KEY'], // This is the default and can be omitted
});

const node = await client.taxonomy.nodes.softRemove('019f177f-9abe-78cd-8008-f40b58e3147d', {
  actor_id: 'actor_id',
  tenant_id: 'org-123',
});

console.log(node.id);
```

## List Records

`client.taxonomy.nodes.listRecords(stringnodeID, NodeListRecordsParamsquery, RequestOptionsoptions?): NodeListRecordsResponse`

**get** `/v1/taxonomy/nodes/{node_id}/records`

Returns the feedback records assigned to a node and all of its (visible) descendant nodes, via the
clusters those nodes reference. Tenant-scoped; returns 404 if the node does not belong to the tenant
or has been removed. An empty `data` therefore means the node genuinely holds no records. The `limit`
in the response reflects the applied cap.

### Parameters

- `nodeID: string`

- `query: NodeListRecordsParams`

  - `tenant_id: string`

    Tenant that owns the node.

  - `limit?: number`

    Maximum number of feedback records to return.

### Returns

- `NodeListRecordsResponse`

  - `data: Array<FeedbackRecordData>`

    - `id: string`

      UUIDv7 primary key

    - `collected_at: string`

      When the feedback was collected

    - `created_at: string`

      When this record was created

    - `field_id: string`

      Identifier for the question/field

    - `field_type: "text" | "categorical" | "nps" | 6 more`

      Type of field

      - `"text"`

      - `"categorical"`

      - `"nps"`

      - `"csat"`

      - `"ces"`

      - `"rating"`

      - `"number"`

      - `"boolean"`

      - `"date"`

    - `source_type: string`

      Type of feedback source

    - `submission_id: string`

      Identifier for the logical submission this record belongs to (required).

    - `tenant_id: string`

      Tenant/organization identifier. NULL bytes not allowed.

    - `updated_at: string`

      When this record was last updated

    - `emotions?: Array<"joy" | "anger" | "sadness" | 3 more>`

      Emotions inferred from value_text (emotion enrichment); multi-label from a fixed set. Read-only; absent until the record is enriched, and never an empty array.

      - `"joy"`

      - `"anger"`

      - `"sadness"`

      - `"fear"`

      - `"surprise"`

      - `"disgust"`

    - `field_group_id?: string`

      Stable identifier grouping related fields (for ranking, matrix, grid questions)

    - `field_group_label?: string`

      Human-readable question text for the group

    - `field_label?: string`

      The actual question text

    - `language?: string`

      ISO language code. NULL bytes not allowed.

    - `metadata?: Record<string, unknown>`

      Additional context

    - `sentiment?: "very_negative" | "negative" | "neutral" | 3 more`

      Sentiment polarity inferred from value_text (sentiment enrichment). Read-only; absent until the record is enriched.

      - `"very_negative"`

      - `"negative"`

      - `"neutral"`

      - `"positive"`

      - `"very_positive"`

      - `"mixed"`

    - `sentiment_score?: number`

      Signed sentiment polarity from -1.0 (very negative) to 1.0 (very positive) (sentiment enrichment). Read-only; absent until the record is enriched.

    - `source_id?: string`

      Reference to survey/form/ticket ID

    - `source_name?: string`

      Human-readable name

    - `translation_lang_key?: string`

      BCP-47 target locale that value_text_translated was produced in (language enrichment). Read-only; absent until the record is enriched.

    - `user_id?: string`

      User ID (e.g., anonymous ID or email hash)

    - `value_boolean?: boolean`

      Boolean response

    - `value_date?: string`

      Date response

    - `value_id?: string`

      Stable id of the selected option in the source system (e.g. a survey choice id), stored alongside value_text for durable option identity. Opaque to Hub. Absent for free-text/non-choice answers. NULL bytes not allowed.

    - `value_number?: number`

      Numeric response

    - `value_text?: string`

      Text response. NULL bytes not allowed.

    - `value_text_translated?: string`

      value_text translated into the tenant's configured target language (language enrichment). Read-only; absent until the record is enriched.

  - `limit: number`

    The applied maximum number of records.

### Example

```typescript
import FormbricksHub from '@formbricks/hub';

const client = new FormbricksHub({
  apiKey: process.env['HUB_API_KEY'], // This is the default and can be omitted
});

const response = await client.taxonomy.nodes.listRecords('019f177f-9abe-78cd-8008-f40b58e3147d', {
  tenant_id: 'org-123',
});

console.log(response.data);
```