Update an alert

Partially update an alert. Provided fields replace existing values; the entities list, when provided, replaces the watched entity (exactly one). Alerts are not covered by zero data retention: the alert’s definition and its matched results are stored as part of the alerts feature.

PATCH /v1/alerts/{id}

cURL

cURL

curl -X PATCH \
  -H "X-API-Key: $PARTICLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "delivery_cadence": "DAILY"
}' \
  "https://api.particle.pro/v1/alerts/{id}"

200

{
  "created_at": "2023-11-07T05:31:56Z",
  "delivery_cadence": "<string>",
  "entities": [
    {
      "entity_id": "<string>",
      "entity_type": "PERSON",
      "image_url": "<string>",
      "name": "<string>"
    }
  ],
  "id": "<string>",
  "is_active": true,
  "kind": "ENTITY_MENTION",
  "notifications": [
    {
      "type": "EMAIL",
      "created_by": {
        "id": "<string>",
        "name": "<string>"
      },
      "email": "[e-mail]",
      "id": "<string>",
      "slack_channel_id": "<string>",
      "slack_channel_name": "<string>",
      "slack_connection_id": "<string>",
      "webhook_connection_id": "<string>"
    }
  ],
  "project_id": "<string>",
  "title": "<string>",
  "updated_at": "2023-11-07T05:31:56Z",
  "created_by": {
    "id": "<string>",
    "name": "<string>"
  },
  "description": "<string>",
  "filters": {
    "languages": [
      "<string>"
    ],
    "relevance": "EVERYTHING",
    "source_popularity": "ANY",
    "speaker_roles": [
      "HOST"
    ]
  },
  "keyword": "<string>"
}

Prefer the terminal? This endpoint is also a command in the Particle CLI: pick Particle CLI in the request example’s language menu. Install the Particle CLI.

Authorizations

ApiKeyHeaderBearerAuth

X-API-Key · string · header · required

Pass your API key in the X-API-Key header (recommended).

Path Parameters

id · string · required

Alert ID

Body

application/json

delivery_cadence · enum<string>

Available options: REALTIME, DAILY, WEEKLY

description · string

Maximum string length: 2000

entities · object[]

Replacement watch target for ENTITY_MENTION and PODCAST_SPEAKER alerts — exactly one entity. Alerts created before the one-entity rule keep their multi-entity watch list until this field is next written. Rejected on KEYWORD_MENTION alerts.

Required array length: 1 element

Show child attributes

filters · object

Replace the alert's filter set wholesale. Omit to leave the existing filters unchanged; send an empty object {} to clear all filters.

Show child attributes

is_active · boolean

Toggle whether the alert produces matches. False pauses; true resumes.

keyword · string

Replacement phrase for KEYWORD_MENTION alerts. Rejected on other kinds, and when too broad (see create). Matches already recorded keep the phrase they fired on.

Maximum string length: 100

notifications · object[]

Required array length: 1 - 20 elements

Show child attributes

title · string

Required string length: 1 - 200

Response

200

application/json

OK

created_at · string<date-time> · required

delivery_cadence · string · required

How often matches are delivered: REALTIME (a separate email per match), DAILY (one bundled email each morning at 13:00 UTC), or WEEKLY (one bundled email Monday 13:00 UTC). Defaults to REALTIME.

entities · object[] | null · required

Show child attributes

id · string · required

is_active · boolean · required

Whether the alert produces matches. Disabled alerts retain history but accumulate no new matches until re-enabled.

kind · enum<string> · required

What signal the alert watches for. ENTITY_MENTION fires whenever a watched entity is mentioned in a podcast episode. PODCAST_SPEAKER fires only when a watched entity is themself an identified speaker on the episode, in one of the alert's speaker roles. By default those are GUEST, PANELIST, CORRESPONDENT, AUDIENCE (which absorbs callers, listeners, and other audience-side roles after server-side canonicalization), and SOUNDBITE_SPEAKER (an excerpted clip of them played on the episode); HOST is excluded by default because hosting the show isn't an appearance. speaker_roles replaces the default set. KEYWORD_MENTION fires whenever the alert's keyword is spoken in a podcast episode, for names the entity resolvers don't know; it watches a keyword instead of entities. Kind is fixed at creation.

Available options: ENTITY_MENTION, PODCAST_SPEAKER, KEYWORD_MENTION

notifications · object[] | null · required

Show child attributes

project_id · string · required

title · string · required

updated_at · string<date-time> · required

created_by · object

User who created the alert. Null when the alert was created via an API key.

Show child attributes

description · string

filters · object

Persistent narrowing applied to every surface the alert produces: the matches list, the realtime email, and the daily/weekly digest. Absent = no filters (every detected match is surfaced).

Show child attributes

keyword · string

KEYWORD_MENTION alerts only: the phrase the alert watches (see the create request's keyword for how it matches). Absent on entity alerts.