> ## 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.

# Trigger Collection Processing

> Process data through a collection - works for both bucket-sourced and collection-sourced collections.

    **For bucket-sourced collections:**
    Discovers objects from source bucket(s), creates a batch, and submits for processing.
    Use `include_buckets` to limit which source buckets to process from.

    **For collection-sourced collections:**
    Processes existing documents from upstream collection(s).
    Use `include_collections` to limit which source collections to process from.

    **Filtering:**
    - `source_filters`: Field-level filters using LogicalOperator format
    - Example: `{"AND": [{"field": "status", "operator": "eq", "value": "pending"}]}`
    - For specific objects: `{"AND": [{"field": "object_id", "operator": "in", "value": ["obj_1", "obj_2"]}]}`

    **Returns:**
    - batch_id: Track progress via GET /batches/{batch_id}
    - task_id: Monitor via GET /tasks/{task_id}



## OpenAPI

````yaml post /v1/collections/{collection_identifier}/trigger
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/collections/{collection_identifier}/trigger:
    post:
      tags:
        - Collections
      summary: Trigger Collection Processing
      description: >-
        Process data through a collection - works for both bucket-sourced and
        collection-sourced collections.

            **For bucket-sourced collections:**
            Discovers objects from source bucket(s), creates a batch, and submits for processing.
            Use `include_buckets` to limit which source buckets to process from.

            **For collection-sourced collections:**
            Processes existing documents from upstream collection(s).
            Use `include_collections` to limit which source collections to process from.

            **Filtering:**
            - `source_filters`: Field-level filters using LogicalOperator format
            - Example: `{"AND": [{"field": "status", "operator": "eq", "value": "pending"}]}`
            - For specific objects: `{"AND": [{"field": "object_id", "operator": "in", "value": ["obj_1", "obj_2"]}]}`

            **Returns:**
            - batch_id: Track progress via GET /batches/{batch_id}
            - task_id: Monitor via GET /tasks/{task_id}
      operationId: trigger_collection_v1_collections__collection_identifier__trigger_post
      parameters:
        - name: collection_identifier
          in: path
          required: true
          schema:
            type: string
            description: The ID or name of the collection to trigger
            title: Collection Identifier
          description: The ID or name of the collection to trigger
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TriggerCollectionRequest'
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TriggerCollectionResponse'
        '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:
    TriggerCollectionRequest:
      properties:
        include_buckets:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Include Buckets
          description: >-
            Limit processing to objects from these specific buckets (IDs or
            names). Only applies to bucket-sourced collections. If not provided,
            all configured source buckets are used.
        include_collections:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Include Collections
          description: >-
            Limit processing to documents from these specific collections (IDs
            or names). Only applies to collection-sourced collections. If not
            provided, all configured source collections are used.
        object_ids:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Object Ids
          description: >-
            Limit processing to these specific object IDs. Only applies to
            bucket-sourced collections. This is a convenience shorthand —
            equivalent to using source_filters with {"AND": [{"field":
            "object_id", "operator": "in", "value": [...]}]}.
        source_filters:
          anyOf:
            - $ref: '#/components/schemas/LogicalOperator-Input'
            - type: 'null'
          description: >-
            Field-level filters for objects (bucket-sourced) or documents
            (collection-sourced). Uses LogicalOperator format (AND/OR/NOT). Use
            this to filter by metadata fields, status, or any other
            object/document properties.
          examples:
            - AND:
                - field: status
                  operator: eq
                  value: pending
            - AND:
                - field: object_id
                  operator: in
                  value:
                    - obj_1
                    - obj_2
        dedup_strategy:
          anyOf:
            - $ref: '#/components/schemas/DedupStrategy'
            - type: 'null'
          description: >-
            How to handle sources already processed in prior batches. `skip`
            (default): skip sources already materialized in this collection.
            `replace`: delete existing documents for the re-processed sources
            and re-materialize them — this also clears the processed-objects
            resume ledger, so use it to recover a collection stuck with ledger
            entries but 0 materialized documents (the orphan/divergence state).
            `force`: process regardless, allowing duplicates.
      type: object
      title: TriggerCollectionRequest
      description: >-
        Request to trigger (re)processing through a collection.


        **For bucket-sourced collections (tier 0):**

        Discovers objects from source bucket(s) and creates a batch for
        processing.

        Use `include_buckets` to limit which source buckets to process from.


        **For collection-sourced collections (tier N):**

        Processes existing documents from upstream collection(s).

        Use `include_collections` to limit which source collections to process
        from.


        Use `source_filters` for field-level filtering on objects or documents.


        **Document Overwrite Behavior:**

        - If source bucket has `unique_key` configured: Documents are UPSERTED
        (overwrites existing)

        - If source bucket has NO `unique_key`: New documents are CREATED (may
        cause duplicates)


        To enable idempotent re-processing, configure `unique_key` on the source
        bucket.
    TriggerCollectionResponse:
      properties:
        batch_id:
          type: string
          title: Batch Id
          description: ID of the created batch for tracking progress.
        task_id:
          type: string
          title: Task Id
          description: Task ID for monitoring via GET /v1/tasks/{task_id}.
        collection_id:
          type: string
          title: Collection Id
          description: ID of the collection being processed.
        source_bucket_ids:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Source Bucket Ids
          description: >-
            Bucket IDs that objects were discovered from (bucket-sourced
            collections).
        source_collection_ids:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Source Collection Ids
          description: >-
            Collection IDs that documents were read from (collection-sourced
            collections).
        object_count:
          anyOf:
            - type: integer
            - type: 'null'
          title: Object Count
          description: >-
            Total number of objects included in the batch (bucket-sourced
            collections).
        document_count:
          anyOf:
            - type: integer
            - type: 'null'
          title: Document Count
          description: >-
            Total number of documents to process (collection-sourced
            collections).
        total_tiers:
          type: integer
          title: Total Tiers
          description: Number of processing tiers in the DAG.
        message:
          type: string
          title: Message
          description: Human-readable status message.
      type: object
      required:
        - batch_id
        - task_id
        - collection_id
        - total_tiers
        - message
      title: TriggerCollectionResponse
      description: >-
        Response after triggering collection processing.


        Use `batch_id` or `task_id` to monitor progress via GET
        /v1/batches/{batch_id}

        or GET /v1/tasks/{task_id}.
    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
    LogicalOperator-Input:
      properties:
        AND:
          anyOf:
            - items:
                anyOf:
                  - $ref: '#/components/schemas/LogicalOperator-Input'
                  - $ref: '#/components/schemas/FilterCondition'
              type: array
            - type: 'null'
          title: And
          description: Logical AND operation - all conditions must be true
          example:
            - field: name
              operator: eq
              value: John
            - field: age
              operator: gte
              value: 30
        OR:
          anyOf:
            - items:
                anyOf:
                  - $ref: '#/components/schemas/LogicalOperator-Input'
                  - $ref: '#/components/schemas/FilterCondition'
              type: array
            - type: 'null'
          title: Or
          description: Logical OR operation - at least one condition must be true
          example:
            - field: status
              operator: eq
              value: active
            - field: role
              operator: eq
              value: admin
        NOT:
          anyOf:
            - items:
                anyOf:
                  - $ref: '#/components/schemas/LogicalOperator-Input'
                  - $ref: '#/components/schemas/FilterCondition'
              type: array
            - type: 'null'
          title: Not
          description: Logical NOT operation - all conditions must be false
          example:
            - field: department
              operator: eq
              value: HR
            - field: location
              operator: eq
              value: remote
        case_sensitive:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Case Sensitive
          description: Whether to perform case-sensitive matching
          default: false
          example: true
      additionalProperties: true
      type: object
      title: LogicalOperator
      description: >-
        Represents a logical operation (AND, OR, NOT) on filter conditions.


        Allows nesting with a defined depth limit.


        Also supports shorthand syntax where field names can be passed directly

        as key-value pairs for equality filtering (e.g., {"metadata.title":
        "value"}).
    DedupStrategy:
      type: string
      enum:
        - skip
        - replace
        - force
      title: DedupStrategy
      description: |-
        Controls how duplicate objects are handled during batch processing.

        Dedup is scoped to (bucket_id, collection_id): an object is considered
        a duplicate if the target collection already has documents produced from
        the same source object in any prior batch.
    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
    FilterCondition:
      properties:
        field:
          type: string
          title: Field
          description: Field name to filter on
        operator:
          $ref: '#/components/schemas/FilterOperator'
          description: Comparison operator
          default: eq
        value:
          anyOf:
            - $ref: '#/components/schemas/DynamicValue'
            - {}
          title: Value
          description: Value to compare against
      type: object
      required:
        - field
        - value
      title: FilterCondition
      description: |-
        Represents a single filter condition.

        Attributes:
            field: The field to filter on
            operator: The comparison operator
            value: The value to compare against
    FilterOperator:
      description: Supported filter operators across database implementations.
      enum:
        - eq
        - ne
        - gt
        - lt
        - gte
        - lte
        - in
        - nin
        - contains
        - starts_with
        - ends_with
        - regex
        - exists
        - is_null
        - text
        - phrase
      title: FilterOperator
      type: string
    DynamicValue:
      description: A value that should be dynamically resolved from the query request.
      properties:
        type:
          type: string
          const: dynamic
          title: Type
          default: dynamic
        field:
          type: string
          title: Field
          description: >-
            The dot-notation path to the value in the runtime query request,
            e.g., 'inputs.user_id'
          examples:
            - inputs.query_text
            - filters.AND[0].value
      required:
        - field
      title: DynamicValue
      type: object

````