Sign in
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": 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

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

Changed in 2 of the 28 revisions of this API.34

  • 5d4c905106b41See the full diff
    • ○

      the endpoint scheme security BearerAuth AND NamespaceHeader was added to the API

      api-security-added

    This revision also has 3 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 7cb05153331133See the full diff
    • ●

      added the new dlq_growth enum value to the system_condition/anyOf[subschema #1: SystemCondition]/type response property for the response status 200

      response-property-enum-value-added

    • ●

      added the new provider_quota_exhausted enum value to the system_condition/anyOf[subschema #1: SystemCondition]/type response property for the response status 200

      response-property-enum-value-added

    • ●

      added the new task_queue_degraded enum value to the system_condition/anyOf[subschema #1: SystemCondition]/type response property for the response status 200

      response-property-enum-value-added

    • ○

      added the new dlq_growth enum value to the request property system_condition/anyOf[subschema #1: SystemCondition]/type

      request-property-enum-value-added

    • ○

      added the new provider_quota_exhausted enum value to the request property system_condition/anyOf[subschema #1: SystemCondition]/type

      request-property-enum-value-added

    • ○

      added the new task_queue_degraded enum value to the request property system_condition/anyOf[subschema #1: SystemCondition]/type

      request-property-enum-value-added

    This revision also has 1 change that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog