Apply Taxonomy to Existing Documents

Apply a taxonomy to all existing documents in a collection retroactively.

This endpoint triggers distributed Ray processing to enrich existing documents with taxonomy data. Unlike automatic materialization (which happens during ingestion), this endpoint allows you to:

1. Backfill enrichment for documents ingested before the taxonomy was created
2. Re-apply taxonomy after configuration changes
3. Process specific subsets using scroll_filters

⚙️ Processing Details:

• Uses Ray datasets with map_batches for parallel processing
• Scales horizontally across Ray cluster
• Non-blocking: Returns immediately with task_id
• Monitor progress via Tasks API

⚠️ Prerequisites:

• Taxonomy must exist and be valid
• Taxonomy must be in collection’s taxonomy_applications list
• Collection must contain documents

📊 Performance:

• ~1000-5000 docs/second depending on cluster size
• Parallel processing across multiple Ray workers
• Batch size and parallelism configurable

🔍 Use Cases:

• Backfill: Apply new taxonomy to historical data
• Re-enrichment: Update after taxonomy changes
• Selective: Process filtered document subsets

See Collections API and Taxonomies API documentation for details.

POST /v1/collections/{collection_identifier}/apply-taxonomy

Apply Taxonomy to Existing Documents

cURL

curl --request POST \
  --url https://api.mixpeek.com/v1/collections/{collection_identifier}/apply-taxonomy \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Namespace: <api-key>' \
  --data '
{
  "description": "Apply taxonomy to all documents",
  "taxonomy_id": "tax_abc123"
}
'

200

{
  "collection_id": "col_products",
  "estimated_documents": 15000,
  "status": "submitted",
  "task_id": "ray_task_abc123",
  "taxonomy_id": "tax_categories"
}

Authorizations

Authorization · string · header · required

Mixpeek API key, sent as Authorization: Bearer mxp_sk_.... Create one in Studio under Settings → API Keys, or with an admin key via POST /v1/organizations/users/{user_email}/api-keys. A missing, malformed, unknown, revoked, inactive or expired key returns 401; a key without the permission, scope or plan an operation needs returns 403.

X-Namespace · string · header · required

Namespace id (ns_...), not the namespace name. This scopes the request rather than authenticating it, and it is required on every operation marked x-mixpeek-namespace-scoped.

Path Parameters

collection_identifier · string · required

Collection ID or name to apply taxonomy to

Body

application/json

Keys this body does not declare are refused with 422 extra_forbidden naming the accepted keys (since 2026-11-02).

Request to apply a taxonomy to an existing collection.

This endpoint triggers retroactive taxonomy materialization on all documents in a collection using distributed Ray processing.

Use Cases: - Apply taxonomy to documents that were ingested before the taxonomy was created - Re-apply taxonomy after taxonomy configuration changes - Backfill enrichment data for existing collections

Requirements: - taxonomy_id: REQUIRED - Must be an existing, valid taxonomy - The taxonomy must already be attached to the collection via taxonomy_applications - Documents must exist in the collection

taxonomy_id · string · required

ID of the taxonomy to apply. REQUIRED. Must be an existing taxonomy (tax_*). The taxonomy must already be in the collection's taxonomy_applications list.

Examples:

"tax_abc123"

"tax_products"

scroll_filters · Scroll Filters · object | null

Optional filters to limit which documents are enriched. NOT REQUIRED. If not provided, all documents in the collection will be enriched. Use to process specific subsets (e.g., documents missing enrichment).

Example:

{
  "must": [
    {
      "key": "metadata.category",
      "match": { "value": "products" }
    }
  ]
}

batch_size · integer · default: 1000

Number of documents to process in each parallel batch. NOT REQUIRED. Defaults to 1000. Larger batches = fewer Ray tasks but more memory per task. Smaller batches = more Ray tasks but lower memory per task.

Required range: 100 <= x <= 5000

Examples:

1000

500

2000

parallelism · integer · default: 4

Number of parallel Ray workers to use for processing. NOT REQUIRED. Defaults to 4. Higher parallelism = faster processing but more cluster resources. Set based on available Ray cluster capacity.

Required range: 1 <= x <= 20

Examples:

4

8

2

budget_limits · BudgetLimits · object | null

Optional budget for this job. max_time_ms stops the job when it has run that long: documents already enriched keep their assignments, the task ends CANCELED, and its stats carry budget, spent and stopped_at. max_credits is refused: taxonomy enrichment bills 0 credits, so a credit cap could never stop this job.

Show child attributes

Example:

{
  "max_credits": 100,
  "max_time_ms": 3600000
}

Response

200

application/json

Successful Response

Response from applying taxonomy to collection.

Returns statistics about the materialization process.

task_id · string · required

ID of the Ray task executing the materialization

status · string · required

Status of the materialization task

Examples:

"submitted"

"running"

"completed"

"failed"

collection_id · string · required

Collection ID where taxonomy is being applied

taxonomy_id · string · required

Taxonomy ID being applied

estimated_documents · integer | null

Estimated number of documents to process (if available)