⚠️ VALIDATION ENDPOINT ONLY - Not for production enrichment!

DEPRECATED path shape — prefer POST /taxonomies/{id}/execute (id-first, consistent with retrievers). This verb-first path still works.

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):

1. Create taxonomy: POST /v1/taxonomies
2. Attach to collection: PATCH /v1/collections/{id} with taxonomy_applications field
3. Ingest documents: Documents are automatically enriched by engine

On-the-fly (during retrieval):

1. Add taxonomy_join stage to retriever pipeline
2. Execute retriever: POST /v1/retrievers/{id}/execute
3. Results include enriched documents (not persisted)

See API documentation for Collections and Retrievers for details.

{
  "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"
  }
}