Skip to main content
POST
/
v1
/
projects
/
{projectId}
/
alerts
cURL
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>",
      "image_url": "<string>",
      "name": "<string>"
    }
  ],
  "id": "<string>",
  "is_active": true,
  "notifications": [
    {
      "type": "EMAIL",
      "email": "jsmith@example.com",
      "id": "<string>"
    }
  ],
  "project_id": "<string>",
  "title": "<string>",
  "updated_at": "2023-11-07T05:31:56Z",
  "created_by": {
    "id": "<string>",
    "name": "<string>"
  },
  "description": "<string>"
}

Authorizations

​
X-API-Key
string
header
required

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

Path Parameters

​
projectId
string
required

Project ID.

Body

application/json
​
entities
object[] | null
required

Entities to watch. v1 matches across podcast episodes only.

Required array length: 1 - 100 elements
​
notifications
object[] | null
required

Delivery channels for match notifications. v1 supports EMAIL only; one or more EMAIL entries are required.

Required array length: 1 - 20 elements
​
title
string
required

Human-readable title

Required string length: 1 - 200
​
delivery_cadence
enum<string>

How often matches are delivered to all configured channels. Defaults to REALTIME. v1 only emits REALTIME; DAILY/WEEKLY are accepted but treated as REALTIME until the digest worker ships.

Available options:
REALTIME,
DAILY,
WEEKLY
​
description
string
Maximum string length: 2000
​
is_active
boolean

Whether the alert produces matches. Defaults to true. Disabling stops new matches without losing the alert — re-enable to resume.

​
kind
enum<string>

What 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.

Available options:
ENTITY_MENTION,
PODCAST_SPEAKER

Response

OK

​
created_at
string<date-time>
required
​
delivery_cadence
string
required

How often matches are delivered to all configured channels: REALTIME (per-match), DAILY, or WEEKLY. v1 only emits REALTIME; DAILY/WEEKLY are accepted but treated as REALTIME until the digest worker ships.

​
entities
object[] | null
required
​
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 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. Kind is fixed at creation.

Available options:
ENTITY_MENTION,
PODCAST_SPEAKER
​
notifications
object[] | null
required
​
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.

​
description
string