Partially Update Taxonomy
Update a taxonomy’s metadata.
Metadata Only Updates: This endpoint allows updating ONLY metadata fields. Core taxonomy logic is immutable to ensure consistency for join history and dependent resources.
Fields You CAN Update:
- taxonomy_name: Rename the taxonomy
- description: Update documentation
- metadata: Update custom metadata
Fields You CANNOT Update:
- config: Taxonomy configuration (retriever_id, input_mappings, collections)
- taxonomy_type: Type (flat vs hierarchical)
Need to Modify Core Logic? Use POST //clone instead to modify configuration, retriever_id, input_mappings, or collections.
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 YOUR_API_KEY"
"Bearer YOUR_STRIPE_API_KEY"
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
Body
Request to update a taxonomy's metadata.
IMPORTANT: Partial Updates with Controlled Mutability
This endpoint allows updating ONLY metadata fields. Core taxonomy logic is immutable to ensure consistency for join history and dependent resources.
✅ Fields You CAN Update (Metadata Only):
taxonomy_name: Rename the taxonomydescription: Update documentationmetadata: Update custom metadata fields
❌ Fields You CANNOT Update (Immutable Core Logic):
config: Taxonomy configuration (retriever_id, input_mappings, collections, hierarchy)taxonomy_type: Type (flat vs hierarchical)retriever_id: Associated retrieverinput_mappings: Field mappingsenrichment_fields: Enrichment configuration
Need to Modify Core Logic? Use POST /taxonomies/{taxonomy_id}/clone instead. Cloning creates a new taxonomy with a new ID, allowing you to:
- Change retriever or input mappings
- Modify enrichment fields
- Update collection configuration
- Change taxonomy hierarchy
Behavior:
- All fields are OPTIONAL - provide only what you want to update
- Empty updates (no fields provided) will be rejected with 400 error
- Original taxonomy remains unchanged (no destructive operations)
Why This Design?
- Join history is tied to specific taxonomy configuration
- Changing retriever would invalidate previous joins
- Version tracking enables auditing and rollback
Response
Successful Response
Response model for a taxonomy.
A unique name for the taxonomy within the namespace.
Configuration for a flat taxonomy - single source collection with one retriever.
- FlatTaxonomyConfig
- HierarchicalTaxonomyConfig
{
"input_mappings": [
{
"input_key": "image_vector",
"path": "features.clip_vit_l_14",
"source_type": "vector"
}
],
"retriever_id": "ret_clip_v1",
"source_collection": {
"collection_id": "col_products_v1",
"enrichment_fields": [
{
"field_path": "metadata.tags",
"merge_mode": "append"
}
]
},
"taxonomy_type": "flat"
}
Unique identifier for the taxonomy
Monotonic version number of the taxonomy configuration
x >= 1Optional human-readable description.
Optional taxonomy-level retriever (prefer per-layer).
Optional taxonomy-level inputs (prefer per-layer).
Whether the taxonomy is ready for use. False for async inference (cluster/LLM) that needs processing. True for flat/explicit hierarchies.
Creation timestamp for this taxonomy record
Additional user-defined metadata for the taxonomy