POST
/
v1
/
taxonomies
/
execute
/
{taxonomy_identifier}
Execute Taxonomy
curl --request POST \
  --url https://api.mixpeek.com/v1/taxonomies/execute/{taxonomy_identifier} \
  --header 'Content-Type: application/json' \
  --data '{
  "batch_size": 1000,
  "join_mode": "on_demand",
  "source_collection_id": "col_catalog_v2",
  "target_collection_id": "col_catalog_enriched_v2",
  "taxonomy": {
    "config": {
      "input_mappings": [
        {
          "input_key": "image_vector",
          "path": "features.clip",
          "source_type": "vector"
        }
      ],
      "retriever_id": "ret_clip_v1",
      "source_collection": {
        "collection_id": "col_products_v1"
      },
      "taxonomy_type": "flat"
    },
    "input_mappings": [
      {
        "input_key": "image_vector",
        "path": "features.clip",
        "source_type": "vector"
      }
    ],
    "namespace_id": "ns_123",
    "retriever_id": "ret_clip_v1",
    "taxonomy_name": "product_tags"
  }
}'
{
  "stats": {
    "processed_docs": 0,
    "batches": 0,
    "errors": 0
  },
  "results": [
    {}
  ]
}

Headers

Authorization
string | null

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. Example: 'Bearer sk_1234567890abcdef'

X-Namespace
string | null

Optional namespace for data isolation. This can be a namespace name or namespace ID. Example: 'netflix_prod' or 'ns_1234567890'. To create a namespace, use the /namespaces endpoint.

Path Parameters

taxonomy_identifier
string
required

Taxonomy ID or name

Query Parameters

version
integer | null

Optional taxonomy version to execute

Body

application/json

Request model for on-demand taxonomy validation and testing.

NOTE: This endpoint only supports ON_DEMAND mode for testing/validation. Batch taxonomy materialization is automatically triggered by the engine after feature extraction completes, based on collection configuration.

taxonomy
object
required

Full taxonomy model with configuration (fetched from DB by controller)

Examples:
{
"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"
}
retriever
object | null

Optional retriever configuration override for testing. If omitted, uses the retriever configured in the taxonomy. Retriever model.

source_documents
Source Documents · object[] | null

Optional documents to enrich for testing. If omitted, validates configuration without processing documents.

source_collection_id
string | null

Collection reference (for context/logging only in ON_DEMAND mode)

target_collection_id
string | null

Not used in ON_DEMAND mode.

join_mode
enum<string>

Must be on_demand. Batch mode is not supported via API.

Available options:
on_demand,
batch
batch_size
integer
default:1000

Batch size for the scroll iterator

Required range: 1 <= x <= 10000
scroll_filters
object | null

Additional 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.

Response

Successful Response

stats
object
required
results
Results · object[] | null