Authorizations
Bearer token authentication using your API key. Format: 'Bearer your_api_key'. To get an API key, create an account at mixpeek.com/start and generate a key in your account settings.
Headers
REQUIRED: Bearer token authentication using your API key. Format: 'Bearer sk_xxxxxxxxxxxxx'. You can create API keys in the Mixpeek dashboard under Organization Settings.
"Bearer sk_live_abc123def456"
"Bearer sk_test_xyz789"
REQUIRED: Namespace identifier for scoping this request. All resources (collections, buckets, taxonomies, etc.) are scoped to a namespace. You can provide either the namespace name or namespace ID. Format: ns_xxxxxxxxxxxxx (ID) or a custom name like 'my-namespace'
"ns_abc123def456"
"production"
"my-namespace"
Path Parameters
Taxonomy ID or name to validate
Query Parameters
Optional taxonomy version (defaults to latest)
Body
- ExecuteTaxonomyRequest
- Payload
Request model for on-demand taxonomy validation and testing ONLY.
ā ļø IMPORTANT: This endpoint is ONLY for testing taxonomy configuration with sample documents.
DO NOT USE THIS FOR BATCH ENRICHMENT: ā Do NOT use this to enrich an entire collection ā Do NOT use source_collection_id expecting batch processing ā Do NOT use target_collection_id expecting persistence
HOW TAXONOMY ENRICHMENT ACTUALLY WORKS:
ā
Automatic during ingestion: Attach taxonomies to collections via taxonomy_applications
ā
On-the-fly in retrieval: Add taxonomy_join stage to retriever pipelines
This endpoint validates:
- Taxonomy configuration is correct
- Retriever can find matching taxonomy nodes
- Enrichment fields are properly applied
For production enrichment, see:
- Collections API: attach taxonomies via
taxonomy_applicationsfield - Retrievers API: add
taxonomy_joinstage for on-the-fly enrichment
Full taxonomy model with configuration (fetched from DB by controller)
{
"config": {
"default_input_mappings": [
{
"input_key": "image_vector",
"path": "features.clip_vit_l_14",
"source_type": "vector"
}
],
"default_retriever_id": "ret_clip_v1",
"source_collection": { "collection_id": "col_products_v1" },
"taxonomy_type": "flat"
},
"namespace_id": "ns_123",
"taxonomy_name": "product_tags",
"taxonomy_type": "flat"
}{
"config": {
"build_mode": "explicit",
"default_input_mappings": [
{
"input_key": "face_vec",
"path": "features.face",
"source_type": "vector"
}
],
"default_retriever_id": "ret_face_v1",
"hierarchical_nodes": [
{ "collection_id": "col_employees_v1" },
{
"collection_id": "col_executives_v1",
"parent_collection_id": "col_employees_v1"
}
],
"taxonomy_type": "hierarchical"
},
"namespace_id": "ns_123",
"taxonomy_name": "org_hierarchy",
"taxonomy_type": "hierarchical"
}Optional retriever configuration override for testing. If omitted, uses the retriever configured in the taxonomy. Retriever model.
Sample documents to test enrichment (typically 1-5 docs). Results are returned immediately, not persisted. ā ļø Do NOT pass collection_id expecting batch processing!
ā ļø IGNORED IN ON_DEMAND MODE. This field exists for legacy compatibility only. To enrich collections, use taxonomy_applications on the collection.
ā ļø IGNORED IN ON_DEMAND MODE. This field exists for legacy compatibility only. Results are never persisted via this endpoint.
Must be 'on_demand'. BATCH mode is NOT supported via API. Batch enrichment is automatic (triggered by engine during ingestion).
on_demand, batch Batch size for the scroll iterator
1 <= x <= 10000Additional filters applied to the source collection prior to enrichment. Represents a logical operation (AND, OR, NOT) on filter conditions.
Allows nesting with a defined depth limit.
Also supports shorthand syntax where field names can be passed directly as key-value pairs for equality filtering (e.g., {"metadata.title": "value"}).