---
title: "Create a taxonomy from a document selection or a cluster run (one gesture)"
method: POST
path: "/v1/taxonomies/from-documents"
tags: ["Taxonomies"]
---

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

`POST /v1/taxonomies/from-documents`

## Request

- Base URL: `https://api.mixpeek.com`
- URL: `https://api.mixpeek.com/v1/taxonomies/from-documents`
- Auth: HTTP bearer and API key in header `X-Namespace`

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.

## Request body

- CreateTaxonomyFromDocumentsRequest: 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).
  - `node_label` string, nullable: Label of the node created from `documents`. Required with `documents`; with `cluster_run` each node takes its cluster's label.
  - `documents` DocumentRef[], nullable: Documents whose stored vectors are averaged into the one node's anchor. Give this or `cluster_run`.
    - `collection_id` string, required: Collection the document lives in.
    - `document_id` string, required: The document's ID.
  - `node_fields` object, 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_name` string, nullable: Optional explicit vector (index) name for the anchor. If omitted, it is derived from the taxonomy's node collection vector indexes.
  - `provenance` object, nullable: 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: A completed cluster run whose clusters become the taxonomy's nodes.
    - `cluster_id` string, required: The cluster that ran.
    - `run_id` string, required: The run to promote, exactly (GET /v1/clusters/{cluster_id}/executions lists them). A run's own artifact is read; no other run is substituted.
  - `taxonomy_name` string, required: Unique name for the new taxonomy.
  - `description` string, nullable: Optional taxonomy description.
  - `enrichment_target_field` string, nullable: Field name written onto enriched documents (defaults to '<taxonomy_name>_label').

## Response `200`

Successful Response

- TaxonomyNodeFromDocumentsResponse: 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.
  - `documents_skipped` SkippedDocumentRef[]
    - `collection_id` string, nullable
    - `document_id` string, nullable
    - `reason` string, required
  - `taxonomy_created` boolean: True when this call also created the taxonomy (one-gesture mode).
  - `retriever_id` string, nullable: Retriever created for the taxonomy (one-gesture mode only).
  - `enrichment_hint` string, required: Plain-language description of how the new node will be applied to future data.
  - `nodes` PromotedNode[], nullable: Every node created, when the source was a `cluster_run` (one per cluster). `node_document_id` and `node_label` name the first.
    - `node_document_id` string, required
    - `node_label` string, required
    - `cluster_id` string, required
    - `member_count` integer, nullable

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not Found
- `422`: Unprocessable Entity
- `429`: Too Many Requests
- `500`: Internal Server Error
- `503`: Service Unavailable

## Changes

- **2026-10-09** `61a175e8eb9a`: 1 warning, 5 info
  - removed the optional property `detail` from the response with the `422` status
  - added the non-success response with the status `429`
  - added the non-success response with the status `503`
  - added the optional property `success` to the response with the `422` status
  - …2 more
- **2026-10-06** `b75474e978ff`: 7 info
  - added the new optional request property `cluster_run`
  - the request property `documents` became optional
  - the request property `node_label` became optional
  - request property `documents` list-of-types was widened by adding types `null` to media type `application/json`
  - …3 more
- **2026-10-04** `38e0822db900`: 1 breaking, 1 info
  - removed the success response with the status `201`
  - added the success response with the status `200`
- **2026-08-09** `5d4c905106b4`: 1 info
  - the endpoint scheme security `BearerAuth AND NamespaceHeader` was added to the API

[Operation history](https://skmtc.dev/mixpeek/apis/mixpeek-api/changes/v1/taxonomies/from-documents/post.md)

---

[API](https://skmtc.dev/mixpeek/apis/mixpeek-api.md) - [All operations](https://skmtc.dev/mixpeek/apis/mixpeek-api/llms.txt) - [OpenAPI document](https://skmtc.dev/mixpeek/apis/mixpeek-api/revisions/790bc16455f6?raw)