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.

POST /v1/projects/{projectId}/alerts

cURL

cURL

curl -X POST \
  -H "X-API-Key: $PARTICLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "entities": [
    {
      "entity_id": "3CensCwu5G2oKCFgPrNf89",
      "entity_type": "COMPANY"
    }
  ],
  "notifications": [
    {
      "email": "[e-mail]",
      "type": "EMAIL"
    }
  ],
  "title": "Nvidia mentions on podcasts"
}' \
  "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"
    ]
  },
  "keyword": "<string>"
}

Prefer the terminal? This endpoint is also a command in the Particle CLI: pick Particle CLI in the request example’s language menu. Install the Particle CLI.

Authorizations

ApiKeyHeaderBearerAuth

X-API-Key · string · header · required

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

Headers

Idempotency-Key · string

A key you choose, such as a UUID, to retry this request safely. Resend the same key with the same request and the first response is returned with Idempotent-Replayed: true instead of the request running again, for 24 hours after it succeeded. The same key with a different request returns 422 idempotency_key_reused; a retry while the first request is still running returns 409 idempotency_key_in_use. A request that fails does not use up its key.

Required string length: 8 - 128

Path Parameters

projectId · string · required

Project ID.

Body

application/json

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

entities · object[] | null

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

Required array length: 1 element

Show child attributes

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.

keyword · string

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.

Maximum string length: 100

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 alert's speaker roles: by default GUEST, PANELIST, CORRESPONDENT, AUDIENCE, and SOUNDBITE_SPEAKER (an excerpted clip of them played on the episode); raw STT/LLM labels like CALLER, LISTENER, REPORTER are normalized into these buckets on write. HOST is excluded by default because hosting the show isn't an appearance. speaker_roles replaces the default set. 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.

Available options: ENTITY_MENTION, PODCAST_SPEAKER, KEYWORD_MENTION

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

Available options: ENTITY_MENTION, PODCAST_SPEAKER, KEYWORD_MENTION

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

keyword · string

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