curl --request POST \
--url https://api.mixpeek.com/v1/taxonomies/{taxonomy_identifier}/nodes/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>"
}
],
"node_fields": {},
"vector_name": "<string>",
"provenance": {}
}
'import requests
url = "https://api.mixpeek.com/v1/taxonomies/{taxonomy_identifier}/nodes/from-documents"
payload = {
"node_label": "<string>",
"documents": [
{
"collection_id": "<string>",
"document_id": "<string>"
}
],
"node_fields": {},
"vector_name": "<string>",
"provenance": {}
}
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>'}],
node_fields: {},
vector_name: '<string>',
provenance: {}
})
};
fetch('https://api.mixpeek.com/v1/taxonomies/{taxonomy_identifier}/nodes/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/{taxonomy_identifier}/nodes/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>'
]
],
'node_fields' => [
],
'vector_name' => '<string>',
'provenance' => [
]
]),
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/{taxonomy_identifier}/nodes/from-documents"
payload := strings.NewReader("{\n \"node_label\": \"<string>\",\n \"documents\": [\n {\n \"collection_id\": \"<string>\",\n \"document_id\": \"<string>\"\n }\n ],\n \"node_fields\": {},\n \"vector_name\": \"<string>\",\n \"provenance\": {}\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/{taxonomy_identifier}/nodes/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 \"node_fields\": {},\n \"vector_name\": \"<string>\",\n \"provenance\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.mixpeek.com/v1/taxonomies/{taxonomy_identifier}/nodes/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 \"node_fields\": {},\n \"vector_name\": \"<string>\",\n \"provenance\": {}\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
}Add a taxonomy node derived from a document selection
Add a node to an existing flat taxonomy from a document selection.
The node is an ordinary document in the taxonomy’s node (source) collection:
its anchor vector is the centroid of the referenced documents’ stored
vectors and its label is node_label. Future documents enriched through
this taxonomy are labeled with the nearest node’s label.
Only stored vectors are read — no re-embedding or GPU work. Documents that
can’t contribute (missing, no matching vector) are skipped and reported in
documents_skipped; the call fails only when NO document contributes.
Hierarchical taxonomies are not supported here (their nodes are whole collections) — the error points you to the flat-taxonomy path.
curl --request POST \
--url https://api.mixpeek.com/v1/taxonomies/{taxonomy_identifier}/nodes/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>"
}
],
"node_fields": {},
"vector_name": "<string>",
"provenance": {}
}
'import requests
url = "https://api.mixpeek.com/v1/taxonomies/{taxonomy_identifier}/nodes/from-documents"
payload = {
"node_label": "<string>",
"documents": [
{
"collection_id": "<string>",
"document_id": "<string>"
}
],
"node_fields": {},
"vector_name": "<string>",
"provenance": {}
}
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>'}],
node_fields: {},
vector_name: '<string>',
provenance: {}
})
};
fetch('https://api.mixpeek.com/v1/taxonomies/{taxonomy_identifier}/nodes/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/{taxonomy_identifier}/nodes/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>'
]
],
'node_fields' => [
],
'vector_name' => '<string>',
'provenance' => [
]
]),
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/{taxonomy_identifier}/nodes/from-documents"
payload := strings.NewReader("{\n \"node_label\": \"<string>\",\n \"documents\": [\n {\n \"collection_id\": \"<string>\",\n \"document_id\": \"<string>\"\n }\n ],\n \"node_fields\": {},\n \"vector_name\": \"<string>\",\n \"provenance\": {}\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/{taxonomy_identifier}/nodes/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 \"node_fields\": {},\n \"vector_name\": \"<string>\",\n \"provenance\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.mixpeek.com/v1/taxonomies/{taxonomy_identifier}/nodes/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 \"node_fields\": {},\n \"vector_name\": \"<string>\",\n \"provenance\": {}\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.
Path Parameters
Taxonomy ID or name
Body
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.
Label for the new node — the value copied onto documents that classify under it (canonical label field).
1Documents whose stored vectors define the node's anchor (centroid). 1-200 refs; for large selections send a sample — the centroid converges quickly.
1 - 200 elementsShow child attributes
Show child attributes
Optional 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.
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?

