---
title: "Create Alert"
method: POST
path: "/v1/alerts"
tags: ["Alerts"]
---

# Create Alert

`POST /v1/alerts`

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.

## Request body

- CreateAlertRequest — 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.
  - `name` string, required — Human-readable name for the alert
  - `description` string, nullable — Optional description of what this alert monitors
  - `source` 'retriever' | 'system' — 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.
  - `retriever_id` string, nullable — ID of the retriever to execute (source=retriever only). The retriever defines filters, scoring, limits.
  - `trigger_on` 'results' | 'no_results' — 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).
  - `system_condition` SystemCondition — 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.
    - `type` 'collection_empty' | 'batch_failed' | 'batch_stalled' | 'retriever_latency' | 'retriever_no_results' | 'batch_error_rate' | 'collection_drift' | 'retriever_accuracy' | 'retriever_alignment_regression' | 'task_queue_degraded' | 'dlq_growth' | 'provider_quota_exhausted', required — Built-in data-plane conditions a system-source alert can watch.
    - `params` object — Per-condition threshold overrides (evaluator supplies defaults)
  - `namespace_selector` NamespaceSelector — 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.
    - `mode` 'all' | 'selected' — How an org-level alert chooses which namespaces it applies to.
    - `namespace_ids` string[] — Namespace IDs the alert applies to (when mode=selected)
  - `notification_config` AlertNotificationConfig, required — 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
    - `channels` NotificationChannelConfig[], required — List of notification channels to send alerts to
      - `channel_type` string, required — Type of notification channel: 'webhook', 'slack', 'email'
      - `channel_id` string, nullable — Reference to a pre-configured notification channel in the organization
      - `config` object, nullable — Channel-specific configuration overrides (e.g., webhook URL, Slack channel)
    - `include_matches` boolean — Include matched documents in notification payload
    - `include_scores` boolean — Include similarity scores in notification payload
    - `template_id` string, nullable — Optional notification template for formatting
  - `enabled` boolean — Whether the alert is active and will execute
  - `metadata` object, nullable — Additional user-defined metadata for the alert

## Response `200`

Successful Response

- AlertResponse — Response model for a single alert.
  - `alert_id` string — Unique identifier for the alert
  - `namespace_id` string, nullable — Namespace this alert belongs to
  - `name` string, required — Human-readable name for the alert
  - `description` string, nullable — Optional description of what this alert monitors
  - `source` 'retriever' | 'system' — 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.
  - `retriever_id` string, nullable — ID of the retriever to execute (source=retriever only). The retriever defines filters, scoring, limits.
  - `trigger_on` 'results' | 'no_results' — 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).
  - `system_condition` SystemCondition — 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.
    - `type` 'collection_empty' | 'batch_failed' | 'batch_stalled' | 'retriever_latency' | 'retriever_no_results' | 'batch_error_rate' | 'collection_drift' | 'retriever_accuracy' | 'retriever_alignment_regression' | 'task_queue_degraded' | 'dlq_growth' | 'provider_quota_exhausted', required — Built-in data-plane conditions a system-source alert can watch.
    - `params` object — Per-condition threshold overrides (evaluator supplies defaults)
  - `namespace_selector` NamespaceSelector — 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.
    - `mode` 'all' | 'selected' — How an org-level alert chooses which namespaces it applies to.
    - `namespace_ids` string[] — Namespace IDs the alert applies to (when mode=selected)
  - `notification_config` AlertNotificationConfig, required — 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
    - `channels` NotificationChannelConfig[], required — List of notification channels to send alerts to
      - `channel_type` string, required — Type of notification channel: 'webhook', 'slack', 'email'
      - `channel_id` string, nullable — Reference to a pre-configured notification channel in the organization
      - `config` object, nullable — Channel-specific configuration overrides (e.g., webhook URL, Slack channel)
    - `include_matches` boolean — Include matched documents in notification payload
    - `include_scores` boolean — Include similarity scores in notification payload
    - `template_id` string, nullable — Optional notification template for formatting
  - `enabled` boolean — Whether the alert is active and will execute
  - `created_at` string, date-time, nullable — Timestamp when the alert was created
  - `updated_at` string, date-time, nullable — Timestamp when the alert was last updated
  - `metadata` object — Additional user-defined metadata for the alert

## 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/04b379bdbb7c/schema)