Skip to main content
POST
cURL

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

​
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: 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
​
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
​
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).