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}"{
"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": "jsmith@example.com",
"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"
],
"speaker_statement_characteristics": {
"certainty": "confident",
"sentiment": "positive",
"specificity": "specific",
"temporal_orientation": "future"
}
},
"keyword": "<string>"
}{
"detail": "Property foo is required but is missing.",
"error_code": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
],
"instance": "https://example.com/error-log/abc123",
"resolve": {
"message": "<string>",
"action": "<string>",
"endpoint": "<string>",
"method": "<string>",
"url": "<string>"
},
"status": 400,
"title": "Bad Request",
"type": "https://example.com/errors/example"
}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.
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}"{
"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": "jsmith@example.com",
"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"
],
"speaker_statement_characteristics": {
"certainty": "confident",
"sentiment": "positive",
"specificity": "specific",
"temporal_orientation": "future"
}
},
"keyword": "<string>"
}{
"detail": "Property foo is required but is missing.",
"error_code": "<string>",
"errors": [
{
"location": "<string>",
"message": "<string>",
"value": "<unknown>"
}
],
"instance": "https://example.com/error-log/abc123",
"resolve": {
"message": "<string>",
"action": "<string>",
"endpoint": "<string>",
"method": "<string>",
"url": "<string>"
},
"status": 400,
"title": "Bad Request",
"type": "https://example.com/errors/example"
}Authorizations
Pass your API key in the X-API-Key header (recommended).
Path Parameters
Alert ID
Body
REALTIME, DAILY, WEEKLY 2000Replacement 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.
1 elementShow child attributes
Show child attributes
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
Show child attributes
Toggle whether the alert produces matches. False pauses; true resumes.
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.
1001 - 20 elementsShow child attributes
Show child attributes
1 - 200Response
OK
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.
Show child attributes
Show child attributes
Whether the alert produces matches. Disabled alerts retain history but accumulate no new matches until re-enabled.
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.
ENTITY_MENTION, PODCAST_SPEAKER, KEYWORD_MENTION Show child attributes
Show child attributes
User who created the alert. Null when the alert was created via an API key.
Show child attributes
Show child attributes
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
Show child attributes
KEYWORD_MENTION alerts only: the phrase the alert watches (see the create request's keyword for how it matches). Absent on entity alerts.
Was this page helpful?