> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mixpeek.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Trigger

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



## OpenAPI

````yaml post /v1/triggers
openapi: 3.1.0
info:
  title: Mixpeek API
  description: >-
    This is the Mixpeek API, providing access to various endpoints for data
    processing and retrieval.
  termsOfService: https://mixpeek.com/terms
  contact:
    name: Mixpeek Support
    url: https://mixpeek.com/contact
    email: info@mixpeek.com
  version: '0.82'
servers:
  - url: https://api.mixpeek.com
    description: Production
security: []
paths:
  /v1/triggers:
    post:
      tags:
        - Triggers
      summary: Create Trigger
      description: |-
        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"
            }
            ```
      operationId: create_trigger_v1_triggers_post
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: >-
                #/components/schemas/shared__triggers__models__CreateTriggerRequest
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/shared__triggers__models__TriggerModel'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    shared__triggers__models__CreateTriggerRequest:
      properties:
        action_type:
          $ref: '#/components/schemas/TriggerActionType'
          description: Type of action to execute
        action_config:
          additionalProperties: true
          type: object
          title: Action Config
          description: Action-specific configuration
        trigger_type:
          $ref: '#/components/schemas/shared__triggers__models__TriggerType'
          description: Type of schedule
        schedule_config:
          additionalProperties: true
          type: object
          title: Schedule Config
          description: Schedule-specific configuration
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
          description: Human-readable description
        status:
          $ref: '#/components/schemas/shared__triggers__models__TriggerStatus'
          description: Initial status (active or paused)
          default: active
      type: object
      required:
        - action_type
        - action_config
        - trigger_type
        - schedule_config
      title: CreateTriggerRequest
      description: |-
        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"
                }
      examples:
        - action_config:
            cluster_id: clust_abc123
          action_type: cluster
          description: Daily clustering at 2am
          schedule_config:
            cron_expression: 0 2 * * *
            timezone: UTC
          trigger_type: cron
        - action_config:
            cluster_id: clust_abc123
            filters:
              status: active
            output_collection_ids:
              - col_daily_clusters
          action_type: cluster
          description: Daily clustering of active items with output override
          schedule_config:
            cron_expression: 0 2 * * *
            timezone: UTC
          trigger_type: cron
        - action_config:
            collection_id: col_inventory
            taxonomy_id: tax_products
          action_type: taxonomy_enrichment
          description: Re-enrich products every 6 hours (in-place)
          schedule_config:
            interval_seconds: 21600
            start_immediately: false
          trigger_type: interval
        - action_config:
            collection_id: col_inventory
            incremental: true
            taxonomy_id: tax_products
          action_type: taxonomy_enrichment
          description: Hourly incremental enrichment (only new docs)
          schedule_config:
            interval_seconds: 3600
          trigger_type: interval
        - action_config:
            batch_size: 500
            collection_id: col_inventory
            incremental: true
            parallelism: 8
            target_collection_id: col_enriched
            taxonomy_id: tax_products
          action_type: taxonomy_enrichment
          description: Nightly incremental enrichment to target collection
          schedule_config:
            cron_expression: 0 3 * * *
            timezone: UTC
          trigger_type: cron
    shared__triggers__models__TriggerModel:
      properties:
        trigger_id:
          type: string
          title: Trigger Id
          description: Unique trigger identifier
        namespace_id:
          type: string
          title: Namespace Id
          description: Namespace ID
        internal_id:
          type: string
          title: Internal Id
          description: Organization internal ID
        action_type:
          $ref: '#/components/schemas/TriggerActionType'
          description: Type of action to execute
        action_config:
          additionalProperties: true
          type: object
          title: Action Config
          description: Action-specific configuration
        trigger_type:
          $ref: '#/components/schemas/shared__triggers__models__TriggerType'
          description: Type of schedule
        schedule_config:
          additionalProperties: true
          type: object
          title: Schedule Config
          description: Schedule-specific configuration
        status:
          $ref: '#/components/schemas/shared__triggers__models__TriggerStatus'
          description: Current trigger status
          default: active
        last_triggered_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Last Triggered At
          description: Last time trigger fired
        last_execution_task_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Last Execution Task Id
          description: Task ID of last execution
        next_scheduled_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Next Scheduled At
          description: Next scheduled execution time
        execution_count:
          type: integer
          title: Execution Count
          description: Total successful executions
          default: 0
        consecutive_failures:
          type: integer
          title: Consecutive Failures
          description: Consecutive failures
          default: 0
        last_execution_status:
          anyOf:
            - type: string
            - type: 'null'
          title: Last Execution Status
          description: Status of last execution
        last_execution_error:
          anyOf:
            - type: string
            - type: 'null'
          title: Last Execution Error
          description: Error from last execution (if failed)
        event_counter:
          type: integer
          title: Event Counter
          description: Current event count since last trigger
          default: 0
        last_cooldown_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Last Cooldown At
          description: Last time cooldown was applied
        baseline_snapshot:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Baseline Snapshot
          description: >-
            Baseline snapshot for drift measurement (captured after successful
            execution)
        last_drift_measurement:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Last Drift Measurement
          description: Result of most recent drift measurement check
        last_volume_measurement:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Last Volume Measurement
          description: Result of most recent volume (document count) condition check
        last_condition_check_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Last Condition Check At
          description: When condition was last evaluated
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
          description: Human-readable description
        created_at:
          type: string
          format: date-time
          title: Created At
          description: Creation timestamp
        updated_at:
          type: string
          format: date-time
          title: Updated At
          description: Last update timestamp
        created_by:
          anyOf:
            - type: string
            - type: 'null'
          title: Created By
          description: User who created trigger
      type: object
      required:
        - namespace_id
        - internal_id
        - action_type
        - action_config
        - trigger_type
        - schedule_config
      title: TriggerModel
      description: |-
        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)
    ErrorResponse:
      properties:
        success:
          type: boolean
          title: Success
          description: Always false for error responses
          default: false
        status:
          type: integer
          title: Status
          description: HTTP status code for this error
        error:
          $ref: '#/components/schemas/ErrorDetail'
          description: Error details payload
      type: object
      required:
        - status
        - error
      title: ErrorResponse
      description: Error response model.
      examples:
        - error:
            details:
              id: ns_123
              resource: namespace
            message: Namespace not found
            type: NotFoundError
          status: 404
          success: false
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    TriggerActionType:
      type: string
      enum:
        - cluster
        - taxonomy_enrichment
        - batch_rerun
        - collection_trigger
      title: TriggerActionType
      description: |-
        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
    shared__triggers__models__TriggerType:
      type: string
      enum:
        - cron
        - interval
        - event
        - conditional
      title: TriggerType
      description: |-
        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
    shared__triggers__models__TriggerStatus:
      type: string
      enum:
        - active
        - paused
        - disabled
        - failed
      title: TriggerStatus
      description: Status of a trigger.
    ErrorDetail:
      properties:
        message:
          type: string
          title: Message
          description: Human-readable error message
        type:
          type: string
          title: Type
          description: Stable error type identifier (machine-readable)
        code:
          anyOf:
            - type: string
            - type: 'null'
          title: Code
          description: >-
            Fine-grained error code for programmatic handling (e.g.,
            namespace_name_taken, feature_extractor_not_found). Present only
            when consumers may need to branch on a specific error condition.
        details:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Details
          description: >-
            Optional structured details to help debugging (validation errors,
            IDs, etc.)
      type: object
      required:
        - message
        - type
      title: ErrorDetail
      description: Error detail model.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError

````