Sign in

v5

latestOpenAPI 3.1.02026-08-025631,1012.8 MB
Taxonomies

Add a taxonomy node derived from a document selection

Add a node to an existing flat taxonomy from a document selection.

The node is an ordinary document in the taxonomy's node (source) collection: its anchor vector is the centroid of the referenced documents' stored vectors and its label is node_label. Future documents enriched through this taxonomy are labeled with the nearest node's label.

Only stored vectors are read — no re-embedding or GPU work. Documents that can't contribute (missing, no matching vector) are skipped and reported in documents_skipped; the call fails only when NO document contributes.

Hierarchical taxonomies are not supported here (their nodes are whole collections) — the error points you to the flat-taxonomy path.

post/v1/taxonomies/{taxonomy_identifier}/nodes/from-documents

Path parameters

taxonomy_identifierstring required

Taxonomy ID or name

Taxonomy ID or name

Request body

node_labelstring required

Label for the new node — the value copied onto documents that classify under it (canonical label field).

node_fieldsobject nullable

Optional extra fields stored on the node document (e.g. description). Only fields listed in the taxonomy's enrichment_fields are copied during enrichment.

vector_namestring nullable

Optional explicit vector (index) name for the anchor. If omitted, it is derived from the taxonomy's node collection vector indexes.

provenanceobject nullable

Optional freeform origin context (e.g. cluster_id, run_id, selection type). Stored on the node document under metadata.promotion for auditability.

Response

Successful Response

taxonomy_idstring required
taxonomy_namestring required
node_document_idstring required

ID of the created node document (the taxonomy node).

node_collection_idstring required

The taxonomy's node (source) collection.

node_labelstring required
vector_namestring required

Vector index name the anchor was stored under.

vector_dimensionsinteger required
documents_usedinteger required

How many referenced documents contributed to the anchor.

taxonomy_createdboolean

True when this call also created the taxonomy (one-gesture mode).

retriever_idstring nullable

Retriever created for the taxonomy (one-gesture mode only).

enrichment_hintstring required

Plain-language description of how the new node will be applied to future data.