Alerts

Update Org-Scoped Alert

Changed on

Partially update an org-scoped alert (e.g. enable/disable, channels).

patch/v1/organizations/alerts/{alert_identifier}

Request

  • Base URL: https://api.mixpeek.com
  • URL: https://api.mixpeek.com/v1/organizations/alerts/{alert_identifier}
  • Auth: HTTP bearer

Path parameters

alert_identifierstring required

Alert ID (alt_...) or name

Request body

namestring nullable

Updated name for the alert

descriptionstring nullable

Updated description for the alert

retriever_idstring 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).

"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

Updated min_count (trigger_on='results')

inputsobject nullable

Updated retriever inputs (replaces the whole set)

cooldown_secondsinteger nullable

Updated cooldown in seconds. 0 removes the cooldown.

renotify_interval_secondsinteger nullable

Updated re-notify interval in seconds

enabledboolean nullable

Updated enabled status

metadataobject nullable

Updated metadata

Example request

{
  "threshold": {
    "field": "score",
    "value": 0.9
  },
  "system_condition": {
    "params": {
      "stall_minutes": 30
    }
  },
  "namespace_selector": {
    "namespace_ids": [
      "ns_production",
      "ns_staging"
    ]
  },
  "notification_config": {
    "channels": [
      {
        "channel_id": "wh_safety_team",
        "channel_type": "webhook"
      },
      {
        "channel_id": "sl_alerts",
        "channel_type": "slack"
      }
    ],
    "include_matches": true,
    "include_scores": true
  }
}

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 //