Skip to main content
POST
Add a taxonomy node derived from a document selection

Authorizations

Authorization
string
header
required

Mixpeek API key, sent as Authorization: Bearer mxp_sk_.... Create one in Studio under Settings → API Keys, or with an admin key via POST /v1/organizations/users/{user_email}/api-keys. A missing header returns 403; an invalid or revoked key returns 401.

X-Namespace
string
header
required

Namespace id (ns_...), not the namespace name. This scopes the request rather than authenticating it, and it is required on every operation marked x-mixpeek-namespace-scoped.

Path Parameters

taxonomy_identifier
string
required

Taxonomy ID or name

Body

application/json

Create a taxonomy node whose classification anchor derives from documents.

Mixpeek taxonomy nodes are documents in the taxonomy's source (node) collection: at enrichment time, an incoming document's embedding queries that collection through the taxonomy's retriever and the best-matching node's fields (canonically label) are copied onto it.

This endpoint computes the CENTROID of the referenced documents' stored vectors and inserts it as a new node document — so future documents whose embeddings land near the referenced selection are classified under node_label. No re-embedding or GPU work happens; only stored vectors are read.

node_label
string
required

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

Minimum string length: 1
documents
DocumentRef · object[]
required

Documents whose stored vectors define the node's anchor (centroid). 1-200 refs; for large selections send a sample — the centroid converges quickly.

Required array length: 1 - 200 elements
node_fields
Node Fields · object | null

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_name
string | null

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

provenance
Provenance · object | null

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

Result of promoting a document selection to a taxonomy node.

taxonomy_id
string
required
taxonomy_name
string
required
node_document_id
string
required

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

node_collection_id
string
required

The taxonomy's node (source) collection.

node_label
string
required
vector_name
string
required

Vector index name the anchor was stored under.

vector_dimensions
integer
required
documents_used
integer
required

How many referenced documents contributed to the anchor.

enrichment_hint
string
required

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

documents_skipped
SkippedDocumentRef · object[]
taxonomy_created
boolean
default:false

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

retriever_id
string | null

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