Alerts

Create Alert

Changed on

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

Request

  • Base URL: https://api.mixpeek.com
  • URL: https://api.mixpeek.com/v1/alerts
  • Auth: HTTP bearer and API key in header X-Namespace

Request body

namestring required

Human-readable name for the alert

descriptionstring 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_idstring 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).

"results" can be narrowed by two alert fields: min_count (at least that many rows) and threshold (a field of the FIRST result meets a comparison, for example score >= 0.9 or an aggregate's count > 100). They are fields rather than further values here so that a release which predates them still reads the alert, as a plain "results" alert.

min_countinteger nullable

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

inputsobject

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

cooldown_secondsinteger

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

renotify_interval_secondsinteger nullable

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

enabledboolean

Whether the alert is active and will execute

metadataobject nullable

Additional user-defined metadata for the alert

Example request

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

Response

Successful Response

alert_idstring

Unique identifier for the alert

namespace_idstring nullable

Namespace this alert belongs to

namestring required

Human-readable name for the alert

descriptionstring 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_idstring 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).

"results" can be narrowed by two alert fields: min_count (at least that many rows) and threshold (a field of the FIRST result meets a comparison, for example score >= 0.9 or an aggregate's count > 100). They are fields rather than further values here so that a release which predates them still reads the alert, as a plain "results" alert.

min_countinteger nullable

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

inputsobject

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.

cooldown_secondsinteger

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

renotify_interval_secondsinteger nullable

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

last_fired_atstring date-time nullable

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

enabledboolean

Whether the alert is active and will execute

created_atstring date-time nullable

Timestamp when the alert was created

updated_atstring date-time nullable

Timestamp when the alert was last updated

metadataobject

Additional user-defined metadata for the alert

Example response

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

Changes

  • 61a175e8eb9aRevision changes
    • warning

      removed the optional property from the response with the status

    • warning

      added the new ingest_stalled enum value to the // response property for the response status

    • info

      added the new ingest_stalled enum value to the request property //

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the optional property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

  • b75474e978ffRevision changes
    • warning

      added the new budget_threshold enum value to the // response property for the response status

    • warning

      added the new collection_stale enum value to the // response property for the response status

    • warning

      added the new retriever_no_interactions enum value to the // response property for the response status

    • info

      added the new budget_threshold enum value to the request property //

    • info

      added the new collection_stale enum value to the request property //

    • info

      added the new retriever_no_interactions enum value to the request property //