Triggers - Mixpeek

Triggers run platform actions automatically — re-cluster a collection nightly, re-enrich documents as new data lands, or rerun a batch on a schedule. Instead of calling an endpoint by hand, you define what to run and when, and Mixpeek executes it.

Anatomy of a trigger

Every trigger combines an action (what to run) with a schedule (when to run it):

curl -sS -X POST "$MP_API_URL/v1/triggers" \
  -H "Authorization: Bearer $MP_API_KEY" \
  -H "X-Namespace: $MP_NAMESPACE" \
  -H "Content-Type: application/json" \
  -d '{
    "action_type": "cluster",
    "action_config": { "cluster_id": "clust_abc123" },
    "trigger_type": "cron",
    "schedule_config": { "cron_expression": "0 2 * * *", "timezone": "UTC" },
    "description": "Daily clustering at 2am"
  }'

Field	Description
`action_type`	What to run: `cluster`, `taxonomy_enrichment`, `batch_rerun`, `collection_trigger`.
`action_config`	Action-specific config (e.g. `{ "cluster_id": "..." }`).
`trigger_type`	When to run: `cron`, `interval`, `event`, `conditional`.
`schedule_config`	Schedule-specific config (cron expression, interval seconds, etc.).
`description`	Human-readable label.
`status`	`active` (default) or `paused`.

Schedule types

Cron
Interval
Event / Conditional

Run on a cron expression in a given timezone — best for fixed times (“every night at 2am”).

{
  "trigger_type": "cron",
  "schedule_config": { "cron_expression": "0 2 * * *", "timezone": "UTC" }
}

The expression is standard 5-field cron (minute hour day-of-month month day-of-week).

Run every N seconds — best for “keep it fresh” loops. Set start_immediately to run once on creation.

{
  "trigger_type": "interval",
  "schedule_config": { "interval_seconds": 3600, "start_immediately": false }
}

event triggers fire in response to platform events (e.g. new documents in a collection); conditional triggers fire when a condition is met. Provide the event/condition details in schedule_config. Use cron or interval for time-based schedules.

Actions

Cluster

Re-run a clustering definition on a schedule so groupings stay current as data grows.

curl -sS -X POST "$MP_API_URL/v1/triggers" \
  -H "Authorization: Bearer $MP_API_KEY" \
  -H "X-Namespace: $MP_NAMESPACE" \
  -H "Content-Type: application/json" \
  -d '{
    "action_type": "cluster",
    "action_config": {
      "cluster_id": "clust_abc123",
      "filters": { "status": "active" },
      "output_collection_ids": ["col_daily_clusters"]
    },
    "trigger_type": "cron",
    "schedule_config": { "cron_expression": "0 2 * * *", "timezone": "UTC" },
    "description": "Daily clustering of active items"
  }'

Taxonomy enrichment

Re-classify a collection against a taxonomy. Use incremental: true to enrich only new documents — far cheaper than re-running the whole collection.

curl -sS -X POST "$MP_API_URL/v1/triggers" \
  -H "Authorization: Bearer $MP_API_KEY" \
  -H "X-Namespace: $MP_NAMESPACE" \
  -H "Content-Type: application/json" \
  -d '{
    "action_type": "taxonomy_enrichment",
    "action_config": {
      "collection_id": "col_inventory",
      "taxonomy_id": "tax_products",
      "incremental": true
    },
    "trigger_type": "interval",
    "schedule_config": { "interval_seconds": 3600 },
    "description": "Hourly incremental enrichment (only new docs)"
  }'

Enrich into a separate target collection on a nightly cron:

curl -sS -X POST "$MP_API_URL/v1/triggers" \
  -H "Authorization: Bearer $MP_API_KEY" \
  -H "X-Namespace: $MP_NAMESPACE" \
  -H "Content-Type: application/json" \
  -d '{
    "action_type": "taxonomy_enrichment",
    "action_config": {
      "collection_id": "col_inventory",
      "taxonomy_id": "tax_products",
      "target_collection_id": "col_enriched",
      "incremental": true,
      "batch_size": 500,
      "parallelism": 8
    },
    "trigger_type": "cron",
    "schedule_config": { "cron_expression": "0 3 * * *", "timezone": "UTC" },
    "description": "Nightly incremental enrichment to target collection"
  }'

incremental: true only processes documents added since the last run, so it won’t re-pay extraction/enrichment cost on documents already processed. Prefer it for recurring enrichment.

Batch rerun & collection trigger

batch_rerun re-runs processing for a collection’s documents; collection_trigger fires a collection’s configured processing. Both take a collection_id in action_config.

Manage triggers

Operation	Endpoint
List	`POST /v1/triggers/list`
Get	`GET /v1/triggers/{trigger_id}`
Update	`PATCH /v1/triggers/{trigger_id}`
Run now	`POST /v1/triggers/{trigger_id}/execute`
Pause / resume	`POST /v1/triggers/{trigger_id}/pause` · `POST .../resume`
Run history	`GET /v1/triggers/{trigger_id}/history`
Delete	`DELETE /v1/triggers/{trigger_id}`

Run a trigger on demand (outside its schedule) to test it:

curl -sS -X POST "$MP_API_URL/v1/triggers/{trigger_id}/execute" \
  -H "Authorization: Bearer $MP_API_KEY" -H "X-Namespace: $MP_NAMESPACE"

Check recent runs and their outcomes:

curl -sS "$MP_API_URL/v1/triggers/{trigger_id}/history" \
  -H "Authorization: Bearer $MP_API_KEY" -H "X-Namespace: $MP_NAMESPACE"

Clusters — define the clustering a cluster trigger reruns
Taxonomies — define the taxonomy a taxonomy_enrichment trigger applies
Alerts — get notified when content matches a condition
Storage syncs — continuously ingest new files from object storage

​Anatomy of a trigger

​Schedule types

​Actions

​Cluster

​Taxonomy enrichment

​Batch rerun & collection trigger

​Manage triggers

​Related

Anatomy of a trigger

Schedule types

Actions

Cluster

Taxonomy enrichment

Batch rerun & collection trigger

Manage triggers

Related