curl -X POST \
-H "X-API-Key: $PARTICLE_API_KEY" \
-H "Content-Type: application/json" \
-d '{}' \
"https://api.particle.pro/v1/projects/{projectId}/alerts"{
"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"
]
},
"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"
}Create an alert
Create an alert that watches a single entity and emails the configured address whenever the entity is mentioned on a podcast episode. To cover several entities, create one alert per entity. 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 POST \
-H "X-API-Key: $PARTICLE_API_KEY" \
-H "Content-Type: application/json" \
-d '{}' \
"https://api.particle.pro/v1/projects/{projectId}/alerts"{
"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"
]
},
"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
Project ID.
Body
Delivery channels for match notifications. Mix of EMAIL and SLACK destinations is allowed. SLACK destinations require a previously-installed Slack workspace connection (see POST /v1/projects/{projectId}/slack/connections/initiate) and a channel id from the connection's channel listing.
1 - 20 elementsShow child attributes
Show child attributes
Human-readable title
1 - 200How 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.
REALTIME, DAILY, WEEKLY 2000The entity to watch — exactly one for ENTITY_MENTION and PODCAST_SPEAKER alerts; an alert watches a single entity, so create a separate alert per entity. Omit for KEYWORD_MENTION alerts. v1 matches across podcast episodes only.
1 elementShow child attributes
Show child attributes
Persistent narrowing applied to every surface the alert produces (matches list, realtime email, digest). Omit (or send an empty object) for no filters.
Show child attributes
Show child attributes
Whether the alert produces matches. Defaults to true. Disabling stops new matches without losing the alert — re-enable to resume.
KEYWORD_MENTION alerts only, and required for them: the phrase to watch, e.g. Lightfield. It matches the way a double-quoted keyword search phrase does — the words adjacent and in order, ignoring case and punctuation, on whole words — within topic-discussion and interview segments, never in ad reads, intros, or outros. Set description to say what the phrase means (e.g. 'Lightfield, the AI-native CRM') — it is how same-name mentions of something else get filtered out. A phrase that matched more than 700 podcast episodes in the past week is rejected as too broad.
100What signal the alert watches for. Defaults to ENTITY_MENTION (fires on any mention of a watched entity). PODCAST_SPEAKER fires only when a watched entity is themself an identified speaker on the episode, in one of the canonical appearance buckets — GUEST, PANELIST, CORRESPONDENT, or AUDIENCE (raw STT/LLM labels like CALLER, LISTENER, REPORTER are normalized into these buckets on write). HOST is excluded — hosting the show isn't an appearance. KEYWORD_MENTION fires whenever the keyword is spoken in a podcast episode — use it for brands, products, or terms the entity resolvers don't know; it takes keyword instead of entities.
ENTITY_MENTION, PODCAST_SPEAKER, KEYWORD_MENTION Response
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 canonical appearance buckets — GUEST, PANELIST, CORRESPONDENT, or AUDIENCE (this last bucket absorbs callers, listeners, and other audience-side roles after server-side canonicalization). HOST is intentionally excluded — hosting the show isn't an appearance. 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?