Test taxonomy configuration (validation only)

curl --request POST \
  --url https://api.mixpeek.com/v1/taxonomies/execute/{taxonomy_identifier} \
  --header 'Authorization: Bearer <token>' \
  --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"
  }
}
'

import requests

url = "https://api.mixpeek.com/v1/taxonomies/execute/{taxonomy_identifier}"

payload = {
    "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"
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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'
    }
  })
};

fetch('https://api.mixpeek.com/v1/taxonomies/execute/{taxonomy_identifier}', 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/execute/{taxonomy_identifier}",
  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([
    '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'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$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/execute/{taxonomy_identifier}"

	payload := strings.NewReader("{\n  \"batch_size\": 1000,\n  \"join_mode\": \"on_demand\",\n  \"source_collection_id\": \"col_catalog_v2\",\n  \"target_collection_id\": \"col_catalog_enriched_v2\",\n  \"taxonomy\": {\n    \"config\": {\n      \"input_mappings\": [\n        {\n          \"input_key\": \"image_vector\",\n          \"path\": \"features.clip\",\n          \"source_type\": \"vector\"\n        }\n      ],\n      \"retriever_id\": \"ret_clip_v1\",\n      \"source_collection\": {\n        \"collection_id\": \"col_products_v1\"\n      },\n      \"taxonomy_type\": \"flat\"\n    },\n    \"input_mappings\": [\n      {\n        \"input_key\": \"image_vector\",\n        \"path\": \"features.clip\",\n        \"source_type\": \"vector\"\n      }\n    ],\n    \"namespace_id\": \"ns_123\",\n    \"retriever_id\": \"ret_clip_v1\",\n    \"taxonomy_name\": \"product_tags\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	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/execute/{taxonomy_identifier}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"batch_size\": 1000,\n  \"join_mode\": \"on_demand\",\n  \"source_collection_id\": \"col_catalog_v2\",\n  \"target_collection_id\": \"col_catalog_enriched_v2\",\n  \"taxonomy\": {\n    \"config\": {\n      \"input_mappings\": [\n        {\n          \"input_key\": \"image_vector\",\n          \"path\": \"features.clip\",\n          \"source_type\": \"vector\"\n        }\n      ],\n      \"retriever_id\": \"ret_clip_v1\",\n      \"source_collection\": {\n        \"collection_id\": \"col_products_v1\"\n      },\n      \"taxonomy_type\": \"flat\"\n    },\n    \"input_mappings\": [\n      {\n        \"input_key\": \"image_vector\",\n        \"path\": \"features.clip\",\n        \"source_type\": \"vector\"\n      }\n    ],\n    \"namespace_id\": \"ns_123\",\n    \"retriever_id\": \"ret_clip_v1\",\n    \"taxonomy_name\": \"product_tags\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.mixpeek.com/v1/taxonomies/execute/{taxonomy_identifier}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"batch_size\": 1000,\n  \"join_mode\": \"on_demand\",\n  \"source_collection_id\": \"col_catalog_v2\",\n  \"target_collection_id\": \"col_catalog_enriched_v2\",\n  \"taxonomy\": {\n    \"config\": {\n      \"input_mappings\": [\n        {\n          \"input_key\": \"image_vector\",\n          \"path\": \"features.clip\",\n          \"source_type\": \"vector\"\n        }\n      ],\n      \"retriever_id\": \"ret_clip_v1\",\n      \"source_collection\": {\n        \"collection_id\": \"col_products_v1\"\n      },\n      \"taxonomy_type\": \"flat\"\n    },\n    \"input_mappings\": [\n      {\n        \"input_key\": \"image_vector\",\n        \"path\": \"features.clip\",\n        \"source_type\": \"vector\"\n      }\n    ],\n    \"namespace_id\": \"ns_123\",\n    \"retriever_id\": \"ret_clip_v1\",\n    \"taxonomy_name\": \"product_tags\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "stats": {
    "processed_docs": 0,
    "batches": 0,
    "errors": 0,
    "enriched": 0
  },
  "results": [
    {}
  ],
  "matches": [
    {
      "document_id": "<string>",
      "taxonomy_id": "<string>",
      "taxonomy_name": "<string>",
      "node_id": "<string>",
      "label": "<string>",
      "score": 123,
      "path": [
        "<string>"
      ],
      "hierarchy_level": 123,
      "enriched_fields": [
        "<string>"
      ]
    }
  ]
}

{
  "status": 123,
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "details": {}
  },
  "success": false
}

{
  "status": 123,
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "details": {}
  },
  "success": false
}

{
  "status": 123,
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "details": {}
  },
  "success": false
}

{
  "status": 123,
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "details": {}
  },
  "success": false
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

{
  "status": 123,
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "details": {}
  },
  "success": false
}

Taxonomies

Test taxonomy configuration (validation only)

⚠️ VALIDATION ENDPOINT ONLY - Not for production enrichment!

This endpoint validates taxonomy configuration with 1-5 sample documents. Results are returned immediately and NOT persisted to any collection.

❌ DO NOT USE FOR:

Enriching entire collections (use taxonomy_applications instead)
Batch processing documents (automatic during ingestion)
Persisting enriched documents (use retriever pipelines instead)

✅ USE THIS FOR:

Testing taxonomy configuration is correct
Validating retriever finds matching taxonomy nodes
Checking enrichment fields are properly applied
Development/debugging taxonomy setup

📚 FOR PRODUCTION ENRICHMENT:

Automatic (during ingestion):

Create taxonomy: POST /taxonomies
Attach to collection: PUT /collections/ with taxonomy_applications field
Ingest documents: Documents are automatically enriched by engine

On-the-fly (during retrieval):

Add taxonomy_join stage to retriever pipeline
Execute retriever: GET /retrievers//execute
Results include enriched documents (not persisted)

See API documentation for Collections and Retrievers for details.

POST

taxonomies

execute

{taxonomy_identifier}

Test taxonomy configuration (validation only)

curl --request POST \
  --url https://api.mixpeek.com/v1/taxonomies/execute/{taxonomy_identifier} \
  --header 'Authorization: Bearer <token>' \
  --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"
  }
}
'

import requests

url = "https://api.mixpeek.com/v1/taxonomies/execute/{taxonomy_identifier}"

payload = {
    "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"
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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'
    }
  })
};

fetch('https://api.mixpeek.com/v1/taxonomies/execute/{taxonomy_identifier}', 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/execute/{taxonomy_identifier}",
  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([
    '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'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$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/execute/{taxonomy_identifier}"

	payload := strings.NewReader("{\n  \"batch_size\": 1000,\n  \"join_mode\": \"on_demand\",\n  \"source_collection_id\": \"col_catalog_v2\",\n  \"target_collection_id\": \"col_catalog_enriched_v2\",\n  \"taxonomy\": {\n    \"config\": {\n      \"input_mappings\": [\n        {\n          \"input_key\": \"image_vector\",\n          \"path\": \"features.clip\",\n          \"source_type\": \"vector\"\n        }\n      ],\n      \"retriever_id\": \"ret_clip_v1\",\n      \"source_collection\": {\n        \"collection_id\": \"col_products_v1\"\n      },\n      \"taxonomy_type\": \"flat\"\n    },\n    \"input_mappings\": [\n      {\n        \"input_key\": \"image_vector\",\n        \"path\": \"features.clip\",\n        \"source_type\": \"vector\"\n      }\n    ],\n    \"namespace_id\": \"ns_123\",\n    \"retriever_id\": \"ret_clip_v1\",\n    \"taxonomy_name\": \"product_tags\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	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/execute/{taxonomy_identifier}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"batch_size\": 1000,\n  \"join_mode\": \"on_demand\",\n  \"source_collection_id\": \"col_catalog_v2\",\n  \"target_collection_id\": \"col_catalog_enriched_v2\",\n  \"taxonomy\": {\n    \"config\": {\n      \"input_mappings\": [\n        {\n          \"input_key\": \"image_vector\",\n          \"path\": \"features.clip\",\n          \"source_type\": \"vector\"\n        }\n      ],\n      \"retriever_id\": \"ret_clip_v1\",\n      \"source_collection\": {\n        \"collection_id\": \"col_products_v1\"\n      },\n      \"taxonomy_type\": \"flat\"\n    },\n    \"input_mappings\": [\n      {\n        \"input_key\": \"image_vector\",\n        \"path\": \"features.clip\",\n        \"source_type\": \"vector\"\n      }\n    ],\n    \"namespace_id\": \"ns_123\",\n    \"retriever_id\": \"ret_clip_v1\",\n    \"taxonomy_name\": \"product_tags\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.mixpeek.com/v1/taxonomies/execute/{taxonomy_identifier}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"batch_size\": 1000,\n  \"join_mode\": \"on_demand\",\n  \"source_collection_id\": \"col_catalog_v2\",\n  \"target_collection_id\": \"col_catalog_enriched_v2\",\n  \"taxonomy\": {\n    \"config\": {\n      \"input_mappings\": [\n        {\n          \"input_key\": \"image_vector\",\n          \"path\": \"features.clip\",\n          \"source_type\": \"vector\"\n        }\n      ],\n      \"retriever_id\": \"ret_clip_v1\",\n      \"source_collection\": {\n        \"collection_id\": \"col_products_v1\"\n      },\n      \"taxonomy_type\": \"flat\"\n    },\n    \"input_mappings\": [\n      {\n        \"input_key\": \"image_vector\",\n        \"path\": \"features.clip\",\n        \"source_type\": \"vector\"\n      }\n    ],\n    \"namespace_id\": \"ns_123\",\n    \"retriever_id\": \"ret_clip_v1\",\n    \"taxonomy_name\": \"product_tags\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "stats": {
    "processed_docs": 0,
    "batches": 0,
    "errors": 0,
    "enriched": 0
  },
  "results": [
    {}
  ],
  "matches": [
    {
      "document_id": "<string>",
      "taxonomy_id": "<string>",
      "taxonomy_name": "<string>",
      "node_id": "<string>",
      "label": "<string>",
      "score": 123,
      "path": [
        "<string>"
      ],
      "hierarchy_level": 123,
      "enriched_fields": [
        "<string>"
      ]
    }
  ]
}

{
  "status": 123,
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "details": {}
  },
  "success": false
}

{
  "status": 123,
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "details": {}
  },
  "success": false
}

{
  "status": 123,
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "details": {}
  },
  "success": false
}

{
  "status": 123,
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "details": {}
  },
  "success": false
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

{
  "status": 123,
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>",
    "details": {}
  },
  "success": false
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

taxonomy_identifier

string

required

Taxonomy ID or name to validate

Query Parameters

version

integer | null

Optional taxonomy version (defaults to latest)

Body

application/json

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_applications field
Retrievers API: add taxonomy_join stage for on-the-fly enrichment

taxonomy

TaxonomyModel · object

required

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

Show child attributes

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

RetrieverModel · object | null

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

Show child attributes

source_documents

Source Documents · object[] | null

Sample documents to test enrichment (typically 1-5 docs). Results are returned immediately, not persisted. ⚠️ Do NOT pass collection_id expecting batch processing!

source_collection_id

string | null

⚠️ IGNORED IN ON_DEMAND MODE. This field exists for legacy compatibility only. To enrich collections, use taxonomy_applications on the collection.

target_collection_id

string | null

⚠️ IGNORED IN ON_DEMAND MODE. This field exists for legacy compatibility only. Results are never persisted via this endpoint.

join_mode

enum<string>

default:on_demand

Must be 'on_demand'. BATCH mode is NOT supported via API. Batch enrichment is automatic (triggered by engine during ingestion).

Available options:

on_demand,

batch

batch_size

integer

default:1000

Batch size for the scroll iterator

Required range: 1 <= x <= 10000

scroll_filters

LogicalOperator · object | null

Additional filters applied to the source collection prior to enrichment.

Show child attributes

Response

Successful Response

stats

JoinStats · object

required

Show child attributes

results

Results · object[] | null

matches

TaxonomyMatch · object[] | null

Flattened per-document match summaries extracted from processing_history — convenience for clients so they don't have to spelunk metadata.processing_history.

Show child attributes

List Taxonomies List Taxonomy Versions

Organization

Namespaces

Buckets

Feature Extractors

Batch Queue

Collections

Documents

Retrievers

Taxonomies

Clusters

Triggers

Alerts

Webhooks

Apps

Agent Sessions

Annotations

Templates

Manifest

Discovery

Analytics

Notifications

Tasks

Inference

Resource Search

Pricing

Test taxonomy configuration (validation only)

Authorizations

Path Parameters

Query Parameters

Body

Response