Sign in

v5

latestOpenAPI 3.1.02026-08-025631,1012.8 MB
Taxonomies

Create a taxonomy from a document selection (one gesture)

Promote a document selection (e.g. a lasso/cluster selection in the cluster visualization) into a NEW flat taxonomy in one call.

Creates, in order:

  1. a node collection mirroring the selection's vector index (same vector name, dimensions, and feature_uri — no re-embedding, no GPU work),
  2. a vector-search retriever over it,
  3. the flat taxonomy wired to both (input_mappings map an incoming document's stored embedding onto the retriever),
  4. the first node: a document whose anchor vector is the centroid of the referenced documents' stored vectors, labeled node_label.

Documents enriched through the taxonomy afterwards are labeled with the nearest node's label. To add more nodes later, use POST /v1/taxonomies/{taxonomy_id}/nodes/from-documents.

Resources created before a failing step are cleaned up best-effort.

post/v1/taxonomies/from-documents

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.

taxonomy_namestring required

Unique name for the new taxonomy.

descriptionstring nullable

Optional taxonomy description.

enrichment_target_fieldstring nullable

Field name written onto enriched documents (defaults to '<taxonomy_name>_label').

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.