Create a taxonomy from a document selection or a cluster run (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 nodes, from one of two sources:
   • documents + node_label: one node whose anchor vector is the centroid of the referenced documents’ stored vectors;
   • cluster_run ({cluster_id, run_id}): one node per cluster in that run, labeled with the cluster’s label and anchored on its stored centroid, so a whole cluster run becomes a classifier in one call. The response’s nodes lists every node created.

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

Create a taxonomy from a document selection or a cluster run (one gesture)

cURL

curl --request POST \
  --url https://api.mixpeek.com/v1/taxonomies/from-documents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Namespace: <api-key>' \
  --data '
{
  "taxonomy_name": "<string>",
  "node_label": "<string>",
  "documents": [
    {
      "collection_id": "<string>",
      "document_id": "<string>"
    }
  ],
  "node_fields": {},
  "vector_name": "<string>",
  "provenance": {},
  "cluster_run": {
    "cluster_id": "<string>",
    "run_id": "<string>"
  },
  "description": "<string>",
  "enrichment_target_field": "<string>"
}
'

200

{
  "taxonomy_id": "<string>",
  "taxonomy_name": "<string>",
  "node_document_id": "<string>",
  "node_collection_id": "<string>",
  "node_label": "<string>",
  "vector_name": "<string>",
  "vector_dimensions": 123,
  "documents_used": 123,
  "enrichment_hint": "<string>",
  "documents_skipped": [
    {
      "reason": "<string>",
      "collection_id": "<string>",
      "document_id": "<string>"
    }
  ],
  "taxonomy_created": false,
  "retriever_id": "<string>",
  "nodes": [
    {
      "node_document_id": "<string>",
      "node_label": "<string>",
      "cluster_id": "<string>",
      "member_count": 123
    }
  ]
}

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, malformed, unknown, revoked, inactive or expired key returns 401; a key without the permission, scope or plan an operation needs returns 403.

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.

Body

application/json

Keys this body does not declare are refused with 422 extra_forbidden naming the accepted keys (since 2026-11-02).

One-gesture promotion: create a flat taxonomy (node collection + vector-search retriever) AND its nodes, from a document selection or from a whole cluster run.

The node collection mirrors the source collection's vector index (same vector name / dimensions / feature_uri), so classification is guaranteed dimension-compatible with the data the nodes came from.

Give exactly one source: documents with node_label (one node whose anchor averages the documents), or cluster_run (one node per cluster in that run, labelled with the cluster's label, its stored centroid as the anchor).

taxonomy_name · string · required

Unique name for the new taxonomy.

Minimum string length: 1

node_label · string | null

Label of the node created from documents. Required with documents; with cluster_run each node takes its cluster's label.

Minimum string length: 1

documents · DocumentRef · object[] | null

Documents whose stored vectors are averaged into the one node's anchor. Give this or cluster_run.

Required array length: 1 - 200 elements

Show child attributes

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.

cluster_run · ClusterRunSource · object | null

Promote a whole cluster run in one call: one node per cluster, labelled with the cluster label, anchored on the cluster's stored centroid vector (no re-embedding). Give this or documents.

Show child attributes

description · string | null

Optional taxonomy description.

enrichment_target_field · string | null

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

Response

200

application/json

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[]

Show child attributes

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

nodes · PromotedNode · object[] | null

Every node created, when the source was a cluster_run (one per cluster). node_document_id and node_label name the first.

Show child attributes