---
title: "Update Alert"
method: PATCH
path: "/v1/alerts/{alert_identifier}"
tags: ["Alerts"]
---

# Update Alert

`PATCH /v1/alerts/{alert_identifier}`

Partially update an alert's configuration.

    **All fields are optional** - provide only what you want to update.

    Unlike taxonomies, alerts can be fully updated including:
    - `name`: Rename the alert
    - `description`: Update documentation
    - `retriever_id`: Change the retriever
    - `notification_config`: Update notification channels
    - `enabled`: Enable/disable the alert
    - `metadata`: Update custom metadata

## Path parameters

- `alert_identifier` string, required — Alert ID (alt_...) or name

## Request body

- PatchAlertRequest — Request model to update an alert. All fields are optional - provide only what you want to update. Core fields (retriever_id, notification_config) can be updated since alerts don't have join history like taxonomies.
  - `name` string, nullable — Updated name for the alert
  - `description` string, nullable — Updated description for the alert
  - `retriever_id` string, nullable — Updated retriever ID (source=retriever only)
  - `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 — 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, nullable — Updated enabled status
  - `metadata` object, nullable — Updated metadata

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