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.

POST /v1/alerts

Create Alert

cURL

curl --request POST \
  --url https://api.mixpeek.com/v1/alerts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Namespace: <api-key>' \
  --data '
{
  "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"
}
'

200

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

Authorizations

Authorization · string · header · required

Mixpeek API key, sent as Authorization: Bearer mxp_sk_.... Create one in Studio under Settings → API Keys, or with an admin key via POST /v1/organizations/users/{user_email}/api-keys. A missing, malformed, unknown, revoked, inactive or expired key returns 401; a key without the permission, scope or plan an operation needs returns 403.

X-Namespace · string · header · required

Namespace id (ns_...), not the namespace name. This scopes the request rather than authenticating it, and it is required on every operation marked x-mixpeek-namespace-scoped.

Body

application/json

Keys this body does not declare are refused with 422 extra_forbidden naming the accepted keys (since 2026-11-02).

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

Required string length: 1 - 200

Examples:

"Safety Incident Detector"

"Prohibited Content Alert"

notification_config · AlertNotificationConfig · object · required

How and where to send notifications when alert triggers

Show child attributes

Example:

{
  "channels": [
    {
      "channel_id": "wh_safety_team",
      "channel_type": "webhook"
    },
    {
      "channel_id": "sl_alerts",
      "channel_type": "slack"
    }
  ],
  "include_matches": true,
  "include_scores": true
}

description · string | null

Optional description of what this alert monitors

Maximum string length: 1000

Example:

"Alerts when new videos match known safety incidents"

source · enum<string> · default: retriever

Trigger source: 'retriever' (runs a retriever) or 'system' (built-in metric)

Available options: retriever, system

retriever_id · string | null

ID of the retriever to execute (source=retriever only). The retriever defines filters, scoring, limits.

Example:

"ret_safety_search"

trigger_on · enum<string> · default: results

source=retriever: fire on 'results' (narrowed by min_count and threshold when set) or 'no_results'

Available options: results, no_results

min_count · integer | null

With trigger_on='results': the fewest rows that fire the alert (default 1).

Required range: x >= 1

Example:

3

threshold · AlertThreshold · object | null

With trigger_on='results': fire only when the first result meets this comparison.

Show child attributes

inputs · Inputs · object

Retriever inputs the alert runs with. The sweep uses exactly these; at ingest, inputs mapped from the document override them.

Example:

{ "window_minutes": 60 }

cooldown_seconds · integer · default: 0

Suppress further fires for this many seconds after a fire. 0 means none.

Required range: 0 <= x <= 2592000

Example:

3600

renotify_interval_seconds · integer | null

While the condition stays true, notify again at this interval. Unset means once per rise.

Required range: 60 <= x <= 2592000

Example:

21600

system_condition · SystemCondition · object | null

Built-in data-plane condition to watch (source=system only)

Show child attributes

namespace_selector · NamespaceSelector · object | null

Org-level namespace scoping (all vs selected)

Show child attributes

enabled · boolean · default: true

Whether the alert is active and will execute

metadata · Metadata · object | null

Additional user-defined metadata for the alert

Response

200

application/json

Successful Response

Response model for a single alert.

name · string · required

Human-readable name for the alert

Required string length: 1 - 200

Examples:

"Safety Incident Detector"

"Prohibited Content Alert"

notification_config · AlertNotificationConfig · object · required

How and where to send notifications when alert triggers

Show child attributes

Example:

{
  "channels": [
    {
      "channel_id": "wh_safety_team",
      "channel_type": "webhook"
    },
    {
      "channel_id": "sl_alerts",
      "channel_type": "slack"
    }
  ],
  "include_matches": true,
  "include_scores": true
}

alert_id · string

Unique identifier for the alert

Example:

"alt_abc123xyz789"

namespace_id · string | null

Namespace this alert belongs to

Example:

"ns_production"

description · string | null

Optional description of what this alert monitors

Maximum string length: 1000

Example:

"Alerts when new videos match known safety incidents"

source · enum<string> · default: retriever

Trigger source: 'retriever' (runs a retriever) or 'system' (built-in metric)

Available options: retriever, system

retriever_id · string | null

ID of the retriever to execute (source=retriever only). The retriever defines filters, scoring, limits.

Example:

"ret_safety_search"

trigger_on · enum<string> · default: results

For source=retriever: fire on 'results' (matches found, narrowed by min_count and threshold when set) or 'no_results' (retriever went dark).

Available options: results, no_results

min_count · integer | null

With trigger_on='results': fire only when the retriever returns at least this many rows.

Required range: x >= 1

Example:

3

threshold · AlertThreshold · object | null

With trigger_on='results': fire only when the first result meets this comparison.

Show child attributes

inputs · Inputs · object

Retriever inputs this alert runs with. The sweep runs the retriever with exactly these, so a templated window such as {{time_ago(minutes=INPUT.window_minutes)}} keeps its window. At ingest, inputs mapped from the document override keys set here.

Example:

{ "window_minutes": 60 }

cooldown_seconds · integer · default: 0

After the alert fires, further fires within this many seconds are suppressed, on every path. 0 means no cooldown.

Required range: 0 <= x <= 2592000

Example:

3600

renotify_interval_seconds · integer | null

While the condition stays true, notify again at this interval. Unset means notify once per rise. Never fires inside cooldown_seconds.

Required range: 60 <= x <= 2592000

Example:

21600

last_fired_at · string<date-time> | null

When the alert last notified. Set by the platform; read-only.

system_condition · SystemCondition · object | null

Built-in data-plane condition to watch (source=system only)

Show child attributes

namespace_selector · NamespaceSelector · object | null

Org-level namespace scoping (all vs selected). When omitted, the alert is scoped to its own namespace_id.

Show child attributes

enabled · boolean · default: true

Whether the alert is active and will execute

created_at · string<date-time> | null

Timestamp when the alert was created

updated_at · string<date-time> | null

Timestamp when the alert was last updated

metadata · Metadata · object

Additional user-defined metadata for the alert