Create a taxonomy from a document selection (one gesture)
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 '
{
"node_label": "<string>",
"documents": [
{
"collection_id": "<string>",
"document_id": "<string>"
}
],
"taxonomy_name": "<string>",
"node_fields": {},
"vector_name": "<string>",
"provenance": {},
"description": "<string>",
"enrichment_target_field": "<string>"
}
'import requests
url = "https://api.mixpeek.com/v1/taxonomies/from-documents"
payload = {
"node_label": "<string>",
"documents": [
{
"collection_id": "<string>",
"document_id": "<string>"
}
],
"taxonomy_name": "<string>",
"node_fields": {},
"vector_name": "<string>",
"provenance": {},
"description": "<string>",
"enrichment_target_field": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"X-Namespace": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
Authorization: 'Bearer <token>',
'X-Namespace': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
node_label: '<string>',
documents: [{collection_id: '<string>', document_id: '<string>'}],
taxonomy_name: '<string>',
node_fields: {},
vector_name: '<string>',
provenance: {},
description: '<string>',
enrichment_target_field: '<string>'
})
};
fetch('https://api.mixpeek.com/v1/taxonomies/from-documents', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.mixpeek.com/v1/taxonomies/from-documents",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'node_label' => '<string>',
'documents' => [
[
'collection_id' => '<string>',
'document_id' => '<string>'
]
],
'taxonomy_name' => '<string>',
'node_fields' => [
],
'vector_name' => '<string>',
'provenance' => [
],
'description' => '<string>',
'enrichment_target_field' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"X-Namespace: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.mixpeek.com/v1/taxonomies/from-documents"
payload := strings.NewReader("{\n \"node_label\": \"<string>\",\n \"documents\": [\n {\n \"collection_id\": \"<string>\",\n \"document_id\": \"<string>\"\n }\n ],\n \"taxonomy_name\": \"<string>\",\n \"node_fields\": {},\n \"vector_name\": \"<string>\",\n \"provenance\": {},\n \"description\": \"<string>\",\n \"enrichment_target_field\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("X-Namespace", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.mixpeek.com/v1/taxonomies/from-documents")
.header("Authorization", "Bearer <token>")
.header("X-Namespace", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"node_label\": \"<string>\",\n \"documents\": [\n {\n \"collection_id\": \"<string>\",\n \"document_id\": \"<string>\"\n }\n ],\n \"taxonomy_name\": \"<string>\",\n \"node_fields\": {},\n \"vector_name\": \"<string>\",\n \"provenance\": {},\n \"description\": \"<string>\",\n \"enrichment_target_field\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.mixpeek.com/v1/taxonomies/from-documents")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["X-Namespace"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"node_label\": \"<string>\",\n \"documents\": [\n {\n \"collection_id\": \"<string>\",\n \"document_id\": \"<string>\"\n }\n ],\n \"taxonomy_name\": \"<string>\",\n \"node_fields\": {},\n \"vector_name\": \"<string>\",\n \"provenance\": {},\n \"description\": \"<string>\",\n \"enrichment_target_field\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"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>"
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}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:
- a node collection mirroring the selection’s vector index (same vector name, dimensions, and feature_uri — no re-embedding, no GPU work),
- a vector-search retriever over it,
- the flat taxonomy wired to both (input_mappings map an incoming document’s stored embedding onto the retriever),
- 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
Create a taxonomy from a document selection (one gesture)
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 '
{
"node_label": "<string>",
"documents": [
{
"collection_id": "<string>",
"document_id": "<string>"
}
],
"taxonomy_name": "<string>",
"node_fields": {},
"vector_name": "<string>",
"provenance": {},
"description": "<string>",
"enrichment_target_field": "<string>"
}
'import requests
url = "https://api.mixpeek.com/v1/taxonomies/from-documents"
payload = {
"node_label": "<string>",
"documents": [
{
"collection_id": "<string>",
"document_id": "<string>"
}
],
"taxonomy_name": "<string>",
"node_fields": {},
"vector_name": "<string>",
"provenance": {},
"description": "<string>",
"enrichment_target_field": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"X-Namespace": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
Authorization: 'Bearer <token>',
'X-Namespace': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
node_label: '<string>',
documents: [{collection_id: '<string>', document_id: '<string>'}],
taxonomy_name: '<string>',
node_fields: {},
vector_name: '<string>',
provenance: {},
description: '<string>',
enrichment_target_field: '<string>'
})
};
fetch('https://api.mixpeek.com/v1/taxonomies/from-documents', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.mixpeek.com/v1/taxonomies/from-documents",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'node_label' => '<string>',
'documents' => [
[
'collection_id' => '<string>',
'document_id' => '<string>'
]
],
'taxonomy_name' => '<string>',
'node_fields' => [
],
'vector_name' => '<string>',
'provenance' => [
],
'description' => '<string>',
'enrichment_target_field' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"X-Namespace: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.mixpeek.com/v1/taxonomies/from-documents"
payload := strings.NewReader("{\n \"node_label\": \"<string>\",\n \"documents\": [\n {\n \"collection_id\": \"<string>\",\n \"document_id\": \"<string>\"\n }\n ],\n \"taxonomy_name\": \"<string>\",\n \"node_fields\": {},\n \"vector_name\": \"<string>\",\n \"provenance\": {},\n \"description\": \"<string>\",\n \"enrichment_target_field\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("X-Namespace", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.mixpeek.com/v1/taxonomies/from-documents")
.header("Authorization", "Bearer <token>")
.header("X-Namespace", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"node_label\": \"<string>\",\n \"documents\": [\n {\n \"collection_id\": \"<string>\",\n \"document_id\": \"<string>\"\n }\n ],\n \"taxonomy_name\": \"<string>\",\n \"node_fields\": {},\n \"vector_name\": \"<string>\",\n \"provenance\": {},\n \"description\": \"<string>\",\n \"enrichment_target_field\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.mixpeek.com/v1/taxonomies/from-documents")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["X-Namespace"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"node_label\": \"<string>\",\n \"documents\": [\n {\n \"collection_id\": \"<string>\",\n \"document_id\": \"<string>\"\n }\n ],\n \"taxonomy_name\": \"<string>\",\n \"node_fields\": {},\n \"vector_name\": \"<string>\",\n \"provenance\": {},\n \"description\": \"<string>\",\n \"enrichment_target_field\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"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>"
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}{
"error": {
"details": {
"id": "ns_123",
"resource": "namespace"
},
"message": "Namespace not found",
"type": "NotFoundError"
},
"status": 404,
"success": false
}Authorizations
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.
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
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.
Label for the new node — the value copied onto documents that classify under it (canonical label field).
Minimum string length:
1Documents 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 elementsShow child attributes
Show child attributes
Unique name for the new taxonomy.
Minimum string length:
1Optional extra fields stored on the node document (e.g. description). Only fields listed in the taxonomy's enrichment_fields are copied during enrichment.
Optional explicit vector (index) name for the anchor. If omitted, it is derived from the taxonomy's node collection vector indexes.
Optional freeform origin context (e.g. cluster_id, run_id, selection type). Stored on the node document under metadata.promotion for auditability.
Optional taxonomy description.
Field name written onto enriched documents (defaults to '<taxonomy_name>_label').
Response
Successful Response
Result of promoting a document selection to a taxonomy node.
ID of the created node document (the taxonomy node).
The taxonomy's node (source) collection.
Vector index name the anchor was stored under.
How many referenced documents contributed to the anchor.
Plain-language description of how the new node will be applied to future data.
Show child attributes
Show child attributes
True when this call also created the taxonomy (one-gesture mode).
Retriever created for the taxonomy (one-gesture mode only).
Was this page helpful?