Create Org-Scoped Alert

Create an organization-level alert that applies across namespaces via its namespace_selector (all or a selected set). Use this for system alerts (collection/batch/retriever health) that should cover the whole org rather than a single namespace.

POST /v1/organizations/alerts

Create Org-Scoped Alert

cURL

curl --request POST \
  --url https://api.mixpeek.com/v1/organizations/alerts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --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 header returns 403; an invalid or revoked key returns 401.

Body

application/json

Keys this body does not declare are ignored, and the response's warnings name them, until 2026-11-02; from 2026-11-02 they are refused with 422 extra_forbidden naming the accepted keys.

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