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.

POST /v1/projects/{projectId}/alerts

cURL

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"

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"
    ]
  }
}

Authorizations

ApiKeyHeaderBearerAuth

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

The entity to watch — exactly one; an alert watches a single entity, so create a separate alert per entity. v1 matches across podcast episodes only.

Required array length: 1 element

Show child attributes

notifications · object[] | null · required

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.

Required array length: 1 - 20 elements

Show child attributes

title · string · required

Human-readable title

Required string length: 1 - 200

delivery_cadence · enum<string>

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.

Available options: REALTIME, DAILY, WEEKLY

description · string

Maximum string length: 2000

filters · object

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

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

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

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