---
title: "Create Trigger"
method: POST
path: "/v1/triggers"
tags: ["Triggers"]
---

# Create Trigger

`POST /v1/triggers`

Create a new trigger for scheduled job execution.

    **Action Types:**
    - `cluster`: Execute clustering on a cluster definition
    - `taxonomy_enrichment`: Apply taxonomy enrichment to a collection

    **Schedule Types:**
    - `cron`: Execute at specific times using cron expressions (e.g., "0 2 * * *" for daily at 2am)
    - `interval`: Execute at fixed intervals (e.g., every 6 hours)
    - `event`: Execute when specific events occur (e.g., after 100 documents added)
    - `conditional`: Execute when conditions are met (e.g., drift threshold exceeded)

    **Examples:**

    Cluster trigger (daily at 2am):
    ```json
    {
      "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"
    }
    ```

    Taxonomy enrichment trigger (every 6 hours):
    ```json
    {
      "action_type": "taxonomy_enrichment",
      "action_config": {
        "taxonomy_id": "tax_products",
        "collection_id": "col_inventory",
        "batch_size": 1000
      },
      "trigger_type": "interval",
      "schedule_config": {"interval_seconds": 21600},
      "description": "Re-enrich products every 6 hours"
    }
    ```

## Request body

- SharedTriggersModelsCreateTriggerRequest — Request to create a new trigger. Examples: Cluster trigger (cron): { "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" } Taxonomy trigger (interval): { "action_type": "taxonomy_enrichment", "action_config": {"taxonomy_id": "tax_products", "collection_id": "col_inv"}, "trigger_type": "interval", "schedule_config": {"interval_seconds": 21600}, "description": "Re-enrich every 6 hours" }
  - `action_type` 'cluster' | 'taxonomy_enrichment' | 'batch_rerun' | 'collection_trigger', required — Type of action to execute when trigger fires. Supported action types: - **cluster**: Execute clustering on a cluster definition - **taxonomy_enrichment**: Apply taxonomy enrichment to a collection - **batch_rerun**: Re-execute a completed/failed batch
  - `action_config` object, required — Action-specific configuration
  - `trigger_type` 'cron' | 'interval' | 'event' | 'conditional', required — Type of trigger schedule. Supported trigger types: - **cron**: Schedule-based execution using cron expressions - **interval**: Fixed-interval execution - **event**: Event-driven execution - **conditional**: Condition-based execution
  - `schedule_config` object, required — Schedule-specific configuration
  - `description` string, nullable — Human-readable description
  - `status` 'active' | 'paused' | 'disabled' | 'failed' — Status of a trigger.

## Response `201`

Successful Response

- SharedTriggersModelsTriggerModel — Unified trigger model for all action types. A trigger defines: 1. **What** to execute (action_type + action_config) 2. **When** to execute (trigger_type + schedule_config) 3. **State** tracking (execution count, failures, next scheduled time)
  - `trigger_id` string — Unique trigger identifier
  - `namespace_id` string, required — Namespace ID
  - `internal_id` string, required — Organization internal ID
  - `action_type` 'cluster' | 'taxonomy_enrichment' | 'batch_rerun' | 'collection_trigger', required — Type of action to execute when trigger fires. Supported action types: - **cluster**: Execute clustering on a cluster definition - **taxonomy_enrichment**: Apply taxonomy enrichment to a collection - **batch_rerun**: Re-execute a completed/failed batch
  - `action_config` object, required — Action-specific configuration
  - `trigger_type` 'cron' | 'interval' | 'event' | 'conditional', required — Type of trigger schedule. Supported trigger types: - **cron**: Schedule-based execution using cron expressions - **interval**: Fixed-interval execution - **event**: Event-driven execution - **conditional**: Condition-based execution
  - `schedule_config` object, required — Schedule-specific configuration
  - `status` 'active' | 'paused' | 'disabled' | 'failed' — Status of a trigger.
  - `last_triggered_at` string, date-time, nullable — Last time trigger fired
  - `last_execution_task_id` string, nullable — Task ID of last execution
  - `next_scheduled_at` string, date-time, nullable — Next scheduled execution time
  - `execution_count` integer — Total successful executions
  - `consecutive_failures` integer — Consecutive failures
  - `last_execution_status` string, nullable — Status of last execution
  - `last_execution_error` string, nullable — Error from last execution (if failed)
  - `event_counter` integer — Current event count since last trigger
  - `last_cooldown_at` string, date-time, nullable — Last time cooldown was applied
  - `baseline_snapshot` object, nullable — Baseline snapshot for drift measurement (captured after successful execution)
  - `last_drift_measurement` object, nullable — Result of most recent drift measurement check
  - `last_volume_measurement` object, nullable — Result of most recent volume (document count) condition check
  - `last_condition_check_at` string, date-time, nullable — When condition was last evaluated
  - `description` string, nullable — Human-readable description
  - `created_at` string, date-time — Creation timestamp
  - `updated_at` string, date-time — Last update timestamp
  - `created_by` string, nullable — User who created trigger

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `422` — Validation Error
- `500` — Internal Server Error

---

[API](https://skmtc.net/mixpeek/apis/mixpeek-api.md) · [All operations](https://skmtc.net/mixpeek/apis/mixpeek-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mixpeek/mixpeek-api/versions/220a3b263fda/schema)