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

# Create a taxonomy from a document selection (one gesture)

`POST /v1/taxonomies/from-documents`

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.

## Request body

- CreateTaxonomyFromDocumentsRequest — One-gesture promotion: create a flat taxonomy (node collection + vector-search retriever) AND its first node from a document selection. The node collection mirrors the referenced documents' collection vector index (same vector name / dimensions / feature_uri), so classification is guaranteed dimension-compatible with the data the selection came from.
  - `node_label` string, required — Label for the new node — the value copied onto documents that classify under it (canonical `label` field).
  - `documents` DocumentRef[], required — Documents whose stored vectors define the node's anchor (centroid). 1-200 refs; for large selections send a sample — the centroid converges quickly.
    - `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.
  - `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 `201`

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.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `422` — Validation Error
- `500` — Internal Server Error

---

[API](https://skmtc.net/mixpeek/apis/mixpeek-api.md) · [All operations](https://skmtc.net/mixpeek/apis/mixpeek-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mixpeek/mixpeek-api/versions/23e05292e326/schema)