v5

latestOpenAPI 3.1.02026-08-025631,1012.8 MB

Alerts

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

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

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_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.

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