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

> Create a new alert that monitors document ingestion and sends notifications.

    Alerts attach retrievers to collections. When new documents are ingested,
    the alert runs the retriever and sends notifications if matches are found.

    **Key Components:**
    - `retriever_id`: References a retriever that defines query logic (filters, scoring, limits)
    - `notification_config`: Defines where to send notifications (webhook, Slack, email)

    **Note:** The retriever owns all query semantics. The alert's job is simply
    to run the retriever and notify if results exist.



## OpenAPI

````yaml post /v1/alerts
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/alerts:
    post:
      tags:
        - Alerts
      summary: Create Alert
      description: >-
        Create a new alert that monitors document ingestion and sends
        notifications.

            Alerts attach retrievers to collections. When new documents are ingested,
            the alert runs the retriever and sends notifications if matches are found.

            **Key Components:**
            - `retriever_id`: References a retriever that defines query logic (filters, scoring, limits)
            - `notification_config`: Defines where to send notifications (webhook, Slack, email)

            **Note:** The retriever owns all query semantics. The alert's job is simply
            to run the retriever and notify if results exist.
      operationId: create_alert_v1_alerts_post
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAlertRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlertResponse'
        '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:
    CreateAlertRequest:
      properties:
        name:
          type: string
          maxLength: 200
          minLength: 1
          title: Name
          description: Human-readable name for the alert
          examples:
            - Safety Incident Detector
            - Prohibited Content Alert
        description:
          anyOf:
            - type: string
              maxLength: 1000
            - type: 'null'
          title: Description
          description: Optional description of what this alert monitors
          examples:
            - Alerts when new videos match known safety incidents
        source:
          $ref: '#/components/schemas/AlertSource'
          description: >-
            Trigger source: 'retriever' (runs a retriever) or 'system' (built-in
            metric)
          default: retriever
        retriever_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Retriever Id
          description: >-
            ID of the retriever to execute (source=retriever only). The
            retriever defines filters, scoring, limits.
          examples:
            - ret_safety_search
            - ret_prohibited_content
        trigger_on:
          $ref: '#/components/schemas/TriggerOn'
          description: 'source=retriever: fire on ''results'' or ''no_results'''
          default: results
        system_condition:
          anyOf:
            - $ref: '#/components/schemas/SystemCondition'
            - type: 'null'
          description: Built-in data-plane condition to watch (source=system only)
        namespace_selector:
          anyOf:
            - $ref: '#/components/schemas/NamespaceSelector'
            - type: 'null'
          description: Org-level namespace scoping (all vs selected)
        notification_config:
          $ref: '#/components/schemas/AlertNotificationConfig'
          description: How and where to send notifications when alert triggers
        enabled:
          type: boolean
          title: Enabled
          description: Whether the alert is active and will execute
          default: true
        metadata:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Metadata
          description: Additional user-defined metadata for the alert
      type: object
      required:
        - name
        - notification_config
      title: CreateAlertRequest
      description: |-
        Request model to create an alert.

        Creates a new alert that can be attached to collections to monitor
        for matching content and send notifications when matches are found.

        Note: The alert references a retriever that contains all query logic
        (filters, min_score, limits, collection targeting). The alert's job
        is simply to run that retriever and notify if results exist.
      examples:
        - description: Alerts when new videos match known safety incidents
          enabled: true
          name: Safety Incident Detector
          notification_config:
            channels:
              - channel_id: wh_safety_team
                channel_type: webhook
            include_matches: true
            include_scores: true
          retriever_id: ret_safety_search
    AlertResponse:
      properties:
        alert_id:
          type: string
          title: Alert Id
          description: Unique identifier for the alert
          examples:
            - alt_abc123xyz789
        namespace_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Namespace Id
          description: Namespace this alert belongs to
          examples:
            - ns_production
            - ns_staging
        name:
          type: string
          maxLength: 200
          minLength: 1
          title: Name
          description: Human-readable name for the alert
          examples:
            - Safety Incident Detector
            - Prohibited Content Alert
        description:
          anyOf:
            - type: string
              maxLength: 1000
            - type: 'null'
          title: Description
          description: Optional description of what this alert monitors
          examples:
            - Alerts when new videos match known safety incidents
        source:
          $ref: '#/components/schemas/AlertSource'
          description: >-
            Trigger source: 'retriever' (runs a retriever) or 'system' (built-in
            metric)
          default: retriever
        retriever_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Retriever Id
          description: >-
            ID of the retriever to execute (source=retriever only). The
            retriever defines filters, scoring, limits.
          examples:
            - ret_safety_search
            - ret_prohibited_content
        trigger_on:
          $ref: '#/components/schemas/TriggerOn'
          description: >-
            For source=retriever: fire on 'results' (matches found) or
            'no_results' (retriever went dark).
          default: results
        system_condition:
          anyOf:
            - $ref: '#/components/schemas/SystemCondition'
            - type: 'null'
          description: Built-in data-plane condition to watch (source=system only)
        namespace_selector:
          anyOf:
            - $ref: '#/components/schemas/NamespaceSelector'
            - type: 'null'
          description: >-
            Org-level namespace scoping (all vs selected). When omitted, the
            alert is scoped to its own namespace_id.
        notification_config:
          $ref: '#/components/schemas/AlertNotificationConfig'
          description: How and where to send notifications when alert triggers
        enabled:
          type: boolean
          title: Enabled
          description: Whether the alert is active and will execute
          default: true
        created_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Created At
          description: Timestamp when the alert was created
        updated_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Updated At
          description: Timestamp when the alert was last updated
        metadata:
          additionalProperties: true
          type: object
          title: Metadata
          description: Additional user-defined metadata for the alert
      type: object
      required:
        - name
        - notification_config
      title: AlertResponse
      description: Response model for a single alert.
      examples:
        - alert_id: alt_safety_001
          description: Alerts when new videos match known safety incidents
          enabled: true
          name: Safety Incident Detector
          notification_config:
            channels:
              - channel_id: wh_safety_team
                channel_type: webhook
            include_matches: true
            include_scores: true
          retriever_id: ret_safety_search
    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
    AlertSource:
      type: string
      enum:
        - retriever
        - system
      title: AlertSource
      description: >-
        Where an alert's trigger decision comes from.


        Send the lowercase wire value (shown in quotes), NOT the member name.


        "retriever": runs a retriever against ingested data and fires on
        (no-)match.
                     "Does my data contain something?"
        "system":    evaluates a built-in data-plane metric against a threshold.
                     "Is my pipeline / data healthy?" No retriever involved.
    TriggerOn:
      type: string
      enum:
        - results
        - no_results
      title: TriggerOn
      description: >-
        For retriever-source alerts, which retriever outcome fires the alert.


        Send the lowercase wire value (shown in quotes), NOT the member name.


        "results":    fire when the retriever returns matches (the classic
        behavior).

        "no_results": fire when the retriever returns nothing — catches a
        retriever
                      that has silently gone dark (empty collection, broken pipeline).
    SystemCondition:
      properties:
        type:
          $ref: '#/components/schemas/SystemConditionType'
          description: Which built-in data-plane condition to evaluate
        params:
          additionalProperties: true
          type: object
          title: Params
          description: Per-condition threshold overrides (evaluator supplies defaults)
          examples:
            - stall_minutes: 30
            - error_rate_threshold: 0.1
      type: object
      required:
        - type
      title: SystemCondition
      description: >-
        A built-in data-plane condition for a system-source alert.


        The condition `type` selects which metric is evaluated; `params` carries

        per-type thresholds (e.g. ``stall_minutes``, ``latency_multiplier``,

        ``error_rate_threshold``, ``drop_fraction``). All params are optional
        and

        fall back to sensible defaults in the evaluator.


        Attributes:
            type: Which system condition to evaluate.
            params: Optional per-condition threshold overrides.
    NamespaceSelector:
      properties:
        mode:
          $ref: '#/components/schemas/NamespaceSelectorMode'
          description: Whether the alert applies to all namespaces or a selected set
          default: all
        namespace_ids:
          items:
            type: string
          type: array
          title: Namespace Ids
          description: Namespace IDs the alert applies to (when mode=selected)
          examples:
            - - ns_production
              - ns_staging
      type: object
      title: NamespaceSelector
      description: |-
        Selects which namespaces an org-level alert applies to.

        mode=all   → every namespace in the org (resolved at evaluation time).
        mode=selected → an explicit allow-list; must be non-empty.

        Attributes:
            mode: ``all`` or ``selected``.
            namespace_ids: Allow-list used when mode=selected.
    AlertNotificationConfig:
      properties:
        channels:
          items:
            $ref: '#/components/schemas/NotificationChannelConfig'
          type: array
          minItems: 1
          title: Channels
          description: List of notification channels to send alerts to
        include_matches:
          type: boolean
          title: Include Matches
          description: Include matched documents in notification payload
          default: true
        include_scores:
          type: boolean
          title: Include Scores
          description: Include similarity scores in notification payload
          default: true
        template_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Template Id
          description: Optional notification template for formatting
      type: object
      required:
        - channels
      title: AlertNotificationConfig
      description: |-
        How and where to send notifications when an alert is triggered.

        Defines the notification channels and what information to include
        in the notification payload.

        Attributes:
            channels: List of channels to send notifications to
            include_matches: Whether to include matched documents in the payload
            include_scores: Whether to include similarity scores in the payload
            template_id: Optional template for formatting the notification
      examples:
        - channels:
            - channel_id: wh_safety_team
              channel_type: webhook
            - channel_id: sl_alerts
              channel_type: slack
          include_matches: true
          include_scores: true
    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
    SystemConditionType:
      type: string
      enum:
        - collection_empty
        - batch_failed
        - batch_stalled
        - retriever_latency
        - retriever_no_results
        - batch_error_rate
        - collection_drift
        - retriever_accuracy
        - retriever_alignment_regression
      title: SystemConditionType
      description: Built-in data-plane conditions a system-source alert can watch.
    NamespaceSelectorMode:
      type: string
      enum:
        - all
        - selected
      title: NamespaceSelectorMode
      description: How an org-level alert chooses which namespaces it applies to.
    NotificationChannelConfig:
      properties:
        channel_type:
          type: string
          title: Channel Type
          description: 'Type of notification channel: ''webhook'', ''slack'', ''email'''
          examples:
            - webhook
            - slack
            - email
        channel_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Channel Id
          description: >-
            Reference to a pre-configured notification channel in the
            organization
          examples:
            - wh_safety_team
            - sl_alerts
            - em_security
        config:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Config
          description: >-
            Channel-specific configuration overrides (e.g., webhook URL, Slack
            channel)
          examples:
            - url: https://example.com/webhook
            - channel: '#alerts'
            - to:
                - admin@example.com
      type: object
      required:
        - channel_type
      title: NotificationChannelConfig
      description: |-
        Configuration for a notification channel.

        Channels define where notifications are sent when an alert is triggered.
        Supports multiple channel types including webhooks, Slack, and email.

        Attributes:
            channel_type: Type of notification channel (webhook, slack, email)
            channel_id: Optional reference to a pre-configured channel in the organization
            config: Optional channel-specific configuration overrides

````