Alerts
tier:standard

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}

Request

  • Base URL: https://api.particle.pro
  • URL: https://api.particle.pro/v1/alerts/{id}
  • Auth: one of:
    • API key in header X-API-Key
    • HTTP bearer

Path parameters

idstring required

Alert ID

Request body

delivery_cadence'REALTIME' | 'DAILY' | 'WEEKLY'
descriptionstring
is_activeboolean

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

keywordstring

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.

titlestring

Response

OK

created_atstring date-time required
delivery_cadencestring 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.

descriptionstring
idstring required
is_activeboolean required

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

keywordstring

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

kind'ENTITY_MENTION' | 'PODCAST_SPEAKER' | 'KEYWORD_MENTION' 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.

project_idstring required
titlestring required
updated_atstring date-time required

Changes

No recorded changes to this operation across all 2 revisions of this API.