{ "components": { "schemas": { "AdDetail": { "additionalProperties": false, "properties": { "company": { "$ref": "#/components/schemas/CompanyCompact", "description": "Linked company record" }, "created_at": { "description": "When the ad was first detected", "format": "date-time", "type": "string" }, "duration_seconds": { "description": "Ad duration in seconds", "format": "double", "type": "number" }, "end_seconds": { "description": "Ad end offset within the episode, in seconds", "format": "double", "type": "number" }, "id": { "description": "Unique identifier", "type": "string" }, "offer_description": { "description": "Promotional offer details", "type": "string" }, "placement_type": { "description": "Where the ad appeared in the episode (PRE_ROLL, MID_ROLL, POST_ROLL)", "type": "string" }, "podcast": { "$ref": "#/components/schemas/PodcastCompact", "description": "Podcast where the ad appeared" }, "product": { "description": "Advertised product or service", "type": "string" }, "read_type": { "description": "How the ad was delivered (HOST_READ, PRE_RECORDED)", "type": "string" }, "sponsor_id": { "description": "Linked sponsor ID, when known. Works as the {id} of /v1/podcasts/advertising/sponsors/{id} and its sub-resources, including when the ad has no linked company.", "type": "string" }, "sponsor_name": { "description": "Name of the advertising sponsor", "type": "string" }, "sponsor_url": { "description": "Sponsor website URL", "type": "string" }, "start_seconds": { "description": "Ad start offset within the episode, in seconds", "format": "double", "type": "number" } }, "required": [ "id", "sponsor_name", "read_type", "start_seconds", "end_seconds", "duration_seconds", "created_at" ], "type": "object" }, "AdvertisingTimeseries": { "additionalProperties": false, "properties": { "buckets": { "description": "Contiguous zero-filled buckets in ascending order", "items": { "$ref": "#/components/schemas/AdvertisingTimeseriesBucket" }, "type": [ "array", "null" ] }, "distinct_episodes": { "description": "Distinct episodes those placements aired in", "format": "int64", "type": "integer" }, "distinct_podcasts": { "description": "Distinct podcasts those placements aired on", "format": "int64", "type": "integer" }, "end": { "description": "UTC date of the range's exclusive upper bound. When the bound falls inside a day, such as the default of now, ads on this date up to the bound are still counted.", "type": "string" }, "host_read_count": { "description": "Host-read placements in the range", "format": "int64", "type": "integer" }, "interval": { "description": "Bucket width", "enum": [ "day", "week", "month" ], "type": "string" }, "pre_recorded_count": { "description": "Placements not read by the host in the range", "format": "int64", "type": "integer" }, "start": { "description": "Start of the first bucket as a UTC date", "type": "string" }, "total_ads": { "description": "Ad placements matching the filters in the range", "format": "int64", "type": "integer" } }, "required": [ "interval", "total_ads", "host_read_count", "pre_recorded_count", "distinct_episodes", "distinct_podcasts", "buckets" ], "type": "object" }, "AdvertisingTimeseriesBucket": { "additionalProperties": false, "properties": { "count": { "description": "Ad placements in this bucket", "format": "int64", "type": "integer" }, "host_read_count": { "description": "Host-read placements in this bucket", "format": "int64", "type": "integer" }, "pre_recorded_count": { "description": "Placements not read by the host in this bucket", "format": "int64", "type": "integer" }, "start": { "description": "Bucket start as a UTC date", "type": "string" } }, "required": [ "start", "count", "host_read_count", "pre_recorded_count" ], "type": "object" }, "Alert": { "additionalProperties": false, "properties": { "created_at": { "format": "date-time", "type": "string" }, "created_by": { "$ref": "#/components/schemas/Creator", "description": "User who created the alert. Null when the alert was created via an API key." }, "delivery_cadence": { "description": "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.", "type": "string" }, "description": { "type": "string" }, "entities": { "items": { "$ref": "#/components/schemas/AlertEntity" }, "type": [ "array", "null" ] }, "filters": { "$ref": "#/components/schemas/AlertFilters", "description": "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)." }, "id": { "type": "string" }, "is_active": { "description": "Whether the alert produces matches. Disabled alerts retain history but accumulate no new matches until re-enabled.", "type": "boolean" }, "keyword": { "description": "KEYWORD_MENTION alerts only: the phrase the alert watches (see the create request's keyword for how it matches). Absent on entity alerts.", "type": "string" }, "kind": { "description": "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.", "enum": [ "ENTITY_MENTION", "PODCAST_SPEAKER", "KEYWORD_MENTION" ], "type": "string" }, "notifications": { "items": { "$ref": "#/components/schemas/AlertNotificationChannel" }, "type": [ "array", "null" ] }, "project_id": { "type": "string" }, "title": { "type": "string" }, "updated_at": { "format": "date-time", "type": "string" } }, "required": [ "id", "project_id", "title", "kind", "delivery_cadence", "is_active", "entities", "notifications", "created_at", "updated_at" ], "type": "object" }, "AlertDelivery": { "additionalProperties": false, "properties": { "alert_id": { "description": "ID of the parent alert.", "type": "string" }, "channel": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "error_message": { "type": "string" }, "id": { "type": "string" }, "match_count": { "format": "int64", "type": "integer" }, "matches": { "items": { "$ref": "#/components/schemas/AlertMatchSummary" }, "type": [ "array", "null" ] }, "monitor_id": { "description": "Deprecated — use alert_id. ID of the parent alert.", "type": "string" }, "sent_at": { "format": "date-time", "type": "string" }, "status": { "description": "Delivery outcome — SENT (delivered; a partial success keeps this status with the failure noted in error_message), FAILED (an attempt failed; realtime retries within its budget and digests re-select within their window), SKIPPED (intentionally not delivered), or ABANDONED (realtime webhook delivery permanently gave up after exhausting its retry budget, so the match was dropped for that channel).", "type": "string" } }, "required": [ "id", "monitor_id", "alert_id", "channel", "status", "match_count", "created_at", "matches" ], "type": "object" }, "AlertDeliveryDetail": { "additionalProperties": false, "properties": { "alert": { "$ref": "#/components/schemas/AlertRef", "description": "Lightweight reference to the parent alert. Lets the FE render a delivery landing page without a second GET /v1/alerts/{id} call." }, "alert_id": { "description": "ID of the parent alert.", "type": "string" }, "channel": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "error_message": { "type": "string" }, "has_webhook_payload": { "description": "Whether this delivery has a reconstructable webhook payload (member-viewed WEBHOOK deliveries only). When true, fetch the exact POSTed JSON from GET /v1/alerts/deliveries/{id}/webhook-payload — it is not embedded here because it can be many MB.", "type": "boolean" }, "id": { "type": "string" }, "match_count": { "format": "int64", "type": "integer" }, "matches": { "items": { "$ref": "#/components/schemas/AlertMatch" }, "type": [ "array", "null" ] }, "matches_cursor": { "description": "Opaque cursor; pass as ?matches_cursor= to fetch the next page of matches. Absent when there are no more.", "type": "string" }, "matches_has_more": { "description": "Whether more matches exist beyond this page. The true total is match_count.", "type": "boolean" }, "monitor": { "$ref": "#/components/schemas/AlertRef", "description": "Deprecated — use alert. Lightweight reference to the parent alert." }, "monitor_id": { "description": "Deprecated — use alert_id. ID of the parent alert.", "type": "string" }, "sent_at": { "format": "date-time", "type": "string" }, "status": { "description": "Delivery outcome — SENT (delivered; a partial success keeps this status with the failure noted in error_message), FAILED (an attempt failed; realtime retries within its budget and digests re-select within their window), SKIPPED (intentionally not delivered), or ABANDONED (realtime webhook delivery permanently gave up after exhausting its retry budget, so the match was dropped for that channel).", "type": "string" }, "viewer_can_manage": { "description": "Whether the caller is a member of the owning org (or an API key scoped to the owning project) and can manage this alert in-app. True responses carry the member-only fields; false responses are the public projection with those fields stripped. Clients must read this rather than inferring access from field presence.", "type": "boolean" } }, "required": [ "id", "monitor_id", "alert_id", "channel", "status", "viewer_can_manage", "match_count", "created_at", "matches", "matches_has_more", "has_webhook_payload" ], "type": "object" }, "AlertDeliverySummary": { "additionalProperties": false, "properties": { "channel": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "error_message": { "type": "string" }, "id": { "type": "string" }, "sent_at": { "format": "date-time", "type": "string" }, "status": { "description": "Delivery outcome — SENT (delivered; a partial success keeps this status with the failure noted in error_message), FAILED (an attempt failed; realtime retries within its budget and digests re-select within their window), SKIPPED (intentionally not delivered), or ABANDONED (realtime webhook delivery permanently gave up after exhausting its retry budget, so the match was dropped for that channel).", "type": "string" } }, "required": [ "id", "channel", "status", "created_at" ], "type": "object" }, "AlertEntity": { "additionalProperties": false, "properties": { "entity_id": { "type": "string" }, "entity_type": { "enum": [ "PERSON", "COMPANY", "KNOWLEDGE_GRAPH_ENTITY" ], "type": "string" }, "image_url": { "description": "Image URL for the watched entity (headshot for PERSON, logo for COMPANY, image for KGE). Omitted from the response when no image is available.", "type": "string" }, "name": { "description": "Display name of the watched entity. Omitted from the response when the underlying record cannot be resolved (e.g. deleted).", "type": "string" } }, "required": [ "entity_type", "entity_id" ], "type": "object" }, "AlertFilters": { "additionalProperties": false, "properties": { "languages": { "description": "Primary language tags the source episode must be in. Accepts a 2-3 letter primary tag (e.g. 'en', 'de', 'sma') and tolerates an optional 2-4 char region or script subtag for readability (e.g. 'pt-BR', 'zh-Hant'); matching is on the PRIMARY tag only, so 'pt-BR' surfaces every Portuguese episode regardless of region and 'pt-BR' + 'pt-PT' collapse to one. Empty or missing means all languages are surfaced. Codes are compared case-insensitively; the API echoes back the canonical primary-tag form.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "relevance": { "description": "EVERYTHING (the default) returns both on-target and incidental matches — the watched entity is correctly identified in both, only the depth of discussion differs. RELEVANT narrows to on-target only: matches where the watched entity is the subject being discussed, dropping passing mentions. Wrong-entity matches (knowledge-graph name collisions, e.g. the podcast 'Truckie' for an alert on the town 'Truckee') are globally suppressed before any filter runs.", "enum": [ "EVERYTHING", "RELEVANT" ], "type": "string" }, "source_popularity": { "description": "ANY (the default) keeps matches from every source. POPULAR keeps only matches whose source podcast scores in the top 5% by chart-popularity percentile (Podcast.Popularity \u003e= 0.95; cume_dist over current chart entries, multi-region weighted). Podcasts that aren't currently charting drop out.", "enum": [ "ANY", "POPULAR" ], "type": "string" }, "speaker_roles": { "description": "PODCAST_SPEAKER alerts only. REPLACES (not intersects with) the default appearance set the alert matches against. Default when omitted is GUEST, PANELIST, CORRESPONDENT, AUDIENCE, SOUNDBITE_SPEAKER — HOST is intentionally excluded because hosting the show isn't an appearance. Setting ['HOST'] flips that — only HOST appearances match. Setting ['GUEST'] alone narrows further. Sending this on an ENTITY_MENTION alert returns 422 — the wire layer can't tell at validation time, so the handler boundary rejects it once the parent kind is known. Input casing is not significant — 'guest' and 'GUEST' are the same value — and the filter is persisted and echoed back in canonical uppercase form. Raw STT/LLM labels like CALLER or REPORTER are not accepted because podcast_episode_speakers.role canonicalizes to the buckets above at write time.", "items": { "enum": [ "HOST", "GUEST", "PANELIST", "CORRESPONDENT", "AUDIENCE", "SOUNDBITE_SPEAKER" ], "type": "string" }, "type": [ "array", "null" ] } }, "type": "object" }, "AlertMatch": { "additionalProperties": false, "properties": { "alert_id": { "description": "ID of the parent alert.", "type": "string" }, "deliveries": { "items": { "$ref": "#/components/schemas/AlertDeliverySummary" }, "type": [ "array", "null" ] }, "detected_at": { "format": "date-time", "type": "string" }, "entity_id": { "type": "string" }, "entity_type": { "description": "Type of the watched target: PERSON, COMPANY, or KNOWLEDGE_GRAPH_ENTITY for entity alerts, KEYWORD for KEYWORD_MENTION alerts.", "type": "string" }, "episode": { "$ref": "#/components/schemas/AlertMatchEpisode", "description": "Optional episode + podcast metadata embedded so a single response renders a card without a follow-up /v1/episodes/{id} call. Populated for preview-sample matches (POST /v1/projects/{projectId}/alerts/preview's GET response) and for the landing-page GETs (GET /v1/alerts/deliveries/{id} in both summary and detailed views, GET /v1/alerts/matches/{id}); absent on the paginated live matches list." }, "id": { "type": "string" }, "is_backfilled": { "description": "True for matches written by the post-create historical sweep. Backfilled matches are real matches the live pipeline would have produced, with DetectedAt set to the source episode's publish time. They never trigger delivery (no email is sent) — the field lets the UI label them so users can distinguish 'past' from 'going-forward' matches.", "type": "boolean" }, "keyword": { "description": "KEYWORD_MENTION matches only: the phrase this match fired on. It stays the phrase that matched even if the alert's keyword is later edited.", "type": "string" }, "kind": { "description": "Inherited from the parent alert's kind so clients can render mention vs appearance semantics without a follow-up alert lookup. Match payloads from ENTITY_MENTION and KEYWORD_MENTION alerts carry mention_count and mention_variants; PODCAST_SPEAKER matches carry roles and a line-count in mention_count.", "enum": [ "ENTITY_MENTION", "PODCAST_SPEAKER", "KEYWORD_MENTION" ], "type": "string" }, "llm_summary": { "description": "AI-generated narrative summary of this match with prior-mention context from the past 7 days for the same (alert, entity). Generated asynchronously after match creation. Absent (field omitted) when the summarizer hasn't processed the row yet OR when the LLM exhausted its retry budget — clients should treat both states the same: no summary to render. Visible to both org members and the public landing-page tier; the summary describes the mention itself, not the alert configuration.", "type": "string" }, "mention_count": { "format": "int64", "type": "integer" }, "mention_variants": { "items": { "type": "string" }, "type": [ "array", "null" ] }, "monitor_id": { "description": "Deprecated — use alert_id. ID of the parent alert.", "type": "string" }, "relevance": { "description": "How this match relates to the watched entity, classified by the summarizer: on_target (the entity is the mention's subject or a substantive reference) or incidental (a correct but passing reference in service of another story). Absent when unjudged. Lets a client tell a substantive mention from a fly-by one. (A third internal verdict, wrong_entity, marks knowledge-graph name collisions; those matches are suppressed before delivery and never appear here.)", "enum": [ "on_target", "incidental" ], "type": "string" }, "roles": { "description": "Canonical speaker role(s) the matched entity appeared as. One of GUEST, PANELIST, CORRESPONDENT, or AUDIENCE (raw STT/LLM labels like CALLER, REPORTER, LISTENER are normalized to these buckets on write). Populated only for PODCAST_SPEAKER matches; sorted alphabetically for deterministic order.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "source_id": { "type": "string" }, "source_type": { "type": "string" }, "truncated": { "type": "boolean" }, "windows": { "items": { "$ref": "#/components/schemas/AlertMatchWindow" }, "type": [ "array", "null" ] } }, "required": [ "id", "monitor_id", "alert_id", "kind", "entity_type", "entity_id", "source_type", "source_id", "detected_at", "mention_count", "deliveries" ], "type": "object" }, "AlertMatchEpisode": { "additionalProperties": false, "properties": { "apple_podcasts_url": { "description": "Apple Podcasts deep-link for the parent podcast. Omitted when the podcast has no iTunes ID.", "type": "string" }, "audio_url": { "description": "CDN-fronted URL for the full episode audio, playable directly in a browser \u003caudio\u003e element without auth (the podcast's own public media). Clients play a specific window by loading this and seeking to the window's start_seconds. Omitted when the episode has no stored audio yet. Present on both the member and public landing-page tiers so a shared link can play the clip.", "type": "string" }, "duration_seconds": { "description": "Total episode duration in seconds. Omitted when unknown.", "format": "double", "type": "number" }, "explicit": { "description": "Whether the episode is flagged as containing explicit content by its publisher.", "type": "boolean" }, "image_url": { "description": "Episode-specific image. Omitted when the episode has no dedicated image. Clients should fall back to podcast_image_url for a card thumbnail in that case.", "type": "string" }, "podcast_bias": { "description": "Political bias rating for the parent podcast. Omitted when the podcast is not substantively political or has not been evaluated yet. Fetch GET /v1/podcasts/{id}/bias for the full analysis including reasoning and evidence.", "enum": [ "EXTREME_LEFT", "LEANS_LEFT", "LEFT", "CENTER", "RIGHT", "LEANS_RIGHT", "EXTREME_RIGHT" ], "type": "string" }, "podcast_id": { "type": "string" }, "podcast_image_url": { "description": "Parent podcast's image. Suitable as a fallback when image_url is absent.", "type": "string" }, "podcast_popularity": { "description": "Parent podcast's global popularity percentile in (0,1] — a cume_dist ranking over all currently-charting podcasts (Apple Podcasts charts). Higher is more popular; 1.0 is the most popular show. Omitted when the podcast is not currently charting.", "format": "double", "type": "number" }, "podcast_popularity_badge": { "description": "Human-facing reach tier derived from podcast_popularity: Top Podcast (top 1%), Very Popular (top 5%), or Popular (top 10%). Omitted for shows outside the top 10%.", "enum": [ "Top Podcast", "Very Popular", "Popular" ], "type": "string" }, "podcast_slug": { "type": "string" }, "podcast_title": { "type": "string" }, "published_at": { "format": "date-time", "type": "string" }, "slug": { "type": "string" }, "title": { "type": "string" } }, "required": [ "title", "podcast_id", "podcast_title" ], "type": "object" }, "AlertMatchLine": { "additionalProperties": false, "properties": { "end_seconds": { "format": "double", "type": "number" }, "is_mention": { "type": "boolean" }, "number": { "format": "int64", "type": "integer" }, "role": { "type": "string" }, "speaker": { "type": "string" }, "start_seconds": { "format": "double", "type": "number" }, "text": { "type": "string" } }, "required": [ "start_seconds", "end_seconds", "text" ], "type": "object" }, "AlertMatchSummary": { "additionalProperties": false, "properties": { "detected_at": { "format": "date-time", "type": "string" }, "entity_id": { "type": "string" }, "entity_type": { "type": "string" }, "id": { "type": "string" }, "keyword": { "description": "KEYWORD_MENTION matches only: the phrase this match fired on.", "type": "string" }, "kind": { "description": "Inherited from the parent alert's kind. See AlertMatch.kind.", "enum": [ "ENTITY_MENTION", "PODCAST_SPEAKER", "KEYWORD_MENTION" ], "type": "string" }, "mention_count": { "format": "int64", "type": "integer" }, "source_id": { "type": "string" }, "source_type": { "type": "string" } }, "required": [ "id", "kind", "entity_type", "entity_id", "source_type", "source_id", "detected_at", "mention_count" ], "type": "object" }, "AlertMatchWindow": { "additionalProperties": false, "properties": { "clip_description": { "type": "string" }, "clip_id": { "type": "string" }, "clip_intro_statement": { "type": "string" }, "clip_title": { "type": "string" }, "clip_type": { "type": "string" }, "end_seconds": { "format": "double", "type": "number" }, "lines": { "items": { "$ref": "#/components/schemas/AlertMatchLine" }, "type": [ "array", "null" ] }, "segment_description": { "type": "string" }, "segment_id": { "type": "string" }, "segment_summary": { "type": "string" }, "segment_title": { "type": "string" }, "segment_type": { "type": "string" }, "start_seconds": { "format": "double", "type": "number" } }, "required": [ "start_seconds", "end_seconds", "lines" ], "type": "object" }, "AlertNotificationChannel": { "additionalProperties": false, "properties": { "created_by": { "$ref": "#/components/schemas/Creator", "description": "User who added this destination. Server-populated." }, "email": { "description": "Required when type=EMAIL.", "format": "email", "type": "string" }, "id": { "type": "string" }, "slack_channel_id": { "description": "Required when type=SLACK. Slack vendor channel id (e.g. C01234XYZ for public channels, G... for private channels). Must be a channel returned by GET /v1/projects/{projectId}/slack/connections/{id}/channels.", "type": "string" }, "slack_channel_name": { "description": "Optional. Display label for the destination channel. The server overwrites this from the cached slack_channels row on save, so clients do not need to supply it.", "type": "string" }, "slack_connection_id": { "description": "Required when type=SLACK. The Slack workspace connection that owns the channel. Any active connection belonging to the alert's project is accepted, whichever surface installed it, so an alert created in one app can be managed from the other.", "type": "string" }, "type": { "description": "Delivery channel type. EMAIL writes to email; SLACK posts a message to a channel in a connected Slack workspace; WEBHOOK POSTs a signed JSON payload to a configured webhook connection.", "enum": [ "EMAIL", "SLACK", "WEBHOOK" ], "type": "string" }, "webhook_connection_id": { "description": "Required when type=WEBHOOK. The webhook connection that receives the signed payload.", "type": "string" } }, "required": [ "type" ], "type": "object" }, "AlertPreviewBucketResponse": { "additionalProperties": false, "properties": { "count": { "description": "Number of matches whose source episode aired on that day.", "format": "int64", "type": "integer" }, "date": { "description": "UTC date in YYYY-MM-DD format.", "type": "string" } }, "required": [ "date", "count" ], "type": "object" }, "AlertRef": { "additionalProperties": false, "properties": { "id": { "type": "string" }, "kind": { "description": "Inherited from the parent alert's kind. See AlertMatch.kind.", "enum": [ "ENTITY_MENTION", "PODCAST_SPEAKER", "KEYWORD_MENTION" ], "type": "string" }, "organization_id": { "description": "Owning organization. Omitted for non-member callers.", "type": "string" }, "project_id": { "description": "Owning project. Lets a deep-linked delivery select the right project in the dashboard. Omitted for non-member callers.", "type": "string" }, "title": { "type": "string" } }, "required": [ "id", "title", "kind" ], "type": "object" }, "AlertTestWebhookDelivery": { "additionalProperties": false, "properties": { "delivered": { "description": "True when the endpoint acknowledged with a 2xx status.", "type": "boolean" }, "duration_ms": { "description": "Round-trip time for the POST in milliseconds.", "format": "int64", "type": "integer" }, "error": { "description": "Failure reason when delivered is false — the endpoint's non-2xx status or the transport error.", "type": "string" }, "status_code": { "description": "HTTP status the endpoint returned. Absent on a transport-level failure (timeout, connection refused, or a blocked non-public address).", "format": "int64", "type": "integer" }, "url": { "description": "The destination the test payload was POSTed to.", "type": "string" }, "webhook_connection_id": { "type": "string" } }, "required": [ "webhook_connection_id", "url", "delivered" ], "type": "object" }, "AlertTestWebhookResult": { "additionalProperties": false, "properties": { "deliveries": { "description": "One entry per active webhook connection the test was POSTed to, in the order attempted. A channel whose connection has been deleted is skipped and does not appear here.", "items": { "$ref": "#/components/schemas/AlertTestWebhookDelivery" }, "type": [ "array", "null" ] } }, "required": [ "deliveries" ], "type": "object" }, "BackCatalogueCoverage": { "additionalProperties": false, "properties": { "complete": { "description": "true when the discovery sources listed the podcast's whole history. false when PodcastIndex capped its listing at 1,000 episodes, so older episodes may exist that neither it nor the podcast's own feed lists.", "type": "boolean" }, "feed_item_count": { "description": "Items the podcast's own feed listed. Absent when the feed could not be read.", "format": "int64", "type": "integer" }, "imported_at": { "description": "When the back catalogue was last imported.", "format": "date-time", "type": "string" }, "podcastindex_episode_count": { "description": "Episodes PodcastIndex listed, at most 1,000.", "format": "int64", "type": "integer" } }, "required": [ "imported_at", "complete", "podcastindex_episode_count" ], "type": "object" }, "BiasPodcastPublisherEntry": { "additionalProperties": false, "properties": { "analyzed_podcasts": { "description": "Catalog podcasts with at least one non-deleted analysis", "format": "int64", "type": "integer" }, "bucket_share": { "description": "podcasts_in_bucket / analyzed_podcasts (0..1)", "format": "double", "type": "number" }, "podcast_count": { "description": "Total podcasts in the publisher's catalog (denormalized)", "format": "int64", "type": "integer" }, "podcasts_in_bucket": { "description": "Analyzed podcasts whose latest result matches the requested bucket", "format": "int64", "type": "integer" }, "publisher": { "$ref": "#/components/schemas/PodcastPublisherCompact", "description": "PodcastPublisher reference" }, "sample_podcast_ids": { "description": "Up to 5 podcast IDs from the publisher whose latest result matches the requested bucket", "items": { "type": "string" }, "type": [ "array", "null" ] } }, "required": [ "publisher", "podcast_count", "analyzed_podcasts", "podcasts_in_bucket", "bucket_share" ], "type": "object" }, "Category": { "additionalProperties": false, "properties": { "external_id": { "description": "Source-native identifier for the category. For Apple this is the iTunes genre id; for Spotify it duplicates the slug.", "type": "string" }, "name": { "description": "Display name of the category.", "type": "string" }, "parent_slug": { "description": "Slug of the parent category, when this is a sub-category of a known hierarchy (Apple).", "type": "string" }, "slug": { "description": "Universal category slug (e.g. 'comedy', 'business'). Stable across sources, accepted as a filter on every rankings endpoint.", "type": "string" } }, "required": [ "slug", "name" ], "type": "object" }, "ClassificationCount": { "additionalProperties": false, "properties": { "classification": { "description": "Podcast classification the count covers. 'transcribed' podcasts have their episodes transcribed and analyzed.", "enum": [ "transcribed" ], "type": "string" }, "count": { "description": "Number of podcasts with this classification.", "format": "int64", "type": "integer" } }, "required": [ "classification", "count" ], "type": "object" }, "Clip": { "additionalProperties": false, "properties": { "audio_url": { "description": "Direct audio URL for this clip", "type": "string" }, "description": { "description": "AI-generated clip description", "type": "string" }, "duration_seconds": { "description": "Clip duration", "format": "double", "type": "number" }, "end_seconds": { "description": "End time within the episode", "format": "double", "type": "number" }, "engagement_score": { "description": "AI-predicted engagement potential (integer, 0 to 100). Values above 70 are typical for a strong clip.", "format": "double", "type": "number" }, "episode": { "$ref": "#/components/schemas/EpisodeCompactWithPodcast", "description": "Parent episode with podcast context" }, "id": { "description": "Unique identifier", "type": "string" }, "intro_statement": { "description": "AI-generated hook text for social sharing", "type": "string" }, "quote": { "description": "Verbatim transcript line from the clip, at most 140 characters, by the clip's speaker where possible", "type": "string" }, "segment": { "$ref": "#/components/schemas/SegmentCompact", "description": "Parent segment context" }, "speaker": { "$ref": "#/components/schemas/ClipSpeaker", "description": "Primary speaker in this clip" }, "start_seconds": { "description": "Start time within the episode", "format": "double", "type": "number" }, "title": { "description": "AI-generated clip title", "type": "string" }, "type": { "description": "Clip type", "enum": [ "SPICY", "CONTROVERSIAL", "EMOTIONAL", "FUNNY", "SHOCKING", "INSIGHTFUL", "INFORMATIVE", "EDUCATIONAL", "PHILOSOPHICAL", "AHA_MOMENT", "NOTABLE_LINE", "BEST_STORY", "DEBATE_DISAGREEMENT" ], "type": "string" } }, "required": [ "id", "title", "engagement_score", "start_seconds", "end_seconds", "duration_seconds" ], "type": "object" }, "ClipEmbed": { "additionalProperties": false, "properties": { "audio_url": { "description": "Direct audio URL", "type": "string" }, "duration_seconds": { "description": "Clip duration", "format": "double", "type": "number" }, "intro_statement": { "description": "Hook text for the embed card", "type": "string" }, "podcast_artwork_url": { "description": "Podcast cover image URL", "type": "string" }, "podcast_link": { "description": "Apple Podcasts or podcast URL", "type": "string" }, "podcast_name": { "description": "Podcast title", "type": "string" }, "published": { "description": "Episode publish date as short relative string", "type": "string" }, "speaker_name": { "description": "Primary speaker name", "type": "string" }, "speakers": { "additionalProperties": { "$ref": "#/components/schemas/ClipEmbedSpeaker" }, "description": "Speaker map keyed by speaker_id", "type": "object" }, "story_color_dominant": { "description": "Dominant color hex from the story header image", "type": "string" }, "story_url": { "description": "Link to the story this clip is from", "type": "string" }, "title": { "description": "Clip title", "type": "string" } }, "required": [ "title", "audio_url", "duration_seconds" ], "type": "object" }, "ClipEmbedSpeaker": { "additionalProperties": false, "properties": { "image": { "description": "Speaker avatar URL", "type": "string" }, "name": { "description": "Speaker display name", "type": "string" } }, "required": [ "name" ], "type": "object" }, "ClipSpeaker": { "additionalProperties": false, "properties": { "entity": { "$ref": "#/components/schemas/EntityCompact", "description": "Linked knowledge graph entity, when this speaker is identified" }, "name": { "description": "Speaker name", "type": "string" }, "person": { "$ref": "#/components/schemas/PersonCompact", "description": "Linked first-class Person, when the speaker has been resolved" }, "role": { "description": "Speaker role", "type": "string" } }, "required": [ "name" ], "type": "object" }, "CoOccurrenceEntry": { "additionalProperties": false, "properties": { "shared_episodes": { "description": "Number of episodes where both sponsors appear", "format": "int64", "type": "integer" }, "sponsor_a": { "$ref": "#/components/schemas/SponsorCompact", "description": "First sponsor in the pair" }, "sponsor_b": { "$ref": "#/components/schemas/SponsorCompact", "description": "Second sponsor in the pair" } }, "required": [ "sponsor_a", "sponsor_b", "shared_episodes" ], "type": "object" }, "Company": { "additionalProperties": false, "properties": { "description": { "description": "Company description", "type": "string" }, "external_links": { "description": "Known third-party profiles and identifiers (LinkedIn, social, domain, Wikidata, SEC CIK, tickers). Returned by GET /v1/companies/{id}; the list endpoint omits it.", "items": { "$ref": "#/components/schemas/ExternalLink" }, "type": [ "array", "null" ] }, "id": { "description": "Unique identifier", "type": "string" }, "identifiers": { "$ref": "#/components/schemas/CompanyIdentifiers", "description": "External identifiers" }, "image_url": { "description": "Company logo or image URL, when available.", "type": "string" }, "name": { "description": "Company name", "type": "string" }, "updated_at": { "description": "Last updated timestamp", "format": "date-time", "type": "string" } }, "required": [ "id", "name" ], "type": "object" }, "CompanyAdvertisingFacets": { "additionalProperties": false, "properties": { "podcast_count": { "description": "Exact number of matching podcasts, including podcasts without a publisher", "format": "int64", "type": "integer" }, "podcasts": { "description": "All matching podcasts, ranked by company ad activity", "items": { "$ref": "#/components/schemas/CompanyAdvertisingPodcastFacet" }, "type": [ "array", "null" ] }, "publisher_count": { "description": "Exact number of matching publishers", "format": "int64", "type": "integer" }, "publishers": { "description": "All matching publishers, ranked by company ad activity", "items": { "$ref": "#/components/schemas/CompanyAdvertisingPublisherFacet" }, "type": [ "array", "null" ] } }, "required": [ "podcast_count", "publisher_count", "podcasts", "publishers" ], "type": "object" }, "CompanyAdvertisingPlacement": { "additionalProperties": false, "properties": { "audio_url": { "description": "Direct audio URL for this segment", "type": "string" }, "description": { "description": "AI-generated segment description", "type": "string" }, "duration_seconds": { "description": "Segment duration", "format": "double", "type": "number" }, "end_line": { "description": "Last transcript line covered by this segment (1-indexed, inclusive). Omitted for episodes segmented before line ranges were recorded.", "format": "int64", "type": "integer" }, "end_seconds": { "description": "End time within the episode — when the segment's last spoken line ends. Where start_line/end_line are present, segments partition the transcript's lines rather than tiling the wall-clock timeline, and the interval between this and the next segment's start_seconds contains no transcribed speech (typically under a second, occasionally minutes of music or silence). Segments without a recorded line range were produced by an earlier segmenter and a small share of them do leave transcript lines uncovered, so a gap between two such segments may contain real speech. Use start_line/end_line to slice a transcript losslessly.", "format": "double", "type": "number" }, "episode": { "$ref": "#/components/schemas/EpisodeCompactWithPodcast", "description": "Parent episode with podcast context" }, "id": { "description": "Unique identifier", "type": "string" }, "number": { "description": "Segment position within the episode", "format": "int64", "type": "integer" }, "placement_type": { "description": "Where the ad appeared in the episode (PRE_ROLL, MID_ROLL, POST_ROLL)", "type": "string" }, "read_type": { "description": "For AD segments, how the ad was delivered (HOST_READ, PRE_RECORDED, NETWORK_PROMO)", "type": "string" }, "sponsors": { "description": "Company-scoped sponsors attributed to this physical ad read", "items": { "$ref": "#/components/schemas/SponsorCompact" }, "type": [ "array", "null" ] }, "start_line": { "description": "First transcript line covered by this segment (1-indexed, inclusive). Line numbers match the number field of GET /v1/podcasts/episodes/{id}/transcript lines. This segment's end_line + 1 is the next segment's start_line, and the segments together cover every line of the transcript. Omitted for episodes segmented before line ranges were recorded.", "format": "int64", "type": "integer" }, "start_seconds": { "description": "Start time within the episode — when the segment's first spoken line begins", "format": "double", "type": "number" }, "summary": { "description": "AI-generated segment summary", "type": "string" }, "title": { "description": "AI-generated segment title", "type": "string" }, "type": { "description": "Segment type (INTRO, PERSONAL_BANTER, TOPIC_DISCUSSION, INTERVIEW, TRANSITION, AD, OUTRO)", "type": "string" } }, "required": [ "placement_type", "sponsors", "id", "number", "type", "title", "start_seconds", "end_seconds", "duration_seconds" ], "type": "object" }, "CompanyAdvertisingPodcastEntry": { "additionalProperties": false, "properties": { "ad_count": { "description": "Exact company-linked ad count on this podcast in the requested scope", "format": "int64", "type": "integer" }, "episode_count": { "description": "Exact distinct episode count on this podcast in the requested scope", "format": "int64", "type": "integer" }, "last_seen_at": { "description": "Publication time of the company's most recent ad on this podcast", "format": "date-time", "type": "string" }, "podcast": { "$ref": "#/components/schemas/PodcastCompact", "description": "Podcast carrying the company's ads" }, "preview_segments": { "description": "Recent company-attributed ad segments from this podcast, bounded by the requested preview limit", "items": { "$ref": "#/components/schemas/CompanyAdvertisingPreview" }, "type": [ "array", "null" ] }, "sponsors": { "description": "Sponsor attribution breakdown for this podcast and request scope", "items": { "$ref": "#/components/schemas/CompanyAdvertisingSponsorBreakdown" }, "type": [ "array", "null" ] } }, "required": [ "podcast", "ad_count", "episode_count", "sponsors", "preview_segments" ], "type": "object" }, "CompanyAdvertisingPodcastFacet": { "additionalProperties": false, "properties": { "ad_count": { "description": "Exact company-linked ad count on this podcast in the facet scope", "format": "int64", "type": "integer" }, "podcast": { "$ref": "#/components/schemas/CompanyAdvertisingPodcastFacetIdentity", "description": "Lightweight podcast identity" } }, "required": [ "podcast", "ad_count" ], "type": "object" }, "CompanyAdvertisingPodcastFacetIdentity": { "additionalProperties": false, "properties": { "id": { "description": "Podcast ID", "type": "string" }, "publisher": { "$ref": "#/components/schemas/PodcastPublisherCompact", "description": "Publisher (network) attributed to this podcast, when known" }, "slug": { "description": "Human-readable slug identifier", "type": "string" }, "title": { "description": "Podcast title", "type": "string" } }, "required": [ "id", "title" ], "type": "object" }, "CompanyAdvertisingPodcastsPage": { "additionalProperties": false, "properties": { "cursor": { "description": "Pass to the next request for more podcasts", "type": "string" }, "data": { "description": "Podcasts ranked by company ad count", "items": { "$ref": "#/components/schemas/CompanyAdvertisingPodcastEntry" }, "type": [ "array", "null" ] }, "facets": { "$ref": "#/components/schemas/CompanyAdvertisingFacets", "description": "Exhaustive Show and Network filter metadata, present only when requested on a cursorless request" }, "has_more": { "description": "Whether more ranked podcasts exist", "type": "boolean" }, "sponsors": { "description": "Complete date-scoped sponsor roster for this company; empty when include_sponsors=false", "items": { "$ref": "#/components/schemas/CompanyAdvertisingSponsorBreakdown" }, "type": [ "array", "null" ] } }, "required": [ "data", "sponsors", "has_more" ], "type": "object" }, "CompanyAdvertisingPreview": { "additionalProperties": false, "properties": { "segment": { "$ref": "#/components/schemas/Segment", "description": "Recent ad segment illustrating the company's activity on this podcast" }, "sponsors": { "description": "Company-scoped sponsors attributed to this segment", "items": { "$ref": "#/components/schemas/SponsorCompact" }, "type": [ "array", "null" ] } }, "required": [ "segment", "sponsors" ], "type": "object" }, "CompanyAdvertisingProfile": { "additionalProperties": false, "properties": { "company_id": { "description": "Company identifier (domain, slug, or encoded ID)", "type": "string" }, "episode_reach": { "description": "Number of distinct episodes with ads", "format": "int64", "type": "integer" }, "podcast_reach": { "description": "Number of distinct podcasts with ads", "format": "int64", "type": "integer" }, "read_type_breakdown": { "$ref": "#/components/schemas/ReadTypeBreakdown", "description": "Distribution of ad read types" }, "recent_ads": { "description": "Most recent ad placements", "items": { "$ref": "#/components/schemas/AdDetail" }, "type": [ "array", "null" ] }, "slug": { "description": "Stable human-readable handle (the linked knowledge-graph slug, e.g. 'nvidia'), when known. Prefer it (or company_id) as a /v1/companies key.", "type": "string" }, "total_ads": { "description": "Total number of ads across all podcasts", "format": "int64", "type": "integer" } }, "required": [ "company_id", "total_ads", "podcast_reach", "episode_reach", "read_type_breakdown", "recent_ads" ], "type": "object" }, "CompanyAdvertisingPublisherFacet": { "additionalProperties": false, "properties": { "ad_count": { "description": "Exact company-linked ad count across this publisher's matching podcasts", "format": "int64", "type": "integer" }, "podcast_count": { "description": "Exact number of matching podcasts attributed to this publisher", "format": "int64", "type": "integer" }, "publisher": { "$ref": "#/components/schemas/PodcastPublisherCompact", "description": "Publisher identity" } }, "required": [ "publisher", "podcast_count", "ad_count" ], "type": "object" }, "CompanyAdvertisingSponsorBreakdown": { "additionalProperties": false, "properties": { "ad_count": { "description": "Ads attributed to this sponsor inside the response scope", "format": "int64", "type": "integer" }, "episode_count": { "description": "Distinct episodes containing this sponsor inside the response scope", "format": "int64", "type": "integer" }, "last_seen_at": { "description": "Publication time of this sponsor's most recent ad inside the response scope", "format": "date-time", "type": "string" }, "sponsor": { "$ref": "#/components/schemas/SponsorCompact", "description": "Sponsor identity attributed to the company advertising activity" } }, "required": [ "sponsor", "ad_count", "episode_count" ], "type": "object" }, "CompanyCompact": { "additionalProperties": false, "properties": { "description": { "description": "Short company description, when known.", "type": "string" }, "domain": { "description": "Primary website domain (e.g. 'nvidia.com'), when known.", "type": "string" }, "id": { "description": "Company identifier (domain, slug, or encoded ID)", "type": "string" }, "image_url": { "description": "Company logo or image URL", "type": "string" }, "name": { "description": "Company name", "type": "string" }, "slug": { "description": "Stable human-readable handle (the linked knowledge-graph slug, e.g. 'nvidia'), when known. Companies have no slug of their own; prefer this for display and pass it (or id) to /v1/companies.", "type": "string" }, "ticker": { "description": "Primary stock ticker symbol, when listed.", "type": "string" } }, "required": [ "id", "name" ], "type": "object" }, "CompanyIdentifiers": { "additionalProperties": false, "properties": { "cik": { "description": "SEC Central Index Key", "type": "string" }, "domain": { "description": "Company domain", "type": "string" }, "entity": { "$ref": "#/components/schemas/EntityCompact", "description": "Linked knowledge graph entity" }, "qid": { "description": "Wikidata QID", "type": "string" }, "ticker": { "description": "Primary stock ticker symbol", "type": "string" } }, "type": "object" }, "CompanyProduct": { "additionalProperties": false, "properties": { "children": { "description": "Child products in the hierarchy", "items": { "$ref": "#/components/schemas/CompanyProduct" }, "type": [ "array", "null" ] }, "company_id": { "description": "Parent company identifier (domain, slug, or encoded ID)", "type": "string" }, "description": { "description": "Product description", "type": "string" }, "id": { "description": "Unique identifier", "type": "string" }, "level": { "description": "Hierarchy position: segment, product_line, or product", "type": "string" }, "name": { "description": "Product name", "type": "string" }, "product_url": { "description": "Canonical product page URL", "type": "string" }, "status": { "description": "Lifecycle status: active, announced, discontinued, or rumored", "type": "string" }, "updated_at": { "description": "Last updated timestamp", "format": "date-time", "type": "string" } }, "required": [ "id", "name", "level", "status", "company_id" ], "type": "object" }, "Competitor": { "additionalProperties": false, "properties": { "company": { "$ref": "#/components/schemas/Company", "description": "The competing company" }, "competitive_basis": { "description": "Rationale for the competitive relationship", "type": "string" } }, "required": [ "company" ], "type": "object" }, "CorpusEpisodeCount": { "additionalProperties": false, "properties": { "count": { "description": "Episodes with this status.", "format": "int64", "type": "integer" }, "transcript_status": { "description": "transcribed: episodes with a transcript. requestable: episodes in podcasts' back catalogues, discovered but not yet transcribed, whose audio we can transcribe.", "enum": [ "transcribed", "requestable" ], "type": "string" } }, "required": [ "transcript_status", "count" ], "type": "object" }, "CreateAlertBody": { "additionalProperties": false, "properties": { "delivery_cadence": { "description": "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.", "enum": [ "REALTIME", "DAILY", "WEEKLY" ], "type": "string" }, "description": { "maxLength": 2000, "type": "string" }, "entities": { "description": "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.", "items": { "$ref": "#/components/schemas/AlertEntity" }, "maxItems": 1, "minItems": 1, "type": [ "array", "null" ] }, "filters": { "$ref": "#/components/schemas/AlertFilters", "description": "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": { "description": "Whether the alert produces matches. Defaults to true. Disabling stops new matches without losing the alert — re-enable to resume.", "type": "boolean" }, "keyword": { "description": "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.", "maxLength": 100, "type": "string" }, "kind": { "description": "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. 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.", "enum": [ "ENTITY_MENTION", "PODCAST_SPEAKER", "KEYWORD_MENTION" ], "type": "string" }, "notifications": { "description": "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.", "items": { "$ref": "#/components/schemas/AlertNotificationChannel" }, "maxItems": 20, "minItems": 1, "type": [ "array", "null" ] }, "title": { "description": "Human-readable title", "maxLength": 200, "minLength": 1, "type": "string" } }, "required": [ "title", "notifications" ], "type": "object" }, "CreateWebhookConnectionBody": { "additionalProperties": false, "properties": { "name": { "description": "Optional human label for the connection.", "maxLength": 200, "type": "string" }, "url": { "description": "Destination URL. Must be https and resolve to a public address; private, loopback, and link-local addresses are rejected.", "maxLength": 2000, "minLength": 1, "type": "string" } }, "required": [ "url" ], "type": "object" }, "Creator": { "additionalProperties": false, "properties": { "id": { "description": "Creator's user ID", "type": "string" }, "name": { "description": "Creator's display name", "type": "string" } }, "required": [ "id", "name" ], "type": "object" }, "DeleteAlertResponseBody": { "additionalProperties": false, "properties": { "deleted": { "type": "boolean" } }, "required": [ "deleted" ], "type": "object" }, "DeleteSlackConnectionResponseBody": { "additionalProperties": false, "properties": { "deleted": { "type": "boolean" } }, "required": [ "deleted" ], "type": "object" }, "DeleteWebhookConnectionResponseBody": { "additionalProperties": false, "properties": { "deleted": { "type": "boolean" } }, "required": [ "deleted" ], "type": "object" }, "DialogueLine": { "additionalProperties": false, "properties": { "end_seconds": { "description": "End time in seconds", "format": "double", "type": "number" }, "number": { "description": "Line number (1-indexed)", "format": "int64", "type": "integer" }, "role": { "description": "Speaker role. One of the canonical buckets documented on the episode speakers endpoint (HOST, GUEST, PANELIST, CORRESPONDENT, MODERATOR, NARRATOR, ANNOUNCER, VOICE_ACTOR, SOUNDBITE_SPEAKER, AUDIENCE, ADVERTISER, PRODUCER, UNKNOWN, OTHER).", "type": "string" }, "speaker": { "description": "Speaker name or ID", "type": "string" }, "start_seconds": { "description": "Start time in seconds", "format": "double", "type": "number" }, "text": { "description": "Spoken text", "type": "string" } }, "required": [ "number", "speaker", "start_seconds", "end_seconds", "text" ], "type": "object" }, "DialogueTranscriptResponse": { "additionalProperties": false, "properties": { "duration_seconds": { "description": "Total duration in seconds", "format": "double", "type": "number" }, "episode_id": { "description": "Parent episode ID", "type": "string" }, "excerpt": { "description": "True when this response is one requested segment of the episode rather than the whole transcript.", "type": "boolean" }, "language": { "description": "Transcript language code", "type": "string" }, "lines": { "description": "Speaker-attributed dialogue lines", "items": { "$ref": "#/components/schemas/DialogueLine" }, "type": [ "array", "null" ] }, "segment_end_seconds": { "description": "End of the excerpt's segment, in seconds.", "format": "double", "type": "number" }, "segment_id": { "description": "The segment this excerpt covers. Pass to get-segment-transcript for the same lines.", "type": "string" }, "segment_start_seconds": { "description": "Start of the excerpt's segment, in seconds.", "format": "double", "type": "number" } }, "required": [ "episode_id", "duration_seconds", "lines" ], "type": "object" }, "DisableAlertBody": { "additionalProperties": false, "properties": { "token": { "description": "Disable-alert token from the footer of an alert email.", "type": "string" } }, "required": [ "token" ], "type": "object" }, "DisableAlertResponseBody": { "additionalProperties": false, "properties": { "alert_id": { "description": "The alert identified by the supplied token.", "type": "string" }, "already_disabled": { "description": "True when this click is not the one that changed state — either the token was already redeemed (GET preview after a click, or POST replay), or the alert was already inactive when the token was redeemed. The is_active field reflects the alert's *current* state, which can diverge from already_disabled if the alert was re-enabled after the token was redeemed.", "type": "boolean" }, "delivery_cadence": { "description": "The alert's delivery cadence (REALTIME, DAILY, or WEEKLY).", "type": "string" }, "is_active": { "description": "The alert's current is_active flag — false after a successful POST.", "type": "boolean" }, "kind": { "description": "The alert's kind (ENTITY_MENTION, PODCAST_SPEAKER, or KEYWORD_MENTION).", "type": "string" }, "manage_url": { "description": "Deep-link to the alert's management page.", "type": "string" }, "monitor_id": { "description": "Deprecated — use alert_id. The alert identified by the supplied token.", "type": "string" }, "title": { "description": "The alert's current title.", "type": "string" } }, "required": [ "monitor_id", "alert_id", "title", "kind", "delivery_cadence", "is_active", "already_disabled", "manage_url" ], "type": "object" }, "Entity": { "additionalProperties": false, "properties": { "company": { "$ref": "#/components/schemas/EntityCompany", "description": "Linked company record, if this entity is a known company" }, "description": { "description": "Short description", "type": "string" }, "id": { "description": "Unique identifier", "type": "string" }, "image_url": { "description": "Entity image URL", "type": "string" }, "name": { "description": "Entity name", "type": "string" }, "person": { "$ref": "#/components/schemas/EntityPerson", "description": "Linked person record, if this entity is a known person" }, "slug": { "description": "Human-readable slug identifier", "type": "string" }, "type": { "$ref": "#/components/schemas/EntityType", "description": "Category. Omitted when the entity falls outside the supported set." }, "wikipedia_url": { "description": "Wikipedia URL", "type": "string" } }, "required": [ "id", "slug", "name" ], "type": "object" }, "EntityChart": { "additionalProperties": false, "properties": { "category_name": { "description": "Display name for the chart.", "type": "string" }, "category_slug": { "description": "Chart identifier.", "type": "string" }, "caveats": { "description": "Edition-level measurement caveats.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "computed_at": { "description": "When the positions were computed.", "format": "date-time", "type": "string" }, "edition_date": { "description": "Eastern-time calendar date the edition describes, as YYYY-MM-DD.", "type": "string" }, "enriched_at": { "description": "When the narrative pipeline finished. Absent while status is 'computed'.", "format": "date-time", "type": "string" }, "entries": { "description": "Ranked entries. Rank ascending by default; ordered by accel_multiple when the chart was requested with sort=acceleration, with each entry's rank still naming its published chart position.", "items": { "$ref": "#/components/schemas/EntityChartEntry" }, "type": [ "array", "null" ] }, "methodology_version": { "description": "Version of the ranking methodology that produced this edition. Editions across a version change are not directly comparable.", "format": "int64", "type": "integer" }, "source": { "description": "Which measurement family this chart belongs to, so a client knows which entry fields apply: 'mentions' charts measure organic podcast mentions and carry mention_count, accel_multiple, and signals — the per-category charts rank by distinct mentioning podcasts, while the sports charts and the composite charts (all, all-entertainment, all-sports) blend reach with 52-day elevation, so their rank does not follow podcast_count; all draws on a wider curated pool of entity types (people, books, music, brands, organizations, sports, events, products, and more), and the per-group composites pool only their group's charts; the 'guest_appearances' chart ranks people by the distinct shows they appeared on, always reports mention_count 0, and carries appearances and highlight_clip instead.", "enum": [ "mentions", "guest_appearances" ], "type": "string" }, "status": { "description": "Edition lifecycle: 'computed' or 'enriched'.", "type": "string" }, "window": { "description": "Measurement window this edition covers.", "type": "string" } }, "required": [ "category_slug", "category_name", "source", "window", "edition_date", "status", "methodology_version", "entries" ], "type": "object" }, "EntityChartClip": { "additionalProperties": false, "properties": { "audio_url": { "description": "Pre-cut clip audio, when the extractor stored one; otherwise play the source episode at the offsets above.", "type": "string" }, "end_seconds": { "description": "End offset of the clip within the episode audio.", "format": "double", "type": "number" }, "engagement": { "description": "The clip's engagement-potential score, the value it was ranked by.", "format": "double", "type": "number" }, "episode": { "$ref": "#/components/schemas/EpisodeCompactWithPodcast", "description": "The source episode with its podcast, enough to render the receipt without fetching the episode. Absent when its metadata is temporarily unavailable." }, "start_seconds": { "description": "Offset of the clip within the episode audio, for click-to-play.", "format": "double", "type": "number" }, "title": { "description": "The clip's title — its editorial hook. Not a verbatim transcript line; render it as a caption, and read the episode transcript for the dialogue.", "type": "string" } }, "required": [ "title", "start_seconds", "end_seconds", "engagement" ], "type": "object" }, "EntityChartEntry": { "additionalProperties": false, "properties": { "accel_multiple": { "description": "How much faster the entity's podcast coverage grew on the last complete day than its own trailing six-day baseline, normalized for overall daily publishing volume so day-of-week swings do not register as movement. Same scale as accel_multiple on the entity trends endpoint. Absent when the entry has no baseline (a debut) or not enough history; render 'new' rather than a number. Always absent on the guests chart: guest appearances are too sparse for a daily multiple, and the guests ranking already measures each guest's spike against their own baseline.", "format": "double", "type": "number" }, "appearances": { "description": "The guest's episode appearances in this window, newest first, as play-in links to the conversation. Present only on the guests chart, for entries with a person subject; empty on the mention-driven charts.", "items": { "$ref": "#/components/schemas/PodcastGuestAppearance" }, "type": [ "array", "null" ] }, "breaking": { "description": "True when the entity's coverage is spiking sharply against its own recent baseline and stayed active in the last day. On the all chart only entries pinned at the head can carry the badge, and a pinned entry that is merely rising does not; category charts badge every qualifying entry.", "type": "boolean" }, "caveats": { "description": "Entry-level measurement caveats.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "driven_by": { "$ref": "#/components/schemas/EntityChartTrendDriver", "description": "Set when this entry's movement is driven by another entry's coverage on the same chart, such as a tribute song rising with the artist it belongs to. It names the driving entry so a client can group derivative entries under what drives them. Present only when include=driven_by is requested, and only on derivative entries." }, "episode_count": { "description": "Distinct episodes mentioning the entity. Never used for ranking: recap networks re-airing clips inflate it.", "format": "int64", "type": "integer" }, "highlight_clip": { "$ref": "#/components/schemas/EntityChartClip", "description": "The guest's single highest-engagement clip from this window's episodes, playable at its offsets — the person analog of the mention charts' quote receipt. Present only on the guests chart, and only when a scored clip exists; guests with no scored clip fall back to the appearance list." }, "mention_count": { "description": "Organic dialogue mentions in the window. Not measured on the guests chart, where it is always 0.", "format": "int64", "type": "integer" }, "movement": { "description": "Movement since the previous edition.", "enum": [ "new", "up", "down", "flat" ], "type": "string" }, "podcast_count": { "description": "Distinct podcasts mentioning the entity organically in the window; on the guests chart, distinct shows the person appeared on. The ranking key on the per-category charts and the guests chart. The composite charts (all, all-entertainment, all-sports) and the sports charts (nfl, nba, mlb, nhl, college-football, wnba, college-basketball, soccer, golf, tennis, formula-1, nascar, pro-wrestling) rank by a blend of this reach and 52-day elevation, so there a lower count can rank higher.", "format": "int64", "type": "integer" }, "previous_episode_count": { "description": "Episode count over the window immediately before this one. Always emitted; 0 on a debut (movement=='new').", "format": "int64", "type": "integer" }, "previous_mention_count": { "description": "Mention count over the window immediately before this one. Always emitted; 0 on a debut (movement=='new').", "format": "int64", "type": "integer" }, "previous_podcast_count": { "description": "Podcast count over the window immediately before this one. Always emitted; a debut reads 0, so tell a real 0 from 'not ranked before' by movement=='new' (previous_rank null).", "format": "int64", "type": "integer" }, "previous_rank": { "description": "Position on the previous edition. Absent when the entity was not ranked then.", "format": "int64", "type": "integer" }, "rank": { "description": "Position in this edition, 1 is highest.", "format": "int64", "type": "integer" }, "rank_change": { "description": "Positions climbed since the previous edition, negative when the entity fell. Zero for both a flat hold and a debut. Read 'movement' to tell those apart.", "format": "int64", "type": "integer" }, "signals": { "$ref": "#/components/schemas/EntityChartSignals", "description": "Momentum classification and the window averages behind it. Absent on editions published before this field existed, on the guests chart, and on 24h editions, none of which compute a signal state. Fall back to breaking and movement when absent. The operand fields below are normalized for publishing volume and for the entity's own weekly cycle, so they will not equal the plain mean of the timeseries buckets' podcast_count; they are the calculation's own inputs, meant to be drawn as reference lines over the timeseries rather than shown as headline numbers. They are omitted for a session without paid Radar access, and whenever state is new." }, "subject": { "$ref": "#/components/schemas/EntityChartSubject", "description": "The ranked entity. Both members are null on a tombstone." }, "timeseries": { "$ref": "#/components/schemas/EntityChartTimeseries", "description": "Daily history. Present only when include=timeseries was requested." }, "tombstone": { "description": "True when the ranked entity was deleted upstream after publication. The position and counts remain as history, but there is no subject to render.", "type": "boolean" }, "why": { "$ref": "#/components/schemas/EntityChartNarrative", "description": "Editorial explanation of the movement with a supporting quote. Absent when no explanation was written for this entry." } }, "required": [ "rank", "subject", "movement", "rank_change", "podcast_count", "episode_count", "mention_count", "previous_podcast_count", "previous_episode_count", "previous_mention_count" ], "type": "object" }, "EntityChartNarrative": { "additionalProperties": false, "properties": { "clip": { "$ref": "#/components/schemas/EntityChartClip", "description": "An existing episode highlight clip that fully contains the quote, playable at its offsets as a pre-cut, engagement-scored moment. Present only on the mention-driven charts, and only when a highlight clip covers the quote, which is the minority case; otherwise fall back to the quote offsets. The guests chart uses highlight_clip instead. The clip's source episode is the narrative's source_episode." }, "generated_at": { "description": "When the explanation was written.", "format": "date-time", "type": "string" }, "quote": { "description": "Verbatim podcast dialogue supporting the explanation. Absent when no quote was captured for it.", "type": "string" }, "quote_end_seconds": { "description": "End offset of the quote within the episode audio.", "format": "double", "type": "number" }, "quote_start_seconds": { "description": "Offset of the quote within the episode audio, for click-to-play.", "format": "double", "type": "number" }, "quote_window": { "description": "The quote's surrounding dialogue with a speaker per line, in the same line shape the alert match windows use. Lines with is_mention true are the quote's own. Render the receipt from this instead of fetching the episode transcript. Empty on narratives written before this field existed, where the transcript remains the fallback.", "items": { "$ref": "#/components/schemas/AlertMatchLine" }, "type": [ "array", "null" ] }, "source_episode": { "$ref": "#/components/schemas/EpisodeCompactWithPodcast", "description": "Summary of the source episode with its podcast (title, artwork, publisher), enough to render the receipt without fetching the episode. Absent when the episode no longer exists — then verifiable is false and source_episode_id and source_episode_name are absent too, so render the text without a receipt — or when its metadata is temporarily unavailable, in which case the id and name are still present." }, "source_episode_id": { "description": "Episode the quote came from. Accepted by the episode endpoints. Absent, together with source_episode_name and source_episode, once the episode has been deleted (verifiable is false).", "type": "string" }, "source_episode_name": { "description": "Title of the source episode.", "type": "string" }, "text": { "description": "One-line explanation of why the entity moved.", "type": "string" }, "verifiable": { "description": "Whether a quote was captured and its source episode still exists. False both when the episode was deleted after the explanation was written and when no quote was captured. Clients must gate quote display and click-to-play on this; source_episode is loaded best-effort and may be absent even when this is true.", "type": "boolean" } }, "required": [ "text", "verifiable" ], "type": "object" }, "EntityChartSignals": { "additionalProperties": false, "properties": { "elevation_baseline": { "description": "The mean of the 52 complete days before the elevation_recent window.", "format": "double", "type": "number" }, "elevation_recent": { "description": "The mean of the last 7 complete days.", "format": "double", "type": "number" }, "state": { "description": "Current momentum classification. breaking: carries the breaking badge, coverage is spiking against its recent baseline and still active in the last day. rising: the most recent days run above the days before them. steady: roughly flat. settling: the last days fall against the days before them, but the week still sits far above its long-run norm, a big story past its peak. cooling: falling with no elevated week behind it. new: too little history to classify. New states may be added later; render an unknown value as steady.", "enum": [ "breaking", "rising", "steady", "settling", "cooling", "new" ], "type": "string" }, "trend_baseline": { "description": "The mean of the 4 complete days before the trend_recent window.", "format": "double", "type": "number" }, "trend_recent": { "description": "The weighted mean of the last 3 complete days, weighted toward the most recent day. The window widths are the methodology; methodology_version changes if they change.", "format": "double", "type": "number" } }, "required": [ "state" ], "type": "object" }, "EntityChartSubject": { "additionalProperties": false, "properties": { "entity": { "$ref": "#/components/schemas/EntityCompact", "description": "Knowledge graph entity, on the mention-driven charts. The slug is accepted by the entity endpoints." }, "person": { "$ref": "#/components/schemas/PersonCompact", "description": "Person, on the guests chart. The slug is accepted by the person and guest endpoints." }, "type": { "description": "Which identity this subject carries, and so which field below is populated: 'entity' on the mention-driven charts, 'person' on the guests chart. Omitted on a tombstone, where neither is set; read the chart's 'source' for the family.", "enum": [ "entity", "person" ], "type": "string" } }, "type": "object" }, "EntityChartSummary": { "additionalProperties": false, "properties": { "category_name": { "description": "Display name for the chart (e.g. 'TV Series').", "type": "string" }, "category_slug": { "description": "Chart identifier, accepted as the {category} path parameter (e.g. 'tv-series', 'movies', 'video-games', 'guests', 'nfl').", "type": "string" }, "caveats": { "description": "Edition-level measurement caveats.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "computed_at": { "description": "When the positions were computed.", "format": "date-time", "type": "string" }, "edition_date": { "description": "Eastern-time calendar date the edition describes, as YYYY-MM-DD. Empty when no edition has been published yet.", "type": "string" }, "enriched_at": { "description": "When the narrative pipeline finished. Absent while status is 'computed'.", "format": "date-time", "type": "string" }, "group": { "description": "Directory section this chart belongs to, so a client can tab the directory instead of hard-coding which charts exist. An 'overall' chart ranks across every subject and stands on its own; 'entertainment' and 'sports' each hold several charts led by a composite of that group (all-entertainment, all-sports). The value set is closed, so a new group is a schema change.", "enum": [ "overall", "entertainment", "sports" ], "type": "string" }, "leader": { "$ref": "#/components/schemas/EntityChartSubject", "description": "The rank-1 entity of the current edition." }, "source": { "description": "Which measurement family this chart belongs to, so a client knows which entry fields apply: 'mentions' charts measure organic podcast mentions and carry mention counts, acceleration, and signals — the per-category charts rank by distinct mentioning podcasts, while the sports charts and the composite charts (all, all-entertainment, all-sports) blend reach with 52-day elevation, so their rank does not follow podcast_count; all draws on a wider curated pool of entity types (people, books, music, brands, organizations, sports, events, products, and more), and the per-group composites pool only their group's charts; the 'guest_appearances' chart ranks people by the distinct shows they appeared on and carries appearances and a highlight clip instead.", "enum": [ "mentions", "guest_appearances" ], "type": "string" }, "status": { "description": "Edition lifecycle: 'computed' means positions are final and narratives have not run; 'enriched' means the narrative pipeline finished. Individual entries carry their own narrative state.", "type": "string" }, "window": { "description": "Measurement window this edition covers.", "type": "string" }, "windows": { "description": "Every measurement window this chart publishes, each accepted as the window query parameter on this endpoint and on the chart endpoint. Most charts publish both '7d' and '24h'; the composite charts (all, all-entertainment, all-sports) publish '7d' only. A window absent here is a 422, not an empty edition.", "items": { "enum": [ "7d", "24h" ], "type": "string" }, "type": [ "array", "null" ] } }, "required": [ "category_slug", "category_name", "source", "window", "windows", "group" ], "type": "object" }, "EntityChartTimeseries": { "additionalProperties": false, "properties": { "buckets": { "description": "One bucket per Eastern day, oldest first, contiguous through the last complete day before edition_date.", "items": { "$ref": "#/components/schemas/EntityChartTimeseriesBucket" }, "type": [ "array", "null" ] }, "end": { "description": "Eastern-time date of the last bucket, YYYY-MM-DD. The last complete Eastern day, edition_date minus one day; the current partial day is dropped.", "type": "string" }, "interval": { "description": "Bucket width. Always 'day' for entity charts.", "enum": [ "day" ], "type": "string" }, "start": { "description": "Eastern-time date of the first bucket, YYYY-MM-DD, on edition_date's calendar.", "type": "string" } }, "required": [ "interval", "buckets" ], "type": "object" }, "EntityChartTimeseriesBucket": { "additionalProperties": false, "properties": { "mention_count": { "description": "Organic dialogue mentions on this day.", "format": "int64", "type": "integer" }, "podcast_count": { "description": "Distinct podcasts mentioning the entity on this day.", "format": "int64", "type": "integer" }, "start": { "description": "Eastern-time date of this bucket, YYYY-MM-DD.", "type": "string" } }, "required": [ "start", "podcast_count", "mention_count" ], "type": "object" }, "EntityChartTrendDriver": { "additionalProperties": false, "properties": { "rank": { "description": "Rank of the driving entry on this same edition. Usually a higher position than this entry, but not guaranteed: on the composite chart, where rank does not follow raw reach, a driver can sit a few positions below the entry it drives.", "format": "int64", "type": "integer" }, "subject": { "$ref": "#/components/schemas/EntityChartSubject", "description": "The entity whose coverage drives this entry's movement." } }, "required": [ "rank", "subject" ], "type": "object" }, "EntityCompact": { "additionalProperties": false, "properties": { "company": { "$ref": "#/components/schemas/EntityCompany", "description": "Linked company record, if this entity is a known company" }, "description": { "description": "Short description", "type": "string" }, "id": { "description": "Entity ID", "type": "string" }, "image_url": { "description": "Entity image URL", "type": "string" }, "name": { "description": "Entity name", "type": "string" }, "person": { "$ref": "#/components/schemas/EntityPerson", "description": "Linked person record, if this entity is a known person" }, "slug": { "description": "Human-readable slug identifier", "type": "string" }, "type": { "$ref": "#/components/schemas/EntityType", "description": "Category. Omitted when the entity falls outside the supported set." }, "wikipedia_url": { "description": "Wikipedia URL", "type": "string" } }, "required": [ "id", "slug", "name" ], "type": "object" }, "EntityCompany": { "additionalProperties": false, "properties": { "domain": { "description": "Company website domain", "type": "string" }, "id": { "description": "Company identifier", "type": "string" }, "ticker": { "description": "Primary stock ticker symbol", "type": "string" } }, "required": [ "id" ], "type": "object" }, "EntityLookup": { "additionalProperties": false, "properties": { "results": { "description": "One result per unique input identifier, in request order. Duplicate identifiers in the request collapse to a single result.", "items": { "$ref": "#/components/schemas/EntityLookupResult" }, "type": [ "array", "null" ] } }, "required": [ "results" ], "type": "object" }, "EntityLookupMatch": { "additionalProperties": false, "properties": { "company": { "$ref": "#/components/schemas/CompanyCompact", "description": "The matched company. Set when type is 'company'." }, "person": { "$ref": "#/components/schemas/PersonCompact", "description": "The matched person. Set when type is 'person'." }, "type": { "description": "Which kind of entity matched. The corresponding field below is the one that is set.", "enum": [ "person", "company" ], "type": "string" } }, "required": [ "type" ], "type": "object" }, "EntityLookupResult": { "additionalProperties": false, "properties": { "identifier": { "description": "The identifier exactly as supplied in the request, not normalized.", "type": "string" }, "match_count": { "description": "How many distinct entities carry this identifier. Larger than the length of 'matches' when more than 10 do. A count above 1 means the identifier is shared, usually by duplicate records for the same real person — 8.7% of LinkedIn identifiers are.", "format": "int64", "type": "integer" }, "matches": { "description": "The entities carrying this identifier, best first: records linked to a knowledge graph entity come before those without, then oldest first. Empty when the identifier does not resolve.", "items": { "$ref": "#/components/schemas/EntityLookupMatch" }, "type": [ "array", "null" ] }, "platforms": { "description": "The platforms this identifier matched on, alphabetically. Usually one. Several when a handle is the same across platforms and no 'platform' filter was given. Omitted when nothing matched.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, "required": [ "identifier", "matches", "match_count" ], "type": "object" }, "EntityMention": { "additionalProperties": false, "properties": { "end_seconds": { "description": "End time of the last line in seconds", "format": "double", "type": "number" }, "lines": { "description": "Dialogue lines in this context window", "items": { "$ref": "#/components/schemas/EntityMentionLine" }, "type": [ "array", "null" ] }, "start_seconds": { "description": "Start time of the first line in seconds", "format": "double", "type": "number" } }, "required": [ "lines", "start_seconds", "end_seconds" ], "type": "object" }, "EntityMentionLine": { "additionalProperties": false, "properties": { "end_seconds": { "description": "End time in seconds", "format": "double", "type": "number" }, "is_mention": { "description": "Whether this line contains a mention of the target entity", "type": "boolean" }, "matched_terms": { "description": "Mention variants that occur in this line, longest-first, for clients to highlight. Set only on lines with is_mention=true. Each term is spelled as the variant was recorded; a multi-word variant (\"Jason Stark\") matches case-insensitively, so locate it case-insensitively, while a single-token variant matches the line's text exactly — \"US\" is reported for \"US\" but never for \"us\", so acronyms and short names don't highlight their common-word homographs. Whole-token matches only: a variant never matches inside a longer word. Only the longest term is reported at any position, so terms never overlap.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "number": { "description": "Line number (1-indexed)", "format": "int64", "type": "integer" }, "role": { "description": "Speaker role. One of the canonical buckets documented on the episode speakers endpoint (HOST, GUEST, PANELIST, CORRESPONDENT, MODERATOR, NARRATOR, ANNOUNCER, VOICE_ACTOR, SOUNDBITE_SPEAKER, AUDIENCE, ADVERTISER, PRODUCER, UNKNOWN, OTHER).", "type": "string" }, "speaker": { "description": "Speaker name or ID", "type": "string" }, "start_seconds": { "description": "Start time in seconds", "format": "double", "type": "number" }, "text": { "description": "Spoken text", "type": "string" } }, "required": [ "number", "speaker", "start_seconds", "end_seconds", "text", "is_mention" ], "type": "object" }, "EntityMentions": { "additionalProperties": false, "properties": { "news_articles": { "description": "News articles covering this entity — a secondary popularity signal.", "format": "int64", "type": "integer" }, "podcast_episodes": { "description": "Distinct podcast episodes mentioning this entity — the primary popularity signal.", "format": "int64", "type": "integer" } }, "required": [ "podcast_episodes", "news_articles" ], "type": "object" }, "EntityMentionsForEntity": { "additionalProperties": false, "properties": { "entity": { "$ref": "#/components/schemas/EntityCompact", "description": "The knowledge graph entity" }, "mention_variants": { "description": "Distinct mention strings matched (e.g., [\"Donald Trump\", \"Trump\"]).", "items": { "type": "string" }, "type": [ "array", "null" ] }, "mentions": { "description": "Context windows. Each window contains up to 2*context_lines+1 lines around a mention; nearby windows merge into a single window, so multiple is_mention=true lines may appear in one entry.", "items": { "$ref": "#/components/schemas/EntityMention" }, "type": [ "array", "null" ] }, "total_mention_count": { "description": "Unfiltered total: number of dialogue lines containing at least one mention of this entity in the episode. Equals the sum of is_mention=true over the un-paginated mentions[]; independent of which page is requested.", "format": "int64", "type": "integer" } }, "required": [ "entity", "total_mention_count", "mention_variants", "mentions" ], "type": "object" }, "EntityMentionsResponse": { "additionalProperties": false, "properties": { "cursor": { "description": "Pass to the next request to fetch the next page.", "type": "string" }, "entities": { "description": "Entity mention results. One per entity when entity_id is specified, multiple (paginated) when showing all.", "items": { "$ref": "#/components/schemas/EntityMentionsForEntity" }, "type": [ "array", "null" ] }, "episode_id": { "description": "Parent episode ID", "type": "string" }, "has_more": { "description": "When entity_id is set, true if more mention windows exist beyond this page; otherwise true if more entities exist.", "type": "boolean" } }, "required": [ "episode_id", "entities", "has_more" ], "type": "object" }, "EntityPerson": { "additionalProperties": false, "properties": { "company": { "description": "Current company name", "type": "string" }, "id": { "description": "Person identifier", "type": "string" }, "image_url": { "description": "Person headshot URL", "type": "string" }, "title": { "description": "Current role title", "type": "string" } }, "required": [ "id" ], "type": "object" }, "EntitySearchHit": { "additionalProperties": false, "properties": { "company": { "$ref": "#/components/schemas/CompanyCompact", "description": "The matched company (when type is 'company')." }, "knowledge_graph_entity": { "$ref": "#/components/schemas/Entity", "description": "The matched knowledge graph entity (when type is 'knowledge_graph_entity')." }, "match_quality": { "description": "How confidently the result matched the query, strongest to weakest: 'exact' (a name, identifier, or known alias equals the query), 'strong' (every query word is present), 'contained' (the result's whole name appears inside a longer query — the query likely names several things; let the user pick), 'fuzzy' (a typo-tolerant similarity match), 'description' (matched only the description text), 'speculative' (a weak remaining match). Auto-select the top hit on 'exact'; otherwise let the user confirm.", "enum": [ "exact", "strong", "contained", "fuzzy", "description", "speculative" ], "type": "string" }, "mentions": { "$ref": "#/components/schemas/EntityMentions", "description": "Where this entity shows up — both a popularity signal and a cue for confirming the match is the entity you meant." }, "person": { "$ref": "#/components/schemas/PersonCompact", "description": "The matched person (when type is 'person')." }, "social_links": { "description": "Third-party social profiles (people \u0026 companies), with follower counts where known — confirms the match.", "items": { "$ref": "#/components/schemas/EntitySocialLink" }, "type": [ "array", "null" ] }, "type": { "description": "Which kind of result this is, and which embedded field is populated: 'person' → /v1/people, 'company' → /v1/companies, 'knowledge_graph_entity' → /v1/entities.", "enum": [ "person", "company", "knowledge_graph_entity" ], "type": "string" } }, "required": [ "type", "match_quality", "mentions" ], "type": "object" }, "EntitySocialLink": { "additionalProperties": false, "properties": { "followers": { "description": "Audience size where recorded (followers, or subscribers for video platforms); omitted when unknown.", "format": "int64", "type": "integer" }, "platform": { "description": "Platform slug (e.g. 'twitter', 'instagram', 'youtube').", "type": "string" }, "url": { "description": "Profile URL.", "type": "string" } }, "required": [ "platform", "url" ], "type": "object" }, "EntityType": { "additionalProperties": false, "properties": { "name": { "description": "Human-friendly display label (e.g. 'Company').", "type": "string" }, "slug": { "description": "Stable identifier, safe to pass to the type query parameter (e.g. 'company').", "type": "string" } }, "required": [ "slug", "name" ], "type": "object" }, "Episode": { "additionalProperties": false, "properties": { "ads": { "description": "Advertising spots detected in the episode, in playback order. Only present when include=ads (or include=all) is requested at the fully_ingested milestone, and in episode archive records.", "items": { "$ref": "#/components/schemas/EpisodeAd" }, "type": [ "array", "null" ] }, "audio_url": { "description": "Direct audio stream URL", "type": "string" }, "clip_count": { "description": "Number of AI-extracted clips", "format": "int64", "type": "integer" }, "clips": { "description": "AI-extracted clips. Only present when include=clips (or include=all) is requested at the fully_ingested milestone.", "items": { "$ref": "#/components/schemas/Clip" }, "type": [ "array", "null" ] }, "description": { "description": "Episode description", "type": "string" }, "duration_seconds": { "description": "Episode duration in seconds", "format": "double", "type": "number" }, "entities": { "description": "Knowledge graph entities discussed in the episode, most salient first, with the transcript lines that mention each. Only present when include=entities (or include=all) is requested at the fully_ingested milestone, and in episode archive records.", "items": { "$ref": "#/components/schemas/EpisodeEntity" }, "type": [ "array", "null" ] }, "entity_count": { "description": "Number of mentioned entities", "format": "int64", "type": "integer" }, "episode_number": { "description": "Episode number in the series", "format": "int64", "type": "integer" }, "explicit": { "description": "Whether the episode contains explicit content", "type": "boolean" }, "has_transcript": { "description": "Whether a transcript is available", "type": "boolean" }, "id": { "description": "Unique identifier", "type": "string" }, "image_url": { "description": "Episode artwork URL", "type": "string" }, "language": { "description": "ISO 639-1 language code", "type": "string" }, "podcast": { "$ref": "#/components/schemas/PodcastCompact", "description": "Parent podcast" }, "published_at": { "description": "Publication date", "format": "date-time", "type": "string" }, "segment_count": { "description": "Number of AI-identified segments", "format": "int64", "type": "integer" }, "segments": { "description": "AI-identified segments. Only present when include=segments (or include=all) is requested at a milestone of segmented or later.", "items": { "$ref": "#/components/schemas/Segment" }, "type": [ "array", "null" ] }, "slug": { "description": "Human-readable slug identifier", "type": "string" }, "speakers": { "description": "Speakers in this episode", "items": { "$ref": "#/components/schemas/EpisodeSpeaker" }, "type": [ "array", "null" ] }, "title": { "description": "Episode title", "type": "string" }, "topics": { "description": "Topic classifications", "items": { "$ref": "#/components/schemas/Topic" }, "type": [ "array", "null" ] }, "transcript": { "$ref": "#/components/schemas/DialogueTranscriptResponse", "description": "Dialogue transcript. Only present when include=transcript (or include=all) is requested at a milestone of transcribed or later." }, "transcript_status": { "description": "Where the episode stands on the way to a transcript. transcribed: the transcript is available. processing: we are transcribing it, or retrying after a failure. queued: a back-catalogue episode whose transcript has been requested and is waiting to be transcribed. requestable: a discovered back-catalogue episode we have not transcribed. unavailable: it can never be transcribed, for example because its audio no longer exists.", "enum": [ "transcribed", "processing", "queued", "requestable", "unavailable" ], "type": "string" }, "url": { "description": "Episode web URL", "type": "string" }, "videos": { "description": "Video URLs discovered for this episode (native enclosures, Podcasting 2.0 alternate enclosures, Media RSS, and platform links / show-note URLs from YouTube, Vimeo, Twitch, Rumble). Populated on the GET /podcasts/episodes/{id} endpoint.", "items": { "$ref": "#/components/schemas/EpisodeVideo" }, "type": [ "array", "null" ] } }, "required": [ "id", "title", "explicit", "duration_seconds", "has_transcript", "transcript_status" ], "type": "object" }, "EpisodeAd": { "additionalProperties": false, "properties": { "company_id": { "description": "The sponsor's company, when linked: the identifier GET /v1/companies/{id} takes (its domain, slug or encoded ID). Fetch its current profile there.", "type": "string" }, "duration_seconds": { "description": "Ad duration in seconds", "format": "double", "type": "number" }, "end_seconds": { "description": "Ad end offset within the episode, in seconds", "format": "double", "type": "number" }, "id": { "description": "Unique identifier", "type": "string" }, "offer_description": { "description": "Promotional offer details", "type": "string" }, "placement_type": { "description": "Where the ad appeared in the episode (PRE_ROLL, MID_ROLL, POST_ROLL)", "type": "string" }, "product": { "description": "Advertised product or service", "type": "string" }, "read_type": { "description": "How the ad was delivered (HOST_READ, PRE_RECORDED, NETWORK_PROMO)", "type": "string" }, "sponsor_id": { "description": "Linked sponsor ID, when known", "type": "string" }, "sponsor_name": { "description": "Name of the advertising sponsor", "type": "string" }, "sponsor_url": { "description": "Sponsor website URL", "type": "string" }, "start_seconds": { "description": "Ad start offset within the episode, in seconds", "format": "double", "type": "number" } }, "required": [ "id", "sponsor_name", "read_type", "start_seconds", "end_seconds", "duration_seconds" ], "type": "object" }, "EpisodeArchive": { "additionalProperties": false, "properties": { "as_of": { "description": "The archive holds every episode change recorded up to this time. null until the archive's first full build completes.", "format": "date-time", "type": [ "string", "null" ] }, "months": { "description": "Months with archived episodes, oldest first.", "items": { "$ref": "#/components/schemas/EpisodeArchiveMonth" }, "type": [ "array", "null" ] }, "stream_since": { "description": "Pass this as since= to GET /v1/podcasts/episodes/stream to pick up where the archive leaves off. Some episodes will arrive twice; deduplicate on the episode id. null until the archive's first full build completes.", "format": "date-time", "type": [ "string", "null" ] } }, "required": [ "as_of", "stream_since", "months" ], "type": "object" }, "EpisodeArchiveComplete": { "additionalProperties": false, "properties": { "episodes": { "description": "Episodes sent by this connection.", "format": "int64", "type": "integer" }, "period": { "description": "The period replayed.", "type": "string" } }, "required": [ "period", "episodes" ], "type": "object" }, "EpisodeArchiveDay": { "additionalProperties": false, "properties": { "bytes": { "description": "Size of the day's download, gzipped.", "format": "int64", "type": "integer" }, "date": { "description": "The day, YYYY-MM-DD, by UTC publication date.", "examples": [ "2026-09-29" ], "type": "string" }, "episodes": { "description": "Episodes in the day. 0 means the day no longer has any; remove your copy.", "format": "int64", "type": "integer" }, "updated_at": { "description": "The as_of at which the day's content last changed. Compare it with the as_of of your last sync.", "format": "date-time", "type": "string" }, "version": { "description": "Changes whenever the day's content changes. It is the download's ETag.", "type": "string" } }, "required": [ "date", "episodes", "bytes", "version", "updated_at" ], "type": "object" }, "EpisodeArchiveMonth": { "additionalProperties": false, "properties": { "bytes": { "description": "Size of the whole month's download, gzipped.", "format": "int64", "type": "integer" }, "days": { "description": "The month's days. With updated_since, only the days that changed.", "items": { "$ref": "#/components/schemas/EpisodeArchiveDay" }, "type": [ "array", "null" ] }, "episodes": { "description": "Episodes in the whole month.", "format": "int64", "type": "integer" }, "month": { "description": "The month, YYYY-MM, by UTC publication date.", "examples": [ "2026-09" ], "type": "string" }, "updated_at": { "description": "The as_of at which the month's content last changed. Compare it with the as_of of your last sync.", "format": "date-time", "type": "string" }, "version": { "description": "Changes whenever any day of the month changes. It is the download's ETag.", "type": "string" } }, "required": [ "month", "episodes", "bytes", "version", "updated_at", "days" ], "type": "object" }, "EpisodeCompact": { "additionalProperties": false, "properties": { "clip_count": { "description": "Number of clips", "format": "int64", "type": "integer" }, "duration_seconds": { "description": "Duration in seconds", "format": "double", "type": "number" }, "has_transcript": { "description": "Whether a transcript is available", "type": "boolean" }, "id": { "description": "Episode ID", "type": "string" }, "published_at": { "description": "Publication date", "format": "date-time", "type": "string" }, "segment_count": { "description": "Number of segments", "format": "int64", "type": "integer" }, "slug": { "description": "Human-readable slug identifier", "type": "string" }, "title": { "description": "Episode title", "type": "string" }, "transcript_status": { "description": "Where the episode stands on the way to a transcript; see Episode.transcript_status.", "enum": [ "transcribed", "processing", "queued", "requestable", "unavailable" ], "type": "string" } }, "required": [ "id", "title", "duration_seconds", "has_transcript", "transcript_status" ], "type": "object" }, "EpisodeCompactWithPodcast": { "additionalProperties": false, "properties": { "id": { "description": "Episode ID", "type": "string" }, "podcast": { "$ref": "#/components/schemas/PodcastCompact", "description": "Parent podcast" }, "published_at": { "description": "Publication date", "format": "date-time", "type": "string" }, "slug": { "description": "Human-readable slug identifier", "type": "string" }, "title": { "description": "Episode title", "type": "string" } }, "required": [ "id", "title" ], "type": "object" }, "EpisodeEmbedCode": { "additionalProperties": false, "properties": { "embed_html": { "description": "Full \u003cparticle-podcast-clip\u003e HTML snippet ready to paste", "type": "string" }, "script_url": { "description": "Inner widget script URL (the \u003cscript src\u003e value)", "type": "string" }, "variant": { "description": "Which embed variant was generated", "enum": [ "clip", "episode-clip" ], "type": "string" } }, "required": [ "embed_html", "script_url", "variant" ], "type": "object" }, "EpisodeEntity": { "additionalProperties": false, "properties": { "entity": { "$ref": "#/components/schemas/EntityCompact", "description": "The knowledge graph entity" }, "mention_lines": { "description": "Numbers of the transcript lines (transcript.lines[].number) that mention the entity, by its name or by a form extraction recognized for it, ascending. Absent when no line does.", "items": { "format": "int64", "type": "integer" }, "type": [ "array", "null" ] }, "occurrences": { "description": "Number of mentions in the episode", "format": "int64", "type": "integer" }, "salience": { "description": "Importance score for the entity within the episode. When salience metadata is available, this is a percentile rank in (0.0, 1.0) — 0.95 means more salient than 95% of other entities mentioned, and the top entity approaches but never reaches 1.0. A value of 0.0 indicates the salience is unknown or unavailable.", "format": "double", "type": "number" } }, "required": [ "entity", "salience", "occurrences" ], "type": "object" }, "EpisodeEntityAppearance": { "additionalProperties": false, "properties": { "entity": { "$ref": "#/components/schemas/EntityCompact", "description": "The knowledge graph entity" }, "occurrences": { "description": "Number of mentions in the episode", "format": "int64", "type": "integer" }, "salience": { "description": "Importance score for the entity within the episode. When salience metadata is available, this is a percentile rank in (0.0, 1.0) — 0.95 means more salient than 95% of other entities mentioned, and the top entity approaches but never reaches 1.0. A value of 0.0 indicates the salience is unknown or unavailable.", "format": "double", "type": "number" } }, "required": [ "entity", "salience", "occurrences" ], "type": "object" }, "EpisodeLookup": { "additionalProperties": false, "properties": { "results": { "description": "One result per unique input identifier, in request order", "items": { "$ref": "#/components/schemas/EpisodeLookupResult" }, "type": [ "array", "null" ] } }, "required": [ "results" ], "type": "object" }, "EpisodeLookupResult": { "additionalProperties": false, "properties": { "episode": { "$ref": "#/components/schemas/LookedUpEpisode", "description": "The matched episode, with its parent podcast. Omitted when the identifier does not resolve to any episode we know of — callers should test for key presence rather than null. A discovered back-catalogue episode resolves too, with transcript_status requestable." }, "identifier": { "description": "The platform-native identifier as supplied in the request", "type": "string" } }, "required": [ "identifier" ], "type": "object" }, "EpisodeSpeaker": { "additionalProperties": false, "properties": { "description": { "description": "Brief description of the speaker", "type": "string" }, "descriptor": { "description": "Movie-credits-style role-in-context label for speakers we can describe but not identify by name (\"Taylor's Lawyer\", \"Court Officer\"). Co-exists with name carrying the raw STT label when no identity could be established. Rendered by clients when descriptor is non-empty and the speaker is otherwise unresolved.", "type": "string" }, "entity": { "$ref": "#/components/schemas/EntityCompact", "description": "Linked knowledge graph entity, when this speaker is identified" }, "name": { "description": "Speaker name", "type": "string" }, "person": { "$ref": "#/components/schemas/PersonCompact", "description": "Linked first-class Person, when the speaker has been resolved to a row in /v1/people" }, "role": { "description": "Speaker role, always one of HOST, GUEST, PANELIST, CORRESPONDENT, MODERATOR, NARRATOR, ANNOUNCER, VOICE_ACTOR, SOUNDBITE_SPEAKER, AUDIENCE, ADVERTISER, PRODUCER, UNKNOWN, OTHER. Responses carry only HOST, GUEST, PANELIST and CORRESPONDENT unless you widen the set with the role query param.", "type": "string" }, "speaking_duration_seconds": { "description": "Total speaking time in seconds", "format": "double", "type": "number" } }, "required": [ "name" ], "type": "object" }, "EpisodeStats": { "additionalProperties": false, "properties": { "added": { "description": "Episodes added to the catalog within each trailing window.", "items": { "$ref": "#/components/schemas/WindowCount" }, "type": [ "array", "null" ] }, "totals": { "description": "The corpus by transcript_status: the episodes we have transcribed, and the episodes in podcasts' back catalogues we have discovered but not yet transcribed and whose audio we can transcribe. Episodes in other statuses (processing, queued, unavailable) are not counted here; a podcast's coverage counts every status. Refreshed hourly; see totals_counted_at.", "items": { "$ref": "#/components/schemas/CorpusEpisodeCount" }, "type": [ "array", "null" ] }, "totals_counted_at": { "description": "When totals were computed. Absent before they have first been counted.", "format": "date-time", "type": "string" } }, "required": [ "added", "totals" ], "type": "object" }, "EpisodeStreamEvent": { "additionalProperties": false, "properties": { "cursor": { "type": "string" }, "episode": { "$ref": "#/components/schemas/Episode" }, "milestone": { "type": "string" } }, "required": [ "milestone", "cursor", "episode" ], "type": "object" }, "EpisodeTimeseries": { "additionalProperties": false, "properties": { "buckets": { "description": "Contiguous zero-filled buckets in ascending order", "items": { "$ref": "#/components/schemas/EpisodeTimeseriesBucket" }, "type": [ "array", "null" ] }, "distinct_podcasts": { "description": "Distinct podcasts those episodes belong to", "format": "int64", "type": "integer" }, "end": { "description": "UTC date of the range's exclusive upper bound. When the bound falls inside a day, such as the default of now, episodes on this date up to the bound are still counted.", "type": "string" }, "interval": { "description": "Bucket width", "enum": [ "day", "week", "month" ], "type": "string" }, "start": { "description": "Start of the first bucket as a UTC date", "type": "string" }, "total_episodes": { "description": "Distinct episodes matching the filters in the range", "format": "int64", "type": "integer" }, "total_mentions": { "description": "Transcript segments matching keyword_search or semantic_search across the range. Present only when one of them is set.", "format": "int64", "type": "integer" } }, "required": [ "interval", "total_episodes", "distinct_podcasts", "buckets" ], "type": "object" }, "EpisodeTimeseriesBucket": { "additionalProperties": false, "properties": { "count": { "description": "Distinct episodes matching the filters in this bucket", "format": "int64", "type": "integer" }, "mention_count": { "description": "Transcript segments matching keyword_search or semantic_search in this bucket. Present only when one of them is set.", "format": "int64", "type": "integer" }, "start": { "description": "Bucket start as a UTC date", "type": "string" } }, "required": [ "start", "count" ], "type": "object" }, "EpisodeVideo": { "additionalProperties": false, "properties": { "duration_seconds": { "description": "Video duration in seconds when known", "format": "int64", "type": "integer" }, "height": { "description": "Frame height in pixels when known", "format": "int64", "type": "integer" }, "mime_type": { "description": "MIME type when known (e.g. video/mp4)", "type": "string" }, "platform": { "description": "Hosting platform. native denotes a direct media file served from the podcaster's own infrastructure; other is the fallback when we know the URL is video but don't have a platform-specific handler.", "enum": [ "youtube", "vimeo", "twitch", "rumble", "tiktok", "native", "other" ], "type": "string" }, "url": { "description": "Video URL", "type": "string" }, "width": { "description": "Frame width in pixels when known", "format": "int64", "type": "integer" } }, "required": [ "url" ], "type": "object" }, "ErrorDetail": { "additionalProperties": false, "properties": { "location": { "description": "Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id'", "type": "string" }, "message": { "description": "Error message text", "type": "string" }, "value": { "description": "The value at the given location" } }, "type": "object" }, "ErrorResolve": { "additionalProperties": false, "properties": { "action": { "type": "string" }, "endpoint": { "type": "string" }, "message": { "type": "string" }, "method": { "type": "string" }, "url": { "type": "string" } }, "required": [ "message" ], "type": "object" }, "ExternalLink": { "additionalProperties": false, "properties": { "attributes": { "description": "Optional platform-specific metadata: audience size, profile fields, account status, and related signals. The set varies by platform and grows over time — clients should treat unknown attribute names as additive.", "items": { "$ref": "#/components/schemas/ExternalLinkAttribute" }, "type": [ "array", "null" ] }, "identifier": { "description": "Platform-native identifier (numeric id, slug, handle, or full URL). Empty for the 'website' platform, where the URL is the canonical reference.", "type": "string" }, "platform": { "$ref": "#/components/schemas/ExternalLinkPlatform", "description": "Platform metadata: machine name, display name, and broad type." }, "url": { "description": "Resolved web URL for this presence. Built from the identifier via a per-platform template, or passed through for 'website'.", "type": "string" } }, "required": [ "platform" ], "type": "object" }, "ExternalLinkAttribute": { "additionalProperties": false, "properties": { "category": { "description": "Broad grouping for the attribute. Today's known values are audience_size, content, profile, and account_status — the set is open and may grow without a versioning event, so clients should treat unrecognised categories as additive rather than invalid.", "type": "string" }, "name": { "description": "Platform-native attribute name (e.g. 'subscribers', 'followers', 'views', 'handle'). Vocabulary varies by platform; use Category to group related attributes if you don't recognise the Name.", "type": "string" }, "observed_at": { "description": "When this attribute was last observed from the upstream source. Omitted when unavailable.", "format": "date-time", "type": "string" }, "value": { "description": "Attribute value. JSON type matches the Category: numbers for audience_size/content, strings for profile/account_status (with bool for flags). Null when the underlying source is unset." } }, "required": [ "name", "value" ], "type": "object" }, "ExternalLinkPlatform": { "additionalProperties": false, "properties": { "display_name": { "description": "Human-readable name suitable for UI display (e.g. 'Apple Podcasts', 'X (Twitter)').", "type": "string" }, "name": { "description": "Stable machine name (e.g. 'spotify', 'youtube', 'twitter'). Suitable for filtering or routing on the client.", "type": "string" }, "type": { "description": "Broad category for the platform. Use this to group presences in a UI rather than enumerating every Name.", "enum": [ "podcast_directory", "music_service", "social_profile", "video_channel", "community", "website", "other" ], "type": "string" } }, "required": [ "name", "display_name", "type" ], "type": "object" }, "Genre": { "additionalProperties": false, "properties": { "external_id": { "description": "Source-native genre id.", "type": "string" }, "name": { "description": "Display name of the genre.", "type": "string" } }, "required": [ "external_id", "name" ], "type": "object" }, "GetAlertPreviewResponseBody": { "additionalProperties": false, "properties": { "by_day": { "description": "Per-day match count over the window (UTC dates), oldest day first.", "items": { "$ref": "#/components/schemas/AlertPreviewBucketResponse" }, "type": [ "array", "null" ] }, "completed_at": { "description": "Set once status is completed or failed.", "format": "date-time", "type": "string" }, "error": { "description": "Set only when status is failed; safe to surface to the user.", "type": "string" }, "sample": { "description": "Up to AlertPreviewSampleSize most-recent matches with payload fully hydrated. Empty until status is completed.", "items": { "$ref": "#/components/schemas/AlertMatch" }, "type": [ "array", "null" ] }, "started_at": { "format": "date-time", "type": "string" }, "status": { "description": "State of the sweep. Clients should poll until the value is 'completed' or 'failed' (TTL 1h).", "enum": [ "in_progress", "completed", "failed" ], "type": "string" }, "total_matches": { "format": "int64", "type": "integer" }, "window_days": { "format": "int64", "type": "integer" } }, "required": [ "status", "window_days", "started_at", "total_matches" ], "type": "object" }, "InitiateSlackConnectionBody": { "additionalProperties": false, "properties": { "redirect_url": { "description": "URL on the calling surface (platform.particle.pro / radar.particle.pro) to redirect the user's browser to after the OAuth dance completes. Must match the calling surface's host.", "maxLength": 2000, "minLength": 1, "type": "string" } }, "required": [ "redirect_url" ], "type": "object" }, "InitiateSlackConnectionResponseBody": { "additionalProperties": false, "properties": { "authorize_url": { "type": "string" } }, "required": [ "authorize_url" ], "type": "object" }, "KnowledgeGraphEntityLink": { "additionalProperties": false, "properties": { "id": { "description": "Knowledge graph entity identifier", "type": "string" }, "slug": { "description": "Knowledge graph entity slug", "type": "string" }, "wikipedia_url": { "description": "Wikipedia URL associated with the KGE, when one is recorded", "type": "string" } }, "required": [ "id" ], "type": "object" }, "LeaderboardEntryV1": { "additionalProperties": false, "properties": { "rank": { "description": "Position in the leaderboard", "format": "int64", "type": "integer" }, "sponsor": { "$ref": "#/components/schemas/Sponsor", "description": "Sponsor with activity metrics" } }, "required": [ "rank", "sponsor" ], "type": "object" }, "LeaderboardPreviewEntry": { "additionalProperties": false, "properties": { "movement": { "description": "Movement since the 7-day window ending 30 days ago.", "enum": [ "new", "up", "down", "flat" ], "type": "string" }, "previous_rank": { "description": "Position in the 7-day window ending 30 days ago. Null when the sponsor was not in that window's top 50.", "format": "int64", "type": "integer" }, "rank": { "description": "Position in the leaderboard", "format": "int64", "type": "integer" }, "rank_change": { "description": "Positions climbed since the 7-day window ending 30 days ago, negative when the sponsor fell. Zero for both a flat hold and a debut. Read 'movement' to tell those apart.", "format": "int64", "type": "integer" }, "sponsor": { "$ref": "#/components/schemas/Sponsor", "description": "Sponsor with activity metrics" } }, "required": [ "movement", "rank_change", "rank", "sponsor" ], "type": "object" }, "ListSlackConnectionChannelsResponseBody": { "additionalProperties": false, "properties": { "data": { "items": { "$ref": "#/components/schemas/PlatformSlackChannel" }, "type": [ "array", "null" ] } }, "required": [ "data" ], "type": "object" }, "ListSlackConnectionsResponseBody": { "additionalProperties": false, "properties": { "data": { "items": { "$ref": "#/components/schemas/PlatformSlackConnection" }, "type": [ "array", "null" ] } }, "required": [ "data" ], "type": "object" }, "ListWebhookConnectionsResponseBody": { "additionalProperties": false, "properties": { "data": { "items": { "$ref": "#/components/schemas/PlatformWebhookConnection" }, "type": [ "array", "null" ] } }, "required": [ "data" ], "type": "object" }, "LookedUpEpisode": { "additionalProperties": false, "properties": { "has_transcript": { "description": "Whether a transcript is available", "type": "boolean" }, "id": { "description": "Episode ID", "type": "string" }, "podcast": { "$ref": "#/components/schemas/PodcastCompact", "description": "Parent podcast" }, "published_at": { "description": "Publication date", "format": "date-time", "type": "string" }, "slug": { "description": "Human-readable slug identifier", "type": "string" }, "title": { "description": "Episode title", "type": "string" }, "transcript_status": { "description": "Where the episode stands on the way to a transcript; see Episode.transcript_status.", "enum": [ "transcribed", "processing", "queued", "requestable", "unavailable" ], "type": "string" } }, "required": [ "has_transcript", "transcript_status", "id", "title" ], "type": "object" }, "MatchMetadata": { "additionalProperties": false, "properties": { "relevance_score": { "description": "Raw relevance score from the underlying ranker. For semantic this is cosine similarity in [-1, 1] (typically 0..1). For keyword this is the BM25 score (unbounded, higher = better). For hybrid this is the reciprocal-rank-fusion score (small positive number, higher = better). Compare scores within a single response, not across queries.", "format": "double", "type": "number" }, "source": { "description": "Which ranking signal produced this result: semantic | keyword | hybrid", "type": "string" } }, "required": [ "source" ], "type": "object" }, "MentionTimeseries": { "additionalProperties": false, "properties": { "buckets": { "description": "Contiguous zero-filled buckets in ascending order", "items": { "$ref": "#/components/schemas/MentionTimeseriesBucket" }, "type": [ "array", "null" ] }, "company": { "$ref": "#/components/schemas/CompanyCompact", "description": "The resolved company, when company_id was used" }, "distinct_podcasts": { "description": "Distinct podcasts those episodes aired on", "format": "int64", "type": "integer" }, "end": { "description": "UTC date of the range's exclusive upper bound. When the bound falls inside a day, such as the default of now, mentions on this date up to the bound are still counted.", "type": "string" }, "entity": { "$ref": "#/components/schemas/EntityCompact", "description": "The resolved entity the counts are for" }, "interval": { "description": "Bucket width", "enum": [ "day", "week", "month" ], "type": "string" }, "start": { "description": "Start of the first bucket as a UTC date", "type": "string" }, "total_episodes": { "description": "Episodes with at least one counted mention in the range", "format": "int64", "type": "integer" }, "total_mentions": { "description": "Counted mention lines across those episodes", "format": "int64", "type": "integer" } }, "required": [ "interval", "total_episodes", "total_mentions", "distinct_podcasts", "buckets" ], "type": "object" }, "MentionTimeseriesBucket": { "additionalProperties": false, "properties": { "episode_count": { "description": "Episodes with at least one counted mention in this bucket", "format": "int64", "type": "integer" }, "mention_count": { "description": "Counted mention lines in this bucket", "format": "int64", "type": "integer" }, "start": { "description": "Bucket start as a UTC date", "type": "string" } }, "required": [ "start", "episode_count", "mention_count" ], "type": "object" }, "PageAdDetail": { "additionalProperties": false, "properties": { "cursor": { "description": "Pass to next request for more results", "type": "string" }, "data": { "description": "List of results", "items": { "$ref": "#/components/schemas/AdDetail" }, "type": [ "array", "null" ] }, "has_more": { "description": "Whether more results exist", "type": "boolean" } }, "required": [ "data", "has_more" ], "type": "object" }, "PageAlert": { "additionalProperties": false, "properties": { "cursor": { "description": "Pass to next request for more results", "type": "string" }, "data": { "description": "List of results", "items": { "$ref": "#/components/schemas/Alert" }, "type": [ "array", "null" ] }, "has_more": { "description": "Whether more results exist", "type": "boolean" } }, "required": [ "data", "has_more" ], "type": "object" }, "PageAlertDelivery": { "additionalProperties": false, "properties": { "cursor": { "description": "Pass to next request for more results", "type": "string" }, "data": { "description": "List of results", "items": { "$ref": "#/components/schemas/AlertDelivery" }, "type": [ "array", "null" ] }, "has_more": { "description": "Whether more results exist", "type": "boolean" } }, "required": [ "data", "has_more" ], "type": "object" }, "PageAlertMatch": { "additionalProperties": false, "properties": { "cursor": { "description": "Pass to next request for more results", "type": "string" }, "data": { "description": "List of results", "items": { "$ref": "#/components/schemas/AlertMatch" }, "type": [ "array", "null" ] }, "has_more": { "description": "Whether more results exist", "type": "boolean" } }, "required": [ "data", "has_more" ], "type": "object" }, "PageBiasPodcastPublisherEntry": { "additionalProperties": false, "properties": { "cursor": { "description": "Pass to next request for more results", "type": "string" }, "data": { "description": "List of results", "items": { "$ref": "#/components/schemas/BiasPodcastPublisherEntry" }, "type": [ "array", "null" ] }, "has_more": { "description": "Whether more results exist", "type": "boolean" } }, "required": [ "data", "has_more" ], "type": "object" }, "PageClip": { "additionalProperties": false, "properties": { "cursor": { "description": "Pass to next request for more results", "type": "string" }, "data": { "description": "List of results", "items": { "$ref": "#/components/schemas/Clip" }, "type": [ "array", "null" ] }, "has_more": { "description": "Whether more results exist", "type": "boolean" } }, "required": [ "data", "has_more" ], "type": "object" }, "PageCoOccurrenceEntry": { "additionalProperties": false, "properties": { "cursor": { "description": "Pass to next request for more results", "type": "string" }, "data": { "description": "List of results", "items": { "$ref": "#/components/schemas/CoOccurrenceEntry" }, "type": [ "array", "null" ] }, "has_more": { "description": "Whether more results exist", "type": "boolean" } }, "required": [ "data", "has_more" ], "type": "object" }, "PageCompany": { "additionalProperties": false, "properties": { "cursor": { "description": "Pass to next request for more results", "type": "string" }, "data": { "description": "List of results", "items": { "$ref": "#/components/schemas/Company" }, "type": [ "array", "null" ] }, "has_more": { "description": "Whether more results exist", "type": "boolean" } }, "required": [ "data", "has_more" ], "type": "object" }, "PageCompanyAdvertisingPlacement": { "additionalProperties": false, "properties": { "cursor": { "description": "Pass to next request for more results", "type": "string" }, "data": { "description": "List of results", "items": { "$ref": "#/components/schemas/CompanyAdvertisingPlacement" }, "type": [ "array", "null" ] }, "has_more": { "description": "Whether more results exist", "type": "boolean" } }, "required": [ "data", "has_more" ], "type": "object" }, "PageCompanyProduct": { "additionalProperties": false, "properties": { "cursor": { "description": "Pass to next request for more results", "type": "string" }, "data": { "description": "List of results", "items": { "$ref": "#/components/schemas/CompanyProduct" }, "type": [ "array", "null" ] }, "has_more": { "description": "Whether more results exist", "type": "boolean" } }, "required": [ "data", "has_more" ], "type": "object" }, "PageCompetitor": { "additionalProperties": false, "properties": { "cursor": { "description": "Pass to next request for more results", "type": "string" }, "data": { "description": "List of results", "items": { "$ref": "#/components/schemas/Competitor" }, "type": [ "array", "null" ] }, "has_more": { "description": "Whether more results exist", "type": "boolean" } }, "required": [ "data", "has_more" ], "type": "object" }, "PageEntity": { "additionalProperties": false, "properties": { "cursor": { "description": "Pass to next request for more results", "type": "string" }, "data": { "description": "List of results", "items": { "$ref": "#/components/schemas/Entity" }, "type": [ "array", "null" ] }, "has_more": { "description": "Whether more results exist", "type": "boolean" } }, "required": [ "data", "has_more" ], "type": "object" }, "PageEntityChartSummary": { "additionalProperties": false, "properties": { "cursor": { "description": "Pass to next request for more results", "type": "string" }, "data": { "description": "List of results", "items": { "$ref": "#/components/schemas/EntityChartSummary" }, "type": [ "array", "null" ] }, "has_more": { "description": "Whether more results exist", "type": "boolean" } }, "required": [ "data", "has_more" ], "type": "object" }, "PageEntitySearchHit": { "additionalProperties": false, "properties": { "cursor": { "description": "Pass to next request for more results", "type": "string" }, "data": { "description": "List of results", "items": { "$ref": "#/components/schemas/EntitySearchHit" }, "type": [ "array", "null" ] }, "has_more": { "description": "Whether more results exist", "type": "boolean" } }, "required": [ "data", "has_more" ], "type": "object" }, "PageEntityType": { "additionalProperties": false, "properties": { "cursor": { "description": "Pass to next request for more results", "type": "string" }, "data": { "description": "List of results", "items": { "$ref": "#/components/schemas/EntityType" }, "type": [ "array", "null" ] }, "has_more": { "description": "Whether more results exist", "type": "boolean" } }, "required": [ "data", "has_more" ], "type": "object" }, "PageEpisode": { "additionalProperties": false, "properties": { "cursor": { "description": "Pass to next request for more results", "type": "string" }, "data": { "description": "List of results", "items": { "$ref": "#/components/schemas/Episode" }, "type": [ "array", "null" ] }, "has_more": { "description": "Whether more results exist", "type": "boolean" } }, "required": [ "data", "has_more" ], "type": "object" }, "PageEpisodeEntityAppearance": { "additionalProperties": false, "properties": { "cursor": { "description": "Pass to next request for more results", "type": "string" }, "data": { "description": "List of results", "items": { "$ref": "#/components/schemas/EpisodeEntityAppearance" }, "type": [ "array", "null" ] }, "has_more": { "description": "Whether more results exist", "type": "boolean" } }, "required": [ "data", "has_more" ], "type": "object" }, "PageEpisodeSpeaker": { "additionalProperties": false, "properties": { "cursor": { "description": "Pass to next request for more results", "type": "string" }, "data": { "description": "List of results", "items": { "$ref": "#/components/schemas/EpisodeSpeaker" }, "type": [ "array", "null" ] }, "has_more": { "description": "Whether more results exist", "type": "boolean" } }, "required": [ "data", "has_more" ], "type": "object" }, "PageExternalLink": { "additionalProperties": false, "properties": { "cursor": { "description": "Pass to next request for more results", "type": "string" }, "data": { "description": "List of results", "items": { "$ref": "#/components/schemas/ExternalLink" }, "type": [ "array", "null" ] }, "has_more": { "description": "Whether more results exist", "type": "boolean" } }, "required": [ "data", "has_more" ], "type": "object" }, "PageLeaderboardEntryV1": { "additionalProperties": false, "properties": { "cursor": { "description": "Pass to next request for more results", "type": "string" }, "data": { "description": "List of results", "items": { "$ref": "#/components/schemas/LeaderboardEntryV1" }, "type": [ "array", "null" ] }, "has_more": { "description": "Whether more results exist", "type": "boolean" } }, "required": [ "data", "has_more" ], "type": "object" }, "PageLeaderboardPreviewEntry": { "additionalProperties": false, "properties": { "cursor": { "description": "Pass to next request for more results", "type": "string" }, "data": { "description": "List of results", "items": { "$ref": "#/components/schemas/LeaderboardPreviewEntry" }, "type": [ "array", "null" ] }, "has_more": { "description": "Whether more results exist", "type": "boolean" } }, "required": [ "data", "has_more" ], "type": "object" }, "PagePerson": { "additionalProperties": false, "properties": { "cursor": { "description": "Pass to next request for more results", "type": "string" }, "data": { "description": "List of results", "items": { "$ref": "#/components/schemas/Person" }, "type": [ "array", "null" ] }, "has_more": { "description": "Whether more results exist", "type": "boolean" } }, "required": [ "data", "has_more" ], "type": "object" }, "PagePodcast": { "additionalProperties": false, "properties": { "cursor": { "description": "Pass to next request for more results", "type": "string" }, "data": { "description": "List of results", "items": { "$ref": "#/components/schemas/Podcast" }, "type": [ "array", "null" ] }, "has_more": { "description": "Whether more results exist", "type": "boolean" } }, "required": [ "data", "has_more" ], "type": "object" }, "PagePodcastBiasEntry": { "additionalProperties": false, "properties": { "cursor": { "description": "Pass to next request for more results", "type": "string" }, "data": { "description": "List of results", "items": { "$ref": "#/components/schemas/PodcastBiasEntry" }, "type": [ "array", "null" ] }, "has_more": { "description": "Whether more results exist", "type": "boolean" } }, "required": [ "data", "has_more" ], "type": "object" }, "PagePodcastGuestAppearance": { "additionalProperties": false, "properties": { "cursor": { "description": "Pass to next request for more results", "type": "string" }, "data": { "description": "List of results", "items": { "$ref": "#/components/schemas/PodcastGuestAppearance" }, "type": [ "array", "null" ] }, "has_more": { "description": "Whether more results exist", "type": "boolean" } }, "required": [ "data", "has_more" ], "type": "object" }, "PagePodcastGuestCompact": { "additionalProperties": false, "properties": { "cursor": { "description": "Pass to next request for more results", "type": "string" }, "data": { "description": "List of results", "items": { "$ref": "#/components/schemas/PodcastGuestCompact" }, "type": [ "array", "null" ] }, "has_more": { "description": "Whether more results exist", "type": "boolean" } }, "required": [ "data", "has_more" ], "type": "object" }, "PagePodcastGuestPodcast": { "additionalProperties": false, "properties": { "cursor": { "description": "Pass to next request for more results", "type": "string" }, "data": { "description": "List of results", "items": { "$ref": "#/components/schemas/PodcastGuestPodcast" }, "type": [ "array", "null" ] }, "has_more": { "description": "Whether more results exist", "type": "boolean" } }, "required": [ "data", "has_more" ], "type": "object" }, "PagePodcastGuestTrend": { "additionalProperties": false, "properties": { "cursor": { "description": "Pass to next request for more results", "type": "string" }, "data": { "description": "List of results", "items": { "$ref": "#/components/schemas/PodcastGuestTrend" }, "type": [ "array", "null" ] }, "has_more": { "description": "Whether more results exist", "type": "boolean" } }, "required": [ "data", "has_more" ], "type": "object" }, "PagePodcastMention": { "additionalProperties": false, "properties": { "cursor": { "description": "Pass to next request for more results", "type": "string" }, "data": { "description": "List of results", "items": { "$ref": "#/components/schemas/PodcastMention" }, "type": [ "array", "null" ] }, "has_more": { "description": "Whether more results exist", "type": "boolean" } }, "required": [ "data", "has_more" ], "type": "object" }, "PagePodcastPublisher": { "additionalProperties": false, "properties": { "cursor": { "description": "Pass to next request for more results", "type": "string" }, "data": { "description": "List of results", "items": { "$ref": "#/components/schemas/PodcastPublisher" }, "type": [ "array", "null" ] }, "has_more": { "description": "Whether more results exist", "type": "boolean" } }, "required": [ "data", "has_more" ], "type": "object" }, "PagePodcastPublisherBiasLeaderboardEntry": { "additionalProperties": false, "properties": { "cursor": { "description": "Pass to next request for more results", "type": "string" }, "data": { "description": "List of results", "items": { "$ref": "#/components/schemas/PodcastPublisherBiasLeaderboardEntry" }, "type": [ "array", "null" ] }, "has_more": { "description": "Whether more results exist", "type": "boolean" } }, "required": [ "data", "has_more" ], "type": "object" }, "PagePodcastRanking": { "additionalProperties": false, "properties": { "cursor": { "description": "Pass to next request for more results", "type": "string" }, "data": { "description": "List of results", "items": { "$ref": "#/components/schemas/PodcastRanking" }, "type": [ "array", "null" ] }, "has_more": { "description": "Whether more results exist", "type": "boolean" } }, "required": [ "data", "has_more" ], "type": "object" }, "PagePodcastRankingCategory": { "additionalProperties": false, "properties": { "cursor": { "description": "Pass to next request for more results", "type": "string" }, "data": { "description": "List of results", "items": { "$ref": "#/components/schemas/PodcastRankingCategory" }, "type": [ "array", "null" ] }, "has_more": { "description": "Whether more results exist", "type": "boolean" } }, "required": [ "data", "has_more" ], "type": "object" }, "PagePodcastRankingCountry": { "additionalProperties": false, "properties": { "cursor": { "description": "Pass to next request for more results", "type": "string" }, "data": { "description": "List of results", "items": { "$ref": "#/components/schemas/PodcastRankingCountry" }, "type": [ "array", "null" ] }, "has_more": { "description": "Whether more results exist", "type": "boolean" } }, "required": [ "data", "has_more" ], "type": "object" }, "PagePodcastRankingMover": { "additionalProperties": false, "properties": { "cursor": { "description": "Pass to next request for more results", "type": "string" }, "data": { "description": "List of results", "items": { "$ref": "#/components/schemas/PodcastRankingMover" }, "type": [ "array", "null" ] }, "has_more": { "description": "Whether more results exist", "type": "boolean" } }, "required": [ "data", "has_more" ], "type": "object" }, "PagePodcastRankingSource": { "additionalProperties": false, "properties": { "cursor": { "description": "Pass to next request for more results", "type": "string" }, "data": { "description": "List of results", "items": { "$ref": "#/components/schemas/PodcastRankingSource" }, "type": [ "array", "null" ] }, "has_more": { "description": "Whether more results exist", "type": "boolean" } }, "required": [ "data", "has_more" ], "type": "object" }, "PagePodcastRating": { "additionalProperties": false, "properties": { "cursor": { "description": "Pass to next request for more results", "type": "string" }, "data": { "description": "List of results", "items": { "$ref": "#/components/schemas/PodcastRating" }, "type": [ "array", "null" ] }, "has_more": { "description": "Whether more results exist", "type": "boolean" } }, "required": [ "data", "has_more" ], "type": "object" }, "PagePodcastSponsorEntry": { "additionalProperties": false, "properties": { "cursor": { "description": "Pass to next request for more results", "type": "string" }, "data": { "description": "List of results", "items": { "$ref": "#/components/schemas/PodcastSponsorEntry" }, "type": [ "array", "null" ] }, "has_more": { "description": "Whether more results exist", "type": "boolean" } }, "required": [ "data", "has_more" ], "type": "object" }, "PagePodcastTopic": { "additionalProperties": false, "properties": { "cursor": { "description": "Pass to next request for more results", "type": "string" }, "data": { "description": "List of results", "items": { "$ref": "#/components/schemas/PodcastTopic" }, "type": [ "array", "null" ] }, "has_more": { "description": "Whether more results exist", "type": "boolean" } }, "required": [ "data", "has_more" ], "type": "object" }, "PagePublisherAdvertisingLeaderboardEntry": { "additionalProperties": false, "properties": { "cursor": { "description": "Pass to next request for more results", "type": "string" }, "data": { "description": "List of results", "items": { "$ref": "#/components/schemas/PublisherAdvertisingLeaderboardEntry" }, "type": [ "array", "null" ] }, "has_more": { "description": "Whether more results exist", "type": "boolean" } }, "required": [ "data", "has_more" ], "type": "object" }, "PagePublisherAdvertisingPodcastEntry": { "additionalProperties": false, "properties": { "cursor": { "description": "Pass to next request for more results", "type": "string" }, "data": { "description": "List of results", "items": { "$ref": "#/components/schemas/PublisherAdvertisingPodcastEntry" }, "type": [ "array", "null" ] }, "has_more": { "description": "Whether more results exist", "type": "boolean" } }, "required": [ "data", "has_more" ], "type": "object" }, "PagePublisherSponsorEntry": { "additionalProperties": false, "properties": { "cursor": { "description": "Pass to next request for more results", "type": "string" }, "data": { "description": "List of results", "items": { "$ref": "#/components/schemas/PublisherSponsorEntry" }, "type": [ "array", "null" ] }, "has_more": { "description": "Whether more results exist", "type": "boolean" } }, "required": [ "data", "has_more" ], "type": "object" }, "PagePublisherSuitabilityCategoryPublisherEntry": { "additionalProperties": false, "properties": { "cursor": { "description": "Pass to next request for more results", "type": "string" }, "data": { "description": "List of results", "items": { "$ref": "#/components/schemas/PublisherSuitabilityCategoryPublisherEntry" }, "type": [ "array", "null" ] }, "has_more": { "description": "Whether more results exist", "type": "boolean" } }, "required": [ "data", "has_more" ], "type": "object" }, "PagePublisherSuitabilityLeaderboardEntry": { "additionalProperties": false, "properties": { "cursor": { "description": "Pass to next request for more results", "type": "string" }, "data": { "description": "List of results", "items": { "$ref": "#/components/schemas/PublisherSuitabilityLeaderboardEntry" }, "type": [ "array", "null" ] }, "has_more": { "description": "Whether more results exist", "type": "boolean" } }, "required": [ "data", "has_more" ], "type": "object" }, "PagePublisherSuitabilityPodcastEntry": { "additionalProperties": false, "properties": { "cursor": { "description": "Pass to next request for more results", "type": "string" }, "data": { "description": "List of results", "items": { "$ref": "#/components/schemas/PublisherSuitabilityPodcastEntry" }, "type": [ "array", "null" ] }, "has_more": { "description": "Whether more results exist", "type": "boolean" } }, "required": [ "data", "has_more" ], "type": "object" }, "PageRecommendedGuest": { "additionalProperties": false, "properties": { "cursor": { "description": "Pass to next request for more results", "type": "string" }, "data": { "description": "List of results", "items": { "$ref": "#/components/schemas/RecommendedGuest" }, "type": [ "array", "null" ] }, "has_more": { "description": "Whether more results exist", "type": "boolean" } }, "required": [ "data", "has_more" ], "type": "object" }, "PageRecommendedPodcast": { "additionalProperties": false, "properties": { "cursor": { "description": "Pass to next request for more results", "type": "string" }, "data": { "description": "List of results", "items": { "$ref": "#/components/schemas/RecommendedPodcast" }, "type": [ "array", "null" ] }, "has_more": { "description": "Whether more results exist", "type": "boolean" } }, "required": [ "data", "has_more" ], "type": "object" }, "PageRecommendedSponsor": { "additionalProperties": false, "properties": { "cursor": { "description": "Pass to next request for more results", "type": "string" }, "data": { "description": "List of results", "items": { "$ref": "#/components/schemas/RecommendedSponsor" }, "type": [ "array", "null" ] }, "has_more": { "description": "Whether more results exist", "type": "boolean" } }, "required": [ "data", "has_more" ], "type": "object" }, "PageRelatedEpisode": { "additionalProperties": false, "properties": { "cursor": { "description": "Pass to next request for more results", "type": "string" }, "data": { "description": "List of results", "items": { "$ref": "#/components/schemas/RelatedEpisode" }, "type": [ "array", "null" ] }, "has_more": { "description": "Whether more results exist", "type": "boolean" } }, "required": [ "data", "has_more" ], "type": "object" }, "PageSegment": { "additionalProperties": false, "properties": { "cursor": { "description": "Pass to next request for more results", "type": "string" }, "data": { "description": "List of results", "items": { "$ref": "#/components/schemas/Segment" }, "type": [ "array", "null" ] }, "has_more": { "description": "Whether more results exist", "type": "boolean" } }, "required": [ "data", "has_more" ], "type": "object" }, "PageSponsor": { "additionalProperties": false, "properties": { "cursor": { "description": "Pass to next request for more results", "type": "string" }, "data": { "description": "List of results", "items": { "$ref": "#/components/schemas/Sponsor" }, "type": [ "array", "null" ] }, "has_more": { "description": "Whether more results exist", "type": "boolean" } }, "required": [ "data", "has_more" ], "type": "object" }, "PageSponsorPodcastEntry": { "additionalProperties": false, "properties": { "cursor": { "description": "Pass to next request for more results", "type": "string" }, "data": { "description": "List of results", "items": { "$ref": "#/components/schemas/SponsorPodcastEntry" }, "type": [ "array", "null" ] }, "has_more": { "description": "Whether more results exist", "type": "boolean" } }, "required": [ "data", "has_more" ], "type": "object" }, "PageSponsorPublisherEntry": { "additionalProperties": false, "properties": { "cursor": { "description": "Pass to next request for more results", "type": "string" }, "data": { "description": "List of results", "items": { "$ref": "#/components/schemas/SponsorPublisherEntry" }, "type": [ "array", "null" ] }, "has_more": { "description": "Whether more results exist", "type": "boolean" } }, "required": [ "data", "has_more" ], "type": "object" }, "PageSponsorTrend": { "additionalProperties": false, "properties": { "cursor": { "description": "Pass to next request for more results", "type": "string" }, "data": { "description": "List of results", "items": { "$ref": "#/components/schemas/SponsorTrend" }, "type": [ "array", "null" ] }, "has_more": { "description": "Whether more results exist", "type": "boolean" } }, "required": [ "data", "has_more" ], "type": "object" }, "PageTopic": { "additionalProperties": false, "properties": { "cursor": { "description": "Pass to next request for more results", "type": "string" }, "data": { "description": "List of results", "items": { "$ref": "#/components/schemas/Topic" }, "type": [ "array", "null" ] }, "has_more": { "description": "Whether more results exist", "type": "boolean" } }, "required": [ "data", "has_more" ], "type": "object" }, "Person": { "additionalProperties": false, "properties": { "current_role": { "$ref": "#/components/schemas/PersonCompanyRole", "description": "The Person's most recent company role, when known." }, "description": { "description": "Short bio (one-liner) curated for the Person.", "type": "string" }, "detailed_description": { "description": "Longer Wikipedia-grounded bio when available.", "type": "string" }, "external_links": { "description": "Known third-party profiles (LinkedIn, Wikipedia, social). Discovered asynchronously; a freshly-resolved Person may not yet have all platforms populated.", "items": { "$ref": "#/components/schemas/ExternalLink" }, "type": [ "array", "null" ] }, "id": { "description": "Encoded Person identifier", "type": "string" }, "image_url": { "description": "Canonical headshot URL when one is known for the Person", "type": "string" }, "knowledge_graph_entity": { "$ref": "#/components/schemas/KnowledgeGraphEntityLink", "description": "Linked knowledge graph entity, when one exists. Secondary identifier — most callers should rely on id/slug." }, "name": { "description": "Display name", "type": "string" }, "roles": { "description": "All known company roles, ordered most-recent first. Includes the current role at index 0.", "items": { "$ref": "#/components/schemas/PersonCompanyRole" }, "type": [ "array", "null" ] }, "slug": { "description": "Stable human-readable handle (e.g. 'satya-nadella'). Recommended canonical identifier on every Particle Pro person surface.", "type": "string" }, "sports": { "$ref": "#/components/schemas/PersonSports", "description": "Sports history from Wikidata: the sports the Person plays, the teams they played for or coached, and their leagues. Present for athletes, coaches and other sports figures; omitted for everyone else." } }, "required": [ "id", "name" ], "type": "object" }, "PersonCompact": { "additionalProperties": false, "properties": { "description": { "description": "Short description (e.g. current role), when known.", "type": "string" }, "id": { "description": "Encoded Person identifier", "type": "string" }, "image_url": { "description": "Canonical headshot URL when one is known for the Person", "type": "string" }, "name": { "description": "Display name", "type": "string" }, "slug": { "description": "Stable human-readable handle (e.g. 'satya-nadella'). Recommended canonical identifier on every Particle Pro person surface.", "type": "string" } }, "required": [ "id", "name" ], "type": "object" }, "PersonCompanyRole": { "additionalProperties": false, "properties": { "company": { "$ref": "#/components/schemas/CompanyCompact", "description": "Company the Person held this role at" }, "ended_at": { "description": "When the role ended, when known (omitted for current roles)", "format": "date-time", "type": "string" }, "is_current": { "description": "Whether the role is currently held", "type": "boolean" }, "started_at": { "description": "When the role began, when known", "format": "date-time", "type": "string" }, "title": { "description": "Role title (e.g. 'Chief Executive Officer')", "type": "string" } }, "required": [ "company", "is_current" ], "type": "object" }, "PersonSports": { "additionalProperties": false, "properties": { "leagues": { "description": "Leagues recorded on the Person directly, latest start first. Most team athletes have none: their league is on each team.", "items": { "$ref": "#/components/schemas/PersonSportsLeague" }, "type": [ "array", "null" ] }, "sports": { "description": "Sports the Person plays or played, e.g. 'American football'.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "teams": { "description": "Teams the Person played for or coached, latest start first; stints with no recorded start come last.", "items": { "$ref": "#/components/schemas/PersonSportsTeam" }, "type": [ "array", "null" ] } }, "type": "object" }, "PersonSportsLeague": { "additionalProperties": false, "properties": { "end_year": { "description": "Year the stint ended, when recorded. A missing end_year does not by itself mean the stint is current: Wikidata often leaves a retired athlete's last team open.", "format": "int64", "type": "integer" }, "entity_slug": { "description": "Knowledge graph entity slug of the league, accepted by /v1/entities/{id}.", "type": "string" }, "name": { "description": "League name.", "type": "string" }, "start_year": { "description": "Year the stint began, when recorded.", "format": "int64", "type": "integer" } }, "required": [ "name" ], "type": "object" }, "PersonSportsTeam": { "additionalProperties": false, "properties": { "end_year": { "description": "Year the stint ended, when recorded. A missing end_year does not by itself mean the stint is current: Wikidata often leaves a retired athlete's last team open.", "format": "int64", "type": "integer" }, "entity_slug": { "description": "Knowledge graph entity slug of the team, accepted by /v1/entities/{id}.", "type": "string" }, "leagues": { "description": "Leagues the team plays in today, which may differ from its league during the stint.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "name": { "description": "Team name.", "type": "string" }, "role": { "description": "Whether the Person played for the team or coached it.", "enum": [ "athlete", "coach" ], "type": "string" }, "start_year": { "description": "Year the stint began, when recorded.", "format": "int64", "type": "integer" } }, "required": [ "name", "role" ], "type": "object" }, "PlatformError": { "additionalProperties": false, "properties": { "detail": { "description": "A human-readable explanation specific to this occurrence of the problem.", "examples": [ "Property foo is required but is missing." ], "type": "string" }, "error_code": { "type": "string" }, "errors": { "description": "Optional list of individual error details", "items": { "$ref": "#/components/schemas/ErrorDetail" }, "type": [ "array", "null" ] }, "instance": { "description": "A URI reference that identifies the specific occurrence of the problem.", "examples": [ "https://example.com/error-log/abc123" ], "format": "uri", "type": "string" }, "resolve": { "$ref": "#/components/schemas/ErrorResolve" }, "status": { "description": "HTTP status code", "examples": [ 400 ], "format": "int64", "type": "integer" }, "title": { "description": "A short, human-readable summary of the problem type. This value should not change between occurrences of the error.", "examples": [ "Bad Request" ], "type": "string" }, "type": { "default": "about:blank", "description": "A URI reference to human-readable documentation for the error.", "examples": [ "https://example.com/errors/example" ], "format": "uri", "type": "string" } }, "type": "object" }, "PlatformSlackChannel": { "additionalProperties": false, "properties": { "name": { "type": "string" }, "slack_channel_id": { "description": "Slack vendor channel id (e.g. C01234XYZ for public, G... for private).", "type": "string" } }, "required": [ "slack_channel_id", "name" ], "type": "object" }, "PlatformSlackConnection": { "additionalProperties": false, "properties": { "created_by": { "$ref": "#/components/schemas/Creator", "description": "User who installed the workspace." }, "id": { "type": "string" }, "installed_at": { "format": "date-time", "type": "string" }, "project_id": { "type": "string" }, "revoked_at": { "description": "Set when the install was revoked or soft-deleted; absent for active connections.", "format": "date-time", "type": "string" }, "scope": { "description": "Comma-joined scopes Slack granted on the bot token.", "type": "string" }, "slack_app_id": { "description": "Slack app id (e.g. A01234XYZ). Lets callers distinguish which Particle app the bot identity belongs to in the workspace.", "type": "string" }, "slack_team_id": { "description": "Slack vendor workspace identifier (e.g. T01234ABC).", "type": "string" }, "slack_team_name": { "description": "Slack workspace display name at install time.", "type": "string" }, "surface": { "description": "Which Particle Slack app this workspace installed. PLATFORM installs the Particle Slack app; RADAR installs the Radar Slack app. Fixed at install time and inferred from the caller's authenticated surface context (JWT issuer) on /initiate. Provenance only — an alert on either surface can deliver through it, though the message posts as this app's bot. Render it to show where the workspace was connected.", "enum": [ "PLATFORM", "RADAR" ], "type": "string" } }, "required": [ "id", "project_id", "surface", "slack_team_id", "slack_team_name", "slack_app_id", "scope", "installed_at" ], "type": "object" }, "PlatformWebhookConnection": { "additionalProperties": false, "properties": { "created_at": { "format": "date-time", "type": "string" }, "created_by": { "$ref": "#/components/schemas/Creator", "description": "User who created the connection. Null when created via an API key." }, "id": { "type": "string" }, "name": { "description": "Optional human label for the connection.", "type": "string" }, "project_id": { "type": "string" }, "revoked_at": { "description": "Set when the connection was deleted/revoked; absent for active connections. A revoked connection stops delivering and is skipped by alerts that still reference it.", "format": "date-time", "type": "string" }, "secret_prefix": { "description": "Masked signing-secret prefix for identification. The full secret is shown only at create/rotate time and cannot be retrieved afterward.", "type": "string" }, "surface": { "description": "Which Particle surface created this connection. Fixed at create time and inferred from the caller's authenticated surface context. Provenance only — an alert on either surface can deliver through it. Render it to show where the endpoint was registered.", "enum": [ "PLATFORM", "RADAR" ], "type": "string" }, "url": { "description": "Destination URL that signed POSTs are delivered to.", "type": "string" } }, "required": [ "id", "project_id", "surface", "url", "secret_prefix", "created_at" ], "type": "object" }, "Podcast": { "additionalProperties": false, "properties": { "bias": { "description": "Political bias rating for the podcast: EXTREME_LEFT, LEANS_LEFT, LEFT, CENTER, RIGHT, LEANS_RIGHT, or EXTREME_RIGHT. Empty when the podcast is not substantively political or has not been evaluated yet. Fetch GET /v1/podcasts/{id}/bias for the full analysis including reasoning and evidence.", "type": "string" }, "coverage": { "$ref": "#/components/schemas/PodcastCoverage", "description": "How much of the podcast's history we know of and have transcribed: discovered episodes by transcript_status and by year, and how its back catalogue was discovered. Present only on GET /v1/podcasts/{id} with include=coverage." }, "description": { "description": "Podcast description", "type": "string" }, "episode_count": { "description": "Total number of episodes", "format": "int64", "type": "integer" }, "explicit": { "description": "Whether the podcast contains explicit content", "type": "boolean" }, "format": { "$ref": "#/components/schemas/PodcastFormat", "description": "Production format attributes derived from episode analysis: guest frequency, detected formats (interview, panel, call_in, solo_narrated), ad and video presence, episode length, publishing cadence, and activity status. Every field doubles as a GET /v1/podcasts filter. Omitted for podcasts with no tracked episodes yet; within the object, the speaker-derived fields (guest_frequency, signals, has_ads) are additionally omitted until enough episodes have been analyzed to judge. Fetch GET /v1/podcasts/{id}/format for the full breakdown including exact rates, duration percentiles, and the publish-day histogram." }, "id": { "description": "Unique identifier", "type": "string" }, "image_url": { "description": "Cover image URL", "type": "string" }, "language": { "description": "ISO 639-1 language code", "type": "string" }, "match_quality": { "description": "How confidently this result matches your q search, strongest first. exact: this is the show with that name. partial: the name matches your search strongly (your search may have included extra words). fuzzy: the name is similar but not the same — it may be the show you meant with a typo, or a different show with a near-identical name; verify before relying on it. description: your search text appears in the show's description rather than its name. speculative: a loose suggestion, listed last. When resolving a show programmatically, act on exact or partial results and treat anything weaker as candidates to confirm. Present only when q was provided.", "enum": [ "exact", "partial", "fuzzy", "description", "speculative" ], "type": "string" }, "political_context": { "description": "Political framework the bias rating is calibrated against: US, UK, EU, CANADA, AUSTRALIA, INDIA, OTHER. Omitted when the latest analysis returned NOT_POLITICAL or when no analysis has been run yet.", "type": "string" }, "popularity": { "description": "Global popularity percentile in (0,1], a cume_dist ranking over all currently-charting podcasts (Apple Podcasts charts). Higher is more popular; the most popular podcast is 1.0. Always global — never scoped to a topic_id or other filter. Omitted when the podcast is not currently charting. Pair with the popularity_threshold query parameter on GET /v1/podcasts to filter the catalog by this value.", "format": "double", "type": "number" }, "publisher": { "$ref": "#/components/schemas/PodcastPublisherCompact", "description": "Publisher attributed to this podcast. Available on detail responses; absent on list responses and on podcasts whose publisher attribution is not yet known." }, "recommended_guests": { "description": "The five guests the show could plausibly book next (lean form, no via). Present only on GET /v1/podcasts/{id} with include=recommended_guests; the paged list is GET /v1/podcasts/{id}/recommendations/guests.", "items": { "$ref": "#/components/schemas/RecommendedGuest" }, "type": [ "array", "null" ] }, "recommended_sponsors": { "description": "The five advertisers most active on shows like this one that do not buy it yet (lean form, no via). Premium-grade: present only on GET /v1/podcasts/{id} with include=recommended_sponsors for plans that include premium endpoints; the paged list is GET /v1/podcasts/{id}/recommendations/sponsors.", "items": { "$ref": "#/components/schemas/RecommendedSponsor" }, "type": [ "array", "null" ] }, "related": { "description": "The five most related podcasts (lean form: podcast, score, band). Present only on GET /v1/podcasts/{id} with include=related, and omitted when the show's related set has not been computed yet. Fetch GET /v1/podcasts/{id}/related for the full ranked list with pagination and the basis (why) behind each result.", "items": { "$ref": "#/components/schemas/RelatedPodcast" }, "type": [ "array", "null" ] }, "slug": { "description": "Human-readable slug identifier", "type": "string" }, "speakers": { "description": "Top recurring speakers", "items": { "$ref": "#/components/schemas/PodcastSpeaker" }, "type": [ "array", "null" ] }, "suitability_tier": { "description": "High-level brand-suitability verdict from the IAB Tech Lab Brand Safety \u0026 Suitability Framework (formerly GARM): SAFE, LIMITED, SENSITIVE, or UNSAFE. Empty when the podcast has not been evaluated yet. Per-category breakdown, evidence, and methodology are gated to GET /v1/podcasts/{id}/suitability.", "type": "string" }, "title": { "description": "Podcast title", "type": "string" }, "topics": { "description": "Top topics discussed across episodes, ordered by frequency. Absent when the rollup exceeds its time budget.", "items": { "$ref": "#/components/schemas/Topic" }, "type": [ "array", "null" ] }, "url": { "description": "RSS feed URL", "type": "string" } }, "required": [ "id", "title", "explicit" ], "type": "object" }, "PodcastAdvertisingProfile": { "additionalProperties": false, "properties": { "avg_ads_per_episode": { "description": "Average ads per episode", "format": "double", "type": "number" }, "episodes_with_ads": { "description": "Number of episodes containing ads", "format": "int64", "type": "integer" }, "podcast_id": { "description": "Podcast identifier", "type": "string" }, "podcast_slug": { "description": "Human-readable slug (when available)", "type": "string" }, "read_type_breakdown": { "$ref": "#/components/schemas/ReadTypeBreakdown", "description": "Distribution of ad read types" }, "top_sponsors": { "description": "Most frequent sponsors", "items": { "$ref": "#/components/schemas/TopSponsorEntry" }, "type": [ "array", "null" ] }, "total_ads": { "description": "Total number of ads detected", "format": "int64", "type": "integer" }, "unique_sponsors": { "description": "Number of distinct sponsors", "format": "int64", "type": "integer" } }, "required": [ "podcast_id", "total_ads", "unique_sponsors", "episodes_with_ads", "avg_ads_per_episode", "read_type_breakdown", "top_sponsors" ], "type": "object" }, "PodcastBiasAnalysis": { "additionalProperties": false, "properties": { "confidence": { "description": "LOW, MEDIUM, or HIGH", "type": "string" }, "episodes_analyzed": { "description": "Number of episodes that informed the rating", "format": "int64", "type": "integer" }, "evaluated_at": { "description": "When the analysis was performed", "format": "date-time", "type": "string" }, "political_context": { "description": "US, UK, EU, CANADA, AUSTRALIA, INDIA, OTHER, or UNKNOWN (when NOT_POLITICAL)", "type": "string" }, "political_context_detail": { "description": "Country/region name when political_context is OTHER", "type": "string" }, "reasoning": { "description": "Agent's justification for the rating, grounded in the gathered evidence", "type": "string" }, "result": { "description": "NOT_POLITICAL when the podcast is not substantively political, otherwise one of EXTREME_LEFT, LEANS_LEFT, LEFT, CENTER, RIGHT, LEANS_RIGHT, EXTREME_RIGHT", "type": "string" }, "sample_episode_ids": { "description": "Episode IDs that informed the rating, in the order they were sampled", "items": { "type": "string" }, "type": [ "array", "null" ] }, "transcript_evidence": { "description": "Concrete quotes and observations drawn from the episode transcripts the agent sampled", "type": "string" }, "web_research_evidence": { "description": "External corroboration from rating services and publications, weighted relative to transcript evidence", "type": "string" } }, "required": [ "result", "political_context", "confidence", "reasoning", "evaluated_at" ], "type": "object" }, "PodcastBiasEntry": { "additionalProperties": false, "properties": { "bias": { "$ref": "#/components/schemas/PodcastBiasAnalysis", "description": "Latest bias analysis for the podcast" }, "podcast": { "$ref": "#/components/schemas/PodcastCompact", "description": "Podcast reference" } }, "required": [ "podcast", "bias" ], "type": "object" }, "PodcastCompact": { "additionalProperties": false, "properties": { "best_rank": { "$ref": "#/components/schemas/PodcastRankingHandle", "description": "The single best (lowest-numbered) chart position this podcast currently holds across all charts. Omitted when the podcast holds no current chart appearances, and on endpoints that do not attach it. Reading a full chart (with country/category/source filters and history) remains premium; a single show's own placement is available on every plan." }, "id": { "description": "Podcast ID", "type": "string" }, "image_url": { "description": "Cover image URL", "type": "string" }, "popularity": { "description": "Global popularity percentile in (0,1], a cume_dist ranking over all currently-charting podcasts (Apple Podcasts charts). Higher is more popular. Omitted when the podcast is not currently charting, on endpoints that build this resource from a projection rather than the full podcast row, and in episode stream, feed and archive payloads, which are stored and replayed: read it live from the podcast endpoints.", "format": "double", "type": "number" }, "publisher": { "$ref": "#/components/schemas/PodcastPublisherCompact", "description": "Publisher (network) attributed to this podcast. Present only when the embedding endpoint preloads publisher attribution and the podcast's publisher is known." }, "slug": { "description": "Human-readable slug identifier", "type": "string" }, "title": { "description": "Podcast title", "type": "string" } }, "required": [ "id", "title" ], "type": "object" }, "PodcastCoverage": { "additionalProperties": false, "properties": { "back_catalogue": { "$ref": "#/components/schemas/BackCatalogueCoverage", "description": "How the podcast's back catalogue was discovered. Absent until it has been imported and counted, and until then discovered_episode_count covers only the episodes we have ingested." }, "counted_at": { "description": "When these counts were computed. They refresh hourly, so an episode ingested, transcribed or requested since is not reflected yet; each episode's own transcript_status is always current.", "format": "date-time", "type": "string" }, "discovered_episode_count": { "description": "Every episode we know of, transcribed or not: the episodes we have ingested plus the podcast's back catalogue. The transcript_statuses counts sum to it.", "format": "int64", "type": "integer" }, "newest_episode_published_at": { "description": "Publication date of the newest discovered episode.", "format": "date-time", "type": "string" }, "oldest_episode_published_at": { "description": "Publication date of the oldest discovered episode.", "format": "date-time", "type": "string" }, "transcript_statuses": { "description": "Discovered episodes by transcript_status, one entry per status. Unlike episode_count on the podcast, which counts ingested episodes, these include the back catalogue.", "items": { "$ref": "#/components/schemas/TranscriptStatusCount" }, "type": [ "array", "null" ] }, "years": { "description": "Discovered and transcribed episodes per publication year, newest year first. Episodes without a publication date are counted in the totals only.", "items": { "$ref": "#/components/schemas/YearCoverage" }, "type": [ "array", "null" ] } }, "required": [ "discovered_episode_count", "transcript_statuses", "years" ], "type": "object" }, "PodcastFormat": { "additionalProperties": false, "properties": { "avg_episode_minutes": { "description": "Average episode length in minutes. Omitted when no episode durations are known.", "format": "int64", "type": "integer" }, "episodes_per_week": { "description": "Publishing cadence over the trailing 90 days, in episodes per week (e.g. 5.0 for a weekday daily, 0.5 for a fortnightly show). Omitted until the show has been tracked long enough to measure reliably.", "format": "double", "type": "number" }, "guest_frequency": { "description": "How often episodes feature a guest: never, rare, occasional, regular, or always. Derived from the share of analyzed episodes with at least one guest speaker. Omitted when too few episodes have been analyzed to judge. Filter the catalog with the guest_frequency query parameter on GET /v1/podcasts.", "type": "string" }, "has_ads": { "description": "Whether episodes carry advertiser reads. Omitted when too few episodes have been analyzed to judge. The full advertising profile (sponsors, read types, ad load) is served by GET /v1/podcasts/{id}/advertising.", "type": "boolean" }, "has_video": { "description": "Whether any episode has a discovered video version (e.g. a YouTube release).", "type": "boolean" }, "publishing_status": { "description": "Whether the show is still releasing episodes: active (published within the last 90 days) or dormant. Omitted when no publish dates are known.", "type": "string" }, "signals": { "description": "Production formats detected from the show's speaker-role mix: interview, panel, call_in, and/or solo_narrated. A show can carry several (a panel show with call-in segments). Omitted when too few episodes have been analyzed to judge.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, "required": [ "has_video" ], "type": "object" }, "PodcastFormatProfile": { "additionalProperties": false, "properties": { "ad_episode_rate": { "description": "Share of analyzed episodes carrying advertiser reads, in [0,1]", "format": "double", "type": "number" }, "analyzed_episodes": { "description": "Number of episodes with speaker analysis — the sample behind guest_frequency, signals, has_ads, and the rates below", "format": "int64", "type": "integer" }, "avg_episode_minutes": { "description": "Average episode length in minutes. Omitted when no episode durations are known.", "format": "int64", "type": "integer" }, "call_in_episode_rate": { "description": "Share of analyzed episodes with listener callers, in [0,1]", "format": "double", "type": "number" }, "computed_at": { "description": "When the profile was last recomputed", "format": "date-time", "type": "string" }, "episode_count": { "description": "Total episodes tracked for this podcast", "format": "int64", "type": "integer" }, "episode_minutes_median": { "description": "Median episode length in minutes", "format": "int64", "type": "integer" }, "episode_minutes_p25": { "description": "25th percentile episode length in minutes", "format": "int64", "type": "integer" }, "episode_minutes_p75": { "description": "75th percentile episode length in minutes", "format": "int64", "type": "integer" }, "episodes_per_week": { "description": "Publishing cadence over the trailing 90 days, in episodes per week (e.g. 5.0 for a weekday daily, 0.5 for a fortnightly show). Omitted until the show has been tracked long enough to measure reliably.", "format": "double", "type": "number" }, "first_episode_published_at": { "description": "Publish date of the earliest tracked episode", "format": "date-time", "type": "string" }, "guest_episode_rate": { "description": "Share of analyzed episodes featuring at least one guest, in [0,1]", "format": "double", "type": "number" }, "guest_frequency": { "description": "How often episodes feature a guest: never, rare, occasional, regular, or always. Derived from the share of analyzed episodes with at least one guest speaker. Omitted when too few episodes have been analyzed to judge. Filter the catalog with the guest_frequency query parameter on GET /v1/podcasts.", "type": "string" }, "has_ads": { "description": "Whether episodes carry advertiser reads. Omitted when too few episodes have been analyzed to judge. The full advertising profile (sponsors, read types, ad load) is served by GET /v1/podcasts/{id}/advertising.", "type": "boolean" }, "has_video": { "description": "Whether any episode has a discovered video version (e.g. a YouTube release).", "type": "boolean" }, "latest_episode_published_at": { "description": "Publish date of the most recent tracked episode", "format": "date-time", "type": "string" }, "panel_episode_rate": { "description": "Share of analyzed episodes with panelists, in [0,1]", "format": "double", "type": "number" }, "publish_days": { "$ref": "#/components/schemas/PodcastFormatPublishDays", "description": "Histogram of episodes by publish day of week" }, "publishing_status": { "description": "Whether the show is still releasing episodes: active (published within the last 90 days) or dormant. Omitted when no publish dates are known.", "type": "string" }, "signals": { "description": "Production formats detected from the show's speaker-role mix: interview, panel, call_in, and/or solo_narrated. A show can carry several (a panel show with call-in segments). Omitted when too few episodes have been analyzed to judge.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, "required": [ "analyzed_episodes", "episode_count", "guest_episode_rate", "ad_episode_rate", "call_in_episode_rate", "panel_episode_rate", "publish_days", "computed_at", "has_video" ], "type": "object" }, "PodcastFormatPublishDays": { "additionalProperties": false, "properties": { "friday": { "description": "Episodes published on a Friday", "format": "int64", "type": "integer" }, "monday": { "description": "Episodes published on a Monday", "format": "int64", "type": "integer" }, "saturday": { "description": "Episodes published on a Saturday", "format": "int64", "type": "integer" }, "sunday": { "description": "Episodes published on a Sunday", "format": "int64", "type": "integer" }, "thursday": { "description": "Episodes published on a Thursday", "format": "int64", "type": "integer" }, "tuesday": { "description": "Episodes published on a Tuesday", "format": "int64", "type": "integer" }, "wednesday": { "description": "Episodes published on a Wednesday", "format": "int64", "type": "integer" } }, "required": [ "monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday" ], "type": "object" }, "PodcastGuest": { "additionalProperties": false, "properties": { "current_role": { "$ref": "#/components/schemas/PersonCompanyRole", "description": "The Person's most recent company role, when known." }, "description": { "description": "Short bio (one-liner) curated for the Person.", "type": "string" }, "detailed_description": { "description": "Longer Wikipedia-grounded bio when available.", "type": "string" }, "external_links": { "description": "Known third-party profiles (LinkedIn, Wikipedia, social). Discovered asynchronously; a freshly-resolved Person may not yet have all platforms populated.", "items": { "$ref": "#/components/schemas/ExternalLink" }, "type": [ "array", "null" ] }, "id": { "description": "Encoded Person identifier", "type": "string" }, "image_url": { "description": "Canonical headshot URL when one is known for the Person", "type": "string" }, "knowledge_graph_entity": { "$ref": "#/components/schemas/KnowledgeGraphEntityLink", "description": "Linked knowledge graph entity, when one exists. Secondary identifier — most callers should rely on id/slug." }, "name": { "description": "Display name", "type": "string" }, "roles": { "description": "All known company roles, ordered most-recent first. Includes the current role at index 0.", "items": { "$ref": "#/components/schemas/PersonCompanyRole" }, "type": [ "array", "null" ] }, "slug": { "description": "Stable human-readable handle (e.g. 'satya-nadella'). Recommended canonical identifier on every Particle Pro person surface.", "type": "string" }, "sports": { "$ref": "#/components/schemas/PersonSports", "description": "Sports history from Wikidata: the sports the Person plays, the teams they played for or coached, and their leagues. Present for athletes, coaches and other sports figures; omitted for everyone else." }, "stats": { "$ref": "#/components/schemas/PodcastGuestStats", "description": "Lifetime appearance statistics across the corpus" }, "top_podcasts": { "description": "Up to five most-frequent podcasts the guest has appeared on", "items": { "$ref": "#/components/schemas/PodcastGuestPodcast" }, "type": [ "array", "null" ] } }, "required": [ "stats", "id", "name" ], "type": "object" }, "PodcastGuestAppearance": { "additionalProperties": false, "properties": { "bias": { "description": "Political-bias rating for the podcast, when evaluated", "type": "string" }, "episode": { "$ref": "#/components/schemas/PodcastGuestAppearanceEpisode", "description": "Episode the guest appeared on" }, "podcast": { "$ref": "#/components/schemas/PodcastCompact", "description": "Podcast that published the episode" }, "speaking_seconds": { "description": "Identified speaking duration on this episode, in seconds", "format": "double", "type": "number" }, "suitability_tier": { "description": "IAB Tech Lab Brand Safety \u0026 Suitability tier for the podcast, when evaluated", "type": "string" } }, "required": [ "episode", "podcast" ], "type": "object" }, "PodcastGuestAppearanceEpisode": { "additionalProperties": false, "properties": { "duration_seconds": { "description": "Episode duration in seconds", "format": "int64", "type": "integer" }, "id": { "description": "Episode ID", "type": "string" }, "published_at": { "description": "Episode publication date", "format": "date-time", "type": "string" }, "slug": { "description": "Episode slug", "type": "string" }, "title": { "description": "Episode title", "type": "string" } }, "required": [ "id", "title" ], "type": "object" }, "PodcastGuestCompact": { "additionalProperties": false, "properties": { "appearance_count": { "description": "Episode appearances in the scope of the listing. For the directory and trends this is the guest's lifetime corpus-wide count; for the podcast-roster and when the directory is filtered with appeared_on_podcast_id, it is scoped to that podcast.", "format": "int64", "type": "integer" }, "description": { "description": "Short description (e.g. current role), when known.", "type": "string" }, "distinct_podcasts": { "description": "Lifetime distinct podcasts the guest has appeared on across the corpus. Omitted when the listing is already scoped to a single podcast.", "format": "int64", "type": "integer" }, "first_appearance_at": { "description": "Publication date of the earliest appearance within the listing's scope", "format": "date-time", "type": "string" }, "id": { "description": "Encoded Person identifier", "type": "string" }, "image_url": { "description": "Canonical headshot URL when one is known for the Person", "type": "string" }, "last_appearance_at": { "description": "Publication date of the most recent appearance within the listing's scope", "format": "date-time", "type": "string" }, "name": { "description": "Display name", "type": "string" }, "slug": { "description": "Stable human-readable handle (e.g. 'satya-nadella'). Recommended canonical identifier on every Particle Pro person surface.", "type": "string" } }, "required": [ "appearance_count", "id", "name" ], "type": "object" }, "PodcastGuestPodcast": { "additionalProperties": false, "properties": { "appearance_count": { "description": "Episodes of this podcast featuring the guest", "format": "int64", "type": "integer" }, "bias": { "description": "Political-bias rating for the podcast, when evaluated", "type": "string" }, "first_appearance_at": { "description": "Publication date of the guest's first appearance on this podcast", "format": "date-time", "type": "string" }, "last_appearance_at": { "description": "Publication date of the guest's most recent appearance on this podcast", "format": "date-time", "type": "string" }, "podcast": { "$ref": "#/components/schemas/PodcastCompact", "description": "Podcast the guest appeared on" }, "suitability_tier": { "description": "IAB Tech Lab Brand Safety \u0026 Suitability tier for the podcast (SAFE, LIMITED, SENSITIVE, UNSAFE), when evaluated", "type": "string" } }, "required": [ "podcast", "appearance_count" ], "type": "object" }, "PodcastGuestStats": { "additionalProperties": false, "properties": { "appearance_count": { "description": "Total episode appearances", "format": "int64", "type": "integer" }, "appearances_by_bias": { "additionalProperties": { "format": "int64", "type": "integer" }, "description": "Episode appearances bucketed by the political-bias rating of the host podcast — including a NOT_POLITICAL bucket for shows explicitly classified as non-political, so the political mix is contextualized against non-political activity. Counts sum to at most appearance_count — appearances on podcasts whose bias hasn't been evaluated are omitted.", "type": "object" }, "appearances_by_suitability_tier": { "additionalProperties": { "format": "int64", "type": "integer" }, "description": "Episode appearances bucketed by the IAB Tech Lab brand-suitability tier of the host podcast. Counts sum to at most appearance_count — appearances on podcasts whose suitability hasn't been evaluated are omitted.", "type": "object" }, "distinct_podcasts": { "description": "Distinct podcasts the guest has appeared on", "format": "int64", "type": "integer" }, "first_appearance_at": { "description": "Publication date of the earliest known appearance", "format": "date-time", "type": "string" }, "last_appearance_at": { "description": "Publication date of the most recent known appearance", "format": "date-time", "type": "string" }, "total_speaking_seconds": { "description": "Sum of identified speaking duration across all appearances, in seconds", "format": "double", "type": "number" } }, "required": [ "appearance_count", "distinct_podcasts" ], "type": "object" }, "PodcastGuestSuitabilityCategoryStat": { "additionalProperties": false, "properties": { "code": { "description": "IAB Tech Lab brand-suitability category code (e.g. adult_sexual, hate_speech_aggression)", "type": "string" }, "podcasts": { "description": "Distinct podcasts the guest has appeared on whose latest suitability analysis flagged this (code, prevalence) bucket", "format": "int64", "type": "integer" }, "prevalence": { "description": "INCIDENTAL, OCCASIONAL, FREQUENT, or PERVASIVE", "type": "string" }, "treatment": { "description": "Most-prevalent treatment observed at this prevalence level: EDITORIAL, DOCUMENTARY, PROMOTIONAL, or GLAMORIZING", "type": "string" } }, "required": [ "code", "prevalence", "podcasts" ], "type": "object" }, "PodcastGuestSuitabilityExposure": { "additionalProperties": false, "properties": { "lifetime": { "$ref": "#/components/schemas/PodcastGuestSuitabilityWindow", "description": "Tier distribution across every podcast the guest has appeared on" }, "notes": { "description": "Plain-text framing: this surface measures exposure, not guest risk.", "type": "string" }, "recent_90d": { "$ref": "#/components/schemas/PodcastGuestSuitabilityWindow", "description": "Tier distribution across podcasts where the guest appeared in the trailing 90 days" }, "top_categories": { "description": "Most-frequently flagged IAB Tech Lab brand-suitability categories across the guest's podcasts (NONE-prevalence buckets omitted)", "items": { "$ref": "#/components/schemas/PodcastGuestSuitabilityCategoryStat" }, "type": [ "array", "null" ] } }, "required": [ "lifetime", "recent_90d", "notes" ], "type": "object" }, "PodcastGuestSuitabilityTierBucket": { "additionalProperties": false, "properties": { "distinct_podcasts": { "description": "Distinct podcasts in this tier", "format": "int64", "type": "integer" }, "episodes": { "description": "Episodes in this tier", "format": "int64", "type": "integer" }, "tier": { "description": "SAFE, LIMITED, SENSITIVE, UNSAFE, or UNKNOWN (not yet evaluated)", "type": "string" } }, "required": [ "tier", "episodes", "distinct_podcasts" ], "type": "object" }, "PodcastGuestSuitabilityWindow": { "additionalProperties": false, "properties": { "tier_distribution": { "description": "Episode + distinct-podcast counts bucketed by tier", "items": { "$ref": "#/components/schemas/PodcastGuestSuitabilityTierBucket" }, "type": [ "array", "null" ] }, "window_start": { "description": "Inclusive lower bound of the window (omitted for the lifetime slice)", "format": "date-time", "type": "string" } }, "required": [ "tier_distribution" ], "type": "object" }, "PodcastGuestTrend": { "additionalProperties": false, "properties": { "first_appearance_in_window": { "description": "Publication date of the earliest appearance in the window", "format": "date-time", "type": "string" }, "guest": { "$ref": "#/components/schemas/PodcastGuestCompact", "description": "Guest summary" }, "last_appearance_at": { "description": "Publication date of the most-recent appearance", "format": "date-time", "type": "string" }, "recent_appearances": { "description": "Episode appearances inside the trend window. Every appearance is on a distinct podcast — guests with repeats on the same show inside the window are excluded so the listing reflects cross-show press tours, not regulars stacking repeats.", "format": "int64", "type": "integer" } }, "required": [ "guest", "recent_appearances" ], "type": "object" }, "PodcastLookup": { "additionalProperties": false, "properties": { "results": { "description": "One result per unique input identifier, in request order", "items": { "$ref": "#/components/schemas/PodcastLookupResult" }, "type": [ "array", "null" ] } }, "required": [ "results" ], "type": "object" }, "PodcastLookupResult": { "additionalProperties": false, "properties": { "identifier": { "description": "The platform-native identifier as supplied in the request", "type": "string" }, "podcast": { "$ref": "#/components/schemas/PodcastCompact", "description": "The matched podcast. Omitted when the identifier does not resolve to any podcast — callers should test for key presence rather than null." } }, "required": [ "identifier" ], "type": "object" }, "PodcastMention": { "additionalProperties": false, "properties": { "episode": { "$ref": "#/components/schemas/EpisodeCompact", "description": "The episode where the entity appears" }, "occurrences": { "description": "Number of times the entity is mentioned in this episode", "format": "int64", "type": "integer" }, "salience": { "description": "Importance score for this entity within the episode. When salience metadata is available, this is a percentile rank in (0.0, 1.0) — 0.95 means more salient than 95% of other entities mentioned, and the top entity approaches but never reaches 1.0. A value of 0.0 indicates salience metadata was unavailable for this episode/entity (e.g. a speaker-only appearance with no mention row).", "format": "double", "type": "number" }, "speaker_roles": { "description": "Roles the entity holds as a speaker (e.g. HOST, GUEST)", "items": { "type": "string" }, "type": [ "array", "null" ] } }, "required": [ "episode", "salience", "occurrences" ], "type": "object" }, "PodcastMentionEpisode": { "additionalProperties": false, "properties": { "episode": { "$ref": "#/components/schemas/EpisodeCompactWithPodcast", "description": "Episode containing the mentions" }, "mention_count": { "description": "Number of dialogue lines containing the entity in this episode", "format": "int64", "type": "integer" }, "mention_variants": { "description": "Distinct mention strings observed (e.g. [\"Sam Altman\", \"Altman\"])", "items": { "type": "string" }, "type": [ "array", "null" ] }, "truncated": { "description": "True when the episode had more mention windows than fit in the response", "type": "boolean" }, "windows": { "description": "Mention windows ordered by time", "items": { "$ref": "#/components/schemas/PodcastMentionWindow" }, "type": [ "array", "null" ] } }, "required": [ "episode", "mention_count", "mention_variants", "windows" ], "type": "object" }, "PodcastMentionWindow": { "additionalProperties": false, "properties": { "end_seconds": { "description": "Window end time in seconds (episode-absolute)", "format": "double", "type": "number" }, "lines": { "description": "Dialogue lines in this window. Lines containing the mention have is_mention=true.", "items": { "$ref": "#/components/schemas/TranscriptLine" }, "type": [ "array", "null" ] }, "segment": { "$ref": "#/components/schemas/SegmentCompact", "description": "Segment containing the mention. Nil when no segment overlaps." }, "start_seconds": { "description": "Window start time in seconds (episode-absolute)", "format": "double", "type": "number" } }, "required": [ "start_seconds", "end_seconds", "lines" ], "type": "object" }, "PodcastMentionsPage": { "additionalProperties": false, "properties": { "company": { "$ref": "#/components/schemas/CompanyCompact", "description": "Resolved company, when company_id filtered the result set. Omitted when only entity_id was provided." }, "cursor": { "description": "Opaque cursor; pass back as ?cursor= for the next page", "type": "string" }, "data": { "description": "Episodes on this page, ordered by recency (default) or salience", "items": { "$ref": "#/components/schemas/PodcastMentionEpisode" }, "type": [ "array", "null" ] }, "entity": { "$ref": "#/components/schemas/EntityCompact", "description": "Resolved entity. Omitted on empty pages where neither entity_id nor company_id resolved, and on name-matched pages (see matched_by) where the subject has no knowledge graph entity." }, "has_more": { "description": "More episodes available", "type": "boolean" }, "matched_by": { "description": "How mention lines were matched. Omitted for the default knowledge-graph tag matching; 'name' when the subject has no knowledge graph entity and dialogue was scanned for the subject's name verbatim.", "type": "string" }, "person": { "$ref": "#/components/schemas/PersonCompact", "description": "Resolved person, when entity_id resolved to a person with no linked knowledge graph entity (name-match fallback)." } }, "required": [ "data", "has_more" ], "type": "object" }, "PodcastPublisher": { "additionalProperties": false, "properties": { "id": { "description": "Publisher ID", "type": "string" }, "name": { "description": "Publisher name", "type": "string" }, "podcast_count": { "description": "Number of podcasts attributed to this publisher.", "format": "int64", "type": "integer" }, "slug": { "description": "Human-readable slug identifier (e.g., 'goalhanger', 'iheartpodcasts'). When present, accepted in place of the ID anywhere a publisher reference is taken in the API (e.g., GET /v1/podcasts/publishers/{slug}). Occasionally absent on publishers whose name doesn't slugify.", "type": "string" } }, "required": [ "id", "name", "podcast_count" ], "type": "object" }, "PodcastPublisherBiasBucketCount": { "additionalProperties": false, "properties": { "count": { "description": "Number of analyzed podcasts in the publisher's catalog whose latest result matches this bucket", "format": "int64", "type": "integer" }, "result": { "description": "Bias bucket: NOT_POLITICAL or one of EXTREME_LEFT, LEFT, LEANS_LEFT, CENTER, LEANS_RIGHT, RIGHT, EXTREME_RIGHT", "type": "string" } }, "required": [ "result", "count" ], "type": "object" }, "PodcastPublisherBiasContextCount": { "additionalProperties": false, "properties": { "count": { "description": "Number of analyzed podcasts whose latest analysis is calibrated against this political framework", "format": "int64", "type": "integer" }, "political_context": { "description": "Political framework: US, UK, EU, CANADA, AUSTRALIA, INDIA, OTHER, or UNKNOWN", "type": "string" } }, "required": [ "political_context", "count" ], "type": "object" }, "PodcastPublisherBiasCoverage": { "additionalProperties": false, "properties": { "analyzed_coverage": { "description": "analyzed_podcasts / total_podcasts (0..1). Treat as a confidence proxy for the rolled-up verdict.", "format": "double", "type": "number" }, "analyzed_podcasts": { "description": "Number of catalog podcasts with at least one non-deleted bias analysis", "format": "int64", "type": "integer" }, "total_podcasts": { "description": "Number of podcasts in the publisher's catalog (denormalized from podcast_publishers.podcast_count)", "format": "int64", "type": "integer" } }, "required": [ "total_podcasts", "analyzed_podcasts", "analyzed_coverage" ], "type": "object" }, "PodcastPublisherBiasDistributions": { "additionalProperties": false, "properties": { "bias": { "description": "Per-bucket counts of analyzed podcasts by their latest result", "items": { "$ref": "#/components/schemas/PodcastPublisherBiasBucketCount" }, "type": [ "array", "null" ] }, "region": { "description": "Per-region counts of analyzed podcasts by political_context", "items": { "$ref": "#/components/schemas/PodcastPublisherBiasContextCount" }, "type": [ "array", "null" ] } }, "required": [ "bias", "region" ], "type": "object" }, "PodcastPublisherBiasLeaderboardEntry": { "additionalProperties": false, "properties": { "coverage": { "$ref": "#/components/schemas/PodcastPublisherBiasCoverage", "description": "Catalog size and how much of it has been analyzed" }, "last_evaluated_at": { "description": "Most recent evaluated_at across the publisher's analyses", "format": "date-time", "type": "string" }, "lean": { "$ref": "#/components/schemas/PodcastPublisherBiasLean", "description": "Ideological lean across political podcasts. Absent from the response when political_content.podcasts == 0." }, "political_content": { "$ref": "#/components/schemas/PodcastPublisherBiasPoliticalContent", "description": "How political the analyzed catalog is, regardless of which side" }, "publisher": { "$ref": "#/components/schemas/PodcastPublisherCompact", "description": "Publisher reference" }, "rank": { "description": "Position in the leaderboard", "format": "int64", "type": "integer" } }, "required": [ "rank", "publisher", "coverage", "political_content" ], "type": "object" }, "PodcastPublisherBiasLean": { "additionalProperties": false, "properties": { "avg_score": { "description": "Average lean across political podcasts on a -3 (extreme left) to +3 (extreme right) ordinal scale: EXTREME_LEFT=-3, LEFT=-2, LEANS_LEFT=-1, CENTER=0, LEANS_RIGHT=+1, RIGHT=+2, EXTREME_RIGHT=+3.", "format": "double", "type": [ "number", "null" ] }, "dominant_bias": { "description": "Modal political bias bucket across the publisher's political podcasts.", "type": "string" }, "stddev": { "description": "Sample standard deviation of the lean score across political podcasts — a diversity signal. Low = monolithic publisher; high = heterogeneous catalog. Null when only one political podcast (stddev undefined for n=1).", "format": "double", "type": [ "number", "null" ] } }, "required": [ "avg_score", "stddev", "dominant_bias" ], "type": "object" }, "PodcastPublisherBiasPoliticalContent": { "additionalProperties": false, "properties": { "avg_topic_percentage": { "description": "Average share of episodes flagged under one of the political root topics across analyzed podcasts (0..1). Sparse — omitted when no analyzed podcast carries this signal.", "format": "double", "type": "number" }, "podcasts": { "description": "Analyzed podcasts whose latest result is not NOT_POLITICAL", "format": "int64", "type": "integer" }, "share": { "description": "podcasts / analyzed_podcasts (0..1) — distinguishes news-heavy publishers from entertainment-heavy publishers", "format": "double", "type": "number" } }, "required": [ "podcasts", "share" ], "type": "object" }, "PodcastPublisherBiasProfile": { "additionalProperties": false, "properties": { "coverage": { "$ref": "#/components/schemas/PodcastPublisherBiasCoverage", "description": "Catalog size and how much of it has been analyzed" }, "distributions": { "$ref": "#/components/schemas/PodcastPublisherBiasDistributions", "description": "Per-bucket and per-region breakdowns of the analyzed catalog" }, "last_evaluated_at": { "description": "Most recent evaluated_at across the publisher's analyses", "format": "date-time", "type": "string" }, "lean": { "$ref": "#/components/schemas/PodcastPublisherBiasLean", "description": "Ideological lean across political podcasts. Absent from the response when political_content.podcasts == 0 — entertainment-only publishers have no lean." }, "political_content": { "$ref": "#/components/schemas/PodcastPublisherBiasPoliticalContent", "description": "How political the analyzed catalog is, regardless of which side" }, "publisher": { "$ref": "#/components/schemas/PodcastPublisherCompact", "description": "Publisher reference" } }, "required": [ "publisher", "coverage", "political_content", "distributions" ], "type": "object" }, "PodcastPublisherCompact": { "additionalProperties": false, "properties": { "id": { "description": "Publisher ID", "type": "string" }, "name": { "description": "Publisher name", "type": "string" }, "slug": { "description": "Human-readable slug identifier (e.g., 'goalhanger', 'iheartpodcasts'). When present, accepted in place of the ID anywhere a publisher reference is taken in the API. Occasionally absent on publishers whose name doesn't slugify (e.g., scripts not representable in ASCII URL slugs).", "type": "string" } }, "required": [ "id", "name" ], "type": "object" }, "PodcastRanking": { "additionalProperties": false, "properties": { "captured_at": { "description": "When the snapshot containing this row was captured (UTC).", "format": "date-time", "type": "string" }, "category": { "$ref": "#/components/schemas/Category", "description": "Category the chart belongs to. Null on the overall ('top podcasts') chart." }, "channel_subscriber_count": { "description": "YouTube channel subscriber count when the source is YouTube.", "format": "int64", "type": "integer" }, "chart_total": { "description": "Total number of entries in this chart at this capture (typically 200).", "format": "int64", "type": "integer" }, "chart_type": { "description": "Chart variant within the source. Currently only 'top_podcasts' is emitted.", "enum": [ "top_podcasts" ], "type": "string" }, "country": { "description": "Lowercase ISO 3166-1 alpha-2 country code.", "type": "string" }, "external_id": { "description": "Source-native identifier for the chart entry (e.g., the Apple collection id '1581410252'). Stable across captures even when the linked podcast hasn't been resolved yet.", "type": "string" }, "external_url": { "description": "Canonical URL of the show on the source platform.", "type": "string" }, "growth_indicator": { "description": "Source-supplied trend hint (e.g. 'up' or 'down') when the source provides one.", "type": "string" }, "id": { "description": "Stable identifier for this chart entry capture (one row per snapshot per slot per rank).", "type": "string" }, "is_current": { "description": "Whether this row belongs to the live snapshot.", "type": "boolean" }, "podcast": { "$ref": "#/components/schemas/PodcastCompact", "description": "Linked podcast in our catalog. Absent when the source's chart entry hasn't been matched to a podcast yet (roughly two thirds of international and long-tail rows)." }, "previous_rank": { "description": "Source-reported rank from the previous capture, when the source provides it. Apple does not currently populate this; treat its absence as 'unknown', not 'unchanged'.", "format": "int64", "type": "integer" }, "rank": { "description": "Position on the chart (1-based, lower is better).", "format": "int64", "type": "integer" }, "reach_pct": { "description": "Source-supplied audience reach percentage (reach-survey sources).", "format": "double", "type": "number" }, "show": { "$ref": "#/components/schemas/ShowSummary", "description": "Show metadata captured with the chart entry. Always populated, including for chart entries we haven't matched to a podcast in our catalog." }, "source": { "description": "Ranking source platform.", "enum": [ "apple", "spotify" ], "type": "string" }, "source_updated_at": { "description": "Timestamp the source itself reported for the chart, when present.", "format": "date-time", "type": "string" }, "view_count": { "description": "YouTube channel view count when the source is YouTube.", "format": "int64", "type": "integer" }, "weekly_avg_downloads": { "description": "Source-supplied weekly download estimate (Triton/Podtrac sources).", "format": "int64", "type": "integer" } }, "required": [ "id", "source", "chart_type", "rank", "captured_at", "is_current", "external_id", "show" ], "type": "object" }, "PodcastRankingCategory": { "additionalProperties": false, "properties": { "current_chart_count": { "description": "Number of distinct chart slots currently available for this category.", "format": "int64", "type": "integer" }, "external_id": { "description": "Source-native category identifier (one of the sources reporting this category).", "type": "string" }, "name": { "description": "Category display name.", "type": "string" }, "parent_slug": { "description": "Slug of the parent category, when this is a sub-category.", "type": "string" }, "slug": { "description": "Universal category slug.", "type": "string" }, "sources": { "description": "Sources with live rankings for this category.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, "required": [ "slug", "name", "current_chart_count", "sources" ], "type": "object" }, "PodcastRankingCountry": { "additionalProperties": false, "properties": { "code": { "description": "Lowercase ISO 3166-1 alpha-2 country code.", "type": "string" }, "current_chart_count": { "description": "Number of distinct chart slots currently available for this country.", "format": "int64", "type": "integer" }, "name": { "description": "Country display name, when known.", "type": "string" }, "sources": { "description": "Sources with live rankings for this country.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, "required": [ "code", "current_chart_count", "sources" ], "type": "object" }, "PodcastRankingHandle": { "additionalProperties": false, "properties": { "captured_at": { "format": "date-time", "type": "string" }, "category_slug": { "type": "string" }, "chart_type": { "enum": [ "top_podcasts" ], "type": "string" }, "country": { "type": "string" }, "rank": { "format": "int64", "type": "integer" }, "source": { "enum": [ "apple", "spotify" ], "type": "string" } }, "required": [ "source", "chart_type", "rank", "captured_at" ], "type": "object" }, "PodcastRankingMover": { "additionalProperties": false, "properties": { "captured_at": { "description": "When the snapshot containing this row was captured (UTC).", "format": "date-time", "type": "string" }, "category": { "$ref": "#/components/schemas/Category", "description": "Category the chart belongs to. Null on the overall ('top podcasts') chart." }, "change": { "description": "How the entry moved between snapshots: 'up' (rank improved), 'down' (rank dropped), 'new' (entry appeared on the chart), or 'exit' (entry fell off).", "enum": [ "up", "down", "new", "exit" ], "type": "string" }, "channel_subscriber_count": { "description": "YouTube channel subscriber count when the source is YouTube.", "format": "int64", "type": "integer" }, "chart_total": { "description": "Total number of entries in this chart at this capture (typically 200).", "format": "int64", "type": "integer" }, "chart_type": { "description": "Chart variant within the source. Currently only 'top_podcasts' is emitted.", "enum": [ "top_podcasts" ], "type": "string" }, "country": { "description": "Lowercase ISO 3166-1 alpha-2 country code.", "type": "string" }, "delta": { "description": "Rank change (positive = rose). Null for 'new' and 'exit' since the change is undefined in the absence of one of the two snapshots.", "format": "int64", "type": "integer" }, "external_id": { "description": "Source-native identifier for the chart entry (e.g., the Apple collection id '1581410252'). Stable across captures even when the linked podcast hasn't been resolved yet.", "type": "string" }, "external_url": { "description": "Canonical URL of the show on the source platform.", "type": "string" }, "growth_indicator": { "description": "Source-supplied trend hint (e.g. 'up' or 'down') when the source provides one.", "type": "string" }, "id": { "description": "Stable identifier for this chart entry capture (one row per snapshot per slot per rank).", "type": "string" }, "is_current": { "description": "Whether this row belongs to the live snapshot.", "type": "boolean" }, "podcast": { "$ref": "#/components/schemas/PodcastCompact", "description": "Linked podcast in our catalog. Absent when the source's chart entry hasn't been matched to a podcast yet (roughly two thirds of international and long-tail rows)." }, "previous_rank": { "description": "Source-reported rank from the previous capture, when the source provides it. Apple does not currently populate this; treat its absence as 'unknown', not 'unchanged'.", "format": "int64", "type": "integer" }, "previous_snapshot": { "$ref": "#/components/schemas/PodcastRanking", "description": "The ranking row from the comparison snapshot. Null when change is 'new'." }, "rank": { "description": "Position on the chart (1-based, lower is better).", "format": "int64", "type": "integer" }, "reach_pct": { "description": "Source-supplied audience reach percentage (reach-survey sources).", "format": "double", "type": "number" }, "show": { "$ref": "#/components/schemas/ShowSummary", "description": "Show metadata captured with the chart entry. Always populated, including for chart entries we haven't matched to a podcast in our catalog." }, "source": { "description": "Ranking source platform.", "enum": [ "apple", "spotify" ], "type": "string" }, "source_updated_at": { "description": "Timestamp the source itself reported for the chart, when present.", "format": "date-time", "type": "string" }, "view_count": { "description": "YouTube channel view count when the source is YouTube.", "format": "int64", "type": "integer" }, "weekly_avg_downloads": { "description": "Source-supplied weekly download estimate (Triton/Podtrac sources).", "format": "int64", "type": "integer" } }, "required": [ "change", "id", "source", "chart_type", "rank", "captured_at", "is_current", "external_id", "show" ], "type": "object" }, "PodcastRankingSource": { "additionalProperties": false, "properties": { "chart_type": { "description": "Chart variant within the source.", "enum": [ "top_podcasts" ], "type": "string" }, "current_row_count": { "description": "Total rows in this source's live snapshot across all chart slots.", "format": "int64", "type": "integer" }, "latest_captured_at": { "description": "When this source's most recent chart was captured (UTC).", "format": "date-time", "type": "string" }, "source": { "description": "Source platform identifier.", "enum": [ "apple", "spotify" ], "type": "string" } }, "required": [ "source", "chart_type", "current_row_count", "latest_captured_at" ], "type": "object" }, "PodcastRankingsSummary": { "additionalProperties": false, "properties": { "appearances_by_source": { "description": "Per-source breakdown of chart presence and best rank.", "items": { "$ref": "#/components/schemas/SourceAppearanceStat" }, "type": [ "array", "null" ] }, "best_rank": { "$ref": "#/components/schemas/PodcastRankingHandle", "description": "The single best (lowest-numbered) rank this podcast currently holds across all charts. Null when the podcast holds no current chart appearances." }, "category_count": { "description": "Number of distinct categories currently charting this podcast.", "format": "int64", "type": "integer" }, "chart_count": { "description": "Number of distinct chart slots (source × country × category) on which this podcast currently appears.", "format": "int64", "type": "integer" }, "country_count": { "description": "Number of distinct countries currently charting this podcast.", "format": "int64", "type": "integer" }, "podcast": { "$ref": "#/components/schemas/PodcastCompact", "description": "The podcast this summary describes." }, "source_count": { "description": "Number of distinct sources currently charting this podcast.", "format": "int64", "type": "integer" } }, "required": [ "podcast", "chart_count", "source_count", "country_count", "category_count", "appearances_by_source" ], "type": "object" }, "PodcastRating": { "additionalProperties": false, "properties": { "author_display_name": { "description": "Display name the reviewer chose on the platform.", "type": "string" }, "author_uri": { "description": "Reviewer profile URL on the platform, when present.", "type": "string" }, "body": { "description": "Review body when present.", "type": "string" }, "id": { "description": "Stable identifier for this rating row.", "type": "string" }, "link_href": { "description": "Source-platform link for this individual rating, when present.", "type": "string" }, "locale": { "description": "Platform-specific locale code (e.g. Apple storefront 'us'). Empty for platforms without a locale dimension.", "type": "string" }, "platform_rating_id": { "description": "Platform-native identifier for the rating. Stable across re-pulls.", "type": "string" }, "platform_slug": { "description": "Canonical platform identifier. Today only 'apple' is populated.", "type": "string" }, "posted_at": { "description": "When the rating was posted on the source platform.", "format": "date-time", "type": "string" }, "stars": { "description": "1-5 star score.", "format": "int64", "maximum": 5, "minimum": 1, "type": "integer" }, "title": { "description": "Review title when present.", "type": "string" } }, "required": [ "id", "platform_slug", "platform_rating_id", "stars" ], "type": "object" }, "PodcastRatingHistogram": { "additionalProperties": false, "properties": { "stars_1": { "description": "Number of 1-star ratings.", "format": "int64", "type": "integer" }, "stars_2": { "description": "Number of 2-star ratings.", "format": "int64", "type": "integer" }, "stars_3": { "description": "Number of 3-star ratings.", "format": "int64", "type": "integer" }, "stars_4": { "description": "Number of 4-star ratings.", "format": "int64", "type": "integer" }, "stars_5": { "description": "Number of 5-star ratings.", "format": "int64", "type": "integer" } }, "required": [ "stars_1", "stars_2", "stars_3", "stars_4", "stars_5" ], "type": "object" }, "PodcastRatingSentimentSummary": { "additionalProperties": false, "properties": { "generated_at": { "description": "When the LLM produced this summary.", "format": "date-time", "type": "string" }, "locale": { "description": "Locale the summary is scoped to (empty for cross-locale roll-up).", "type": "string" }, "platform_slug": { "description": "Platform the summary is scoped to (empty for cross-platform roll-up).", "type": "string" }, "rating_count_in_window": { "description": "How many ratings the summary aggregates.", "format": "int64", "type": "integer" }, "summary_text": { "description": "Narrative summary paragraph.", "type": "string" }, "window_end": { "description": "Latest rating posted_at in the window the summary covers.", "format": "date-time", "type": "string" }, "window_start": { "description": "Earliest rating posted_at in the window the summary covers.", "format": "date-time", "type": "string" } }, "required": [ "summary_text", "rating_count_in_window", "generated_at" ], "type": "object" }, "PodcastRatingSummaryEntry": { "additionalProperties": false, "properties": { "computed_at": { "description": "When this summary was last computed.", "format": "date-time", "type": "string" }, "histogram": { "$ref": "#/components/schemas/PodcastRatingHistogram", "description": "Per-star counts." }, "locale": { "description": "Platform-specific locale code. Empty for platforms without a locale dimension or for the cross-locale roll-up.", "type": "string" }, "platform_slug": { "description": "Canonical platform identifier.", "type": "string" }, "rating_average": { "description": "Arithmetic mean of stars across the aggregated ratings.", "format": "double", "type": "number" }, "rating_count": { "description": "Total ratings the summary aggregates.", "format": "int64", "type": "integer" } }, "required": [ "platform_slug", "rating_count", "rating_average", "histogram", "computed_at" ], "type": "object" }, "PodcastRatingsSummary": { "additionalProperties": false, "properties": { "combined": { "$ref": "#/components/schemas/PodcastRatingSummaryEntry", "description": "Single roll-up across every entry, computed by weighting each entry's average by its rating_count. Null when the podcast has no ratings yet." }, "entries": { "description": "One entry per (platform, locale) the podcast has been rated on.", "items": { "$ref": "#/components/schemas/PodcastRatingSummaryEntry" }, "type": [ "array", "null" ] }, "podcast_id": { "description": "Internal podcast ID.", "type": "string" }, "sentiment": { "$ref": "#/components/schemas/PodcastRatingSentimentSummary", "description": "Latest LLM-generated narrative summary. Null until enough ratings have accumulated for the popularity-bucket cadence to generate one." } }, "required": [ "podcast_id", "entries" ], "type": "object" }, "PodcastSearchMatch": { "additionalProperties": false, "properties": { "clips": { "description": "Highlight clips that overlap this segment, when any exist. Omitted when format=compact.", "items": { "$ref": "#/components/schemas/Clip" }, "type": [ "array", "null" ] }, "episode": { "$ref": "#/components/schemas/EpisodeCompactWithPodcast", "description": "Episode containing the match" }, "match": { "$ref": "#/components/schemas/MatchMetadata", "description": "Source and relevance metadata" }, "segment": { "$ref": "#/components/schemas/Segment", "description": "Matching segment" }, "windows": { "description": "Bounded transcript windows highlighting the relevant lines. Omitted when format=compact; otherwise at least one window whenever the segment's transcript is loaded.", "items": { "$ref": "#/components/schemas/TranscriptWindow" }, "type": [ "array", "null" ] } }, "required": [ "episode", "segment", "match" ], "type": "object" }, "PodcastSearchPage": { "additionalProperties": false, "properties": { "company": { "$ref": "#/components/schemas/CompanyCompact", "description": "Resolved company, when company_id filtered the result set. Omitted when only entity_id was provided." }, "cursor": { "description": "Opaque cursor; pass back as ?cursor= for the next page", "type": "string" }, "data": { "description": "Matches on this page, ranked by relevance (default) or recency", "items": { "$ref": "#/components/schemas/PodcastSearchMatch" }, "type": [ "array", "null" ] }, "diagnostics": { "$ref": "#/components/schemas/SearchDiagnostics", "description": "Present only when data is empty: which filter excluded everything, why, and the parameter change to retry with." }, "entity": { "$ref": "#/components/schemas/EntityCompact", "description": "Resolved entity, when entity_id or company_id filtered the result set" }, "has_more": { "description": "More results available", "type": "boolean" } }, "required": [ "data", "has_more" ], "type": "object" }, "PodcastSpeaker": { "additionalProperties": false, "properties": { "entity": { "$ref": "#/components/schemas/EntityCompact", "description": "Linked knowledge graph entity, when this speaker is identified" }, "name": { "description": "Speaker name", "type": "string" }, "occurrences": { "description": "Number of episodes featuring this speaker", "format": "int64", "type": "integer" }, "role": { "description": "Speaker role, drawn from the same canonical set as the episode speakers. This show-level view surfaces the podcast's recurring hosts, so expect HOST here; read the per-episode speakers for guests, advertisers, and the rest of the role range.", "type": "string" } }, "required": [ "name" ], "type": "object" }, "PodcastSponsorEntry": { "additionalProperties": false, "properties": { "ad_count": { "description": "Total ads on this podcast from this sponsor", "format": "int64", "type": "integer" }, "episode_count": { "description": "Distinct episodes of this podcast featuring the sponsor", "format": "int64", "type": "integer" }, "last_seen_at": { "description": "Publication time of the sponsor's most recent ad on this podcast", "format": "date-time", "type": "string" }, "sponsor": { "$ref": "#/components/schemas/SponsorCompact", "description": "Sponsor advertising on the podcast" } }, "required": [ "sponsor", "episode_count", "ad_count" ], "type": "object" }, "PodcastStats": { "additionalProperties": false, "properties": { "episodes": { "$ref": "#/components/schemas/EpisodeStats", "description": "Episode activity across the catalog." }, "podcasts": { "$ref": "#/components/schemas/PodcastTotals", "description": "Catalog-wide podcast counts." } }, "required": [ "podcasts", "episodes" ], "type": "object" }, "PodcastSuitabilityAnalysis": { "additionalProperties": false, "properties": { "categories": { "description": "Per-category breakdown across all 12 brand-safety categories. Always 12 entries even when prevalence is NONE — the assessment records that every category was actively considered.", "items": { "$ref": "#/components/schemas/PodcastSuitabilityCategory" }, "type": [ "array", "null" ] }, "confidence": { "description": "Agent confidence in the verdict: LOW, MEDIUM, or HIGH.", "type": "string" }, "episodes_analyzed": { "description": "Number of episodes that informed the assessment.", "format": "int64", "type": "integer" }, "evaluated_at": { "description": "When the assessment was performed.", "format": "date-time", "type": "string" }, "history": { "description": "Prior assessments ordered most-recent first. Present when include=history.", "items": { "$ref": "#/components/schemas/PodcastSuitabilityHistoryEntry" }, "type": [ "array", "null" ] }, "methodology": { "description": "Note on what the agent sampled (segments + transcripts read, sponsor cross-checks).", "type": "string" }, "overall_tier": { "description": "Suitability verdict: SAFE (Low Risk), LIMITED (Medium), SENSITIVE (High), or UNSAFE (Brand Safety Floor).", "type": "string" }, "sample_episode_ids": { "description": "Episode IDs in the contiguous window the agent analyzed.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "sample_window_end_at": { "description": "Published-at of the newest episode in the assessment window.", "format": "date-time", "type": "string" }, "sample_window_start_at": { "description": "Published-at of the oldest episode in the assessment window.", "format": "date-time", "type": "string" }, "summary": { "description": "Customer-facing 2-4 sentence explanation of the verdict.", "type": "string" }, "trend": { "$ref": "#/components/schemas/PodcastSuitabilityTrend", "description": "Deterministic comparison against the prior assessment. Present when include=trend; INSUFFICIENT_HISTORY before a second assessment exists." } }, "required": [ "overall_tier", "confidence", "summary", "methodology", "categories", "sample_window_start_at", "sample_window_end_at", "evaluated_at" ], "type": "object" }, "PodcastSuitabilityCategory": { "additionalProperties": false, "properties": { "code": { "description": "Brand-safety category code (IAB Tech Lab Content Taxonomy 3.x): adult_sexual, arms_ammunition, crime_harmful_acts, death_injury_military_conflict, online_piracy, hate_speech_aggression, obscenity_profanity, illegal_drugs_alcohol_tobacco, spam_harmful, terrorism, debated_social_issues, misinformation.", "type": "string" }, "description": { "description": "Human-readable description of the category.", "type": "string" }, "evidence": { "description": "Episode-grounded evidence excerpts. Present when prevalence is anything other than NONE.", "items": { "$ref": "#/components/schemas/PodcastSuitabilityEvidence" }, "type": [ "array", "null" ] }, "prevalence": { "description": "How often the category appears in the analyzed window: NONE, INCIDENTAL, OCCASIONAL, FREQUENT, PERVASIVE.", "type": "string" }, "reasoning": { "description": "Customer-facing justification for the prevalence + treatment finding.", "type": "string" }, "risk_level": { "description": "Risk level derived deterministically from prevalence, treatment, and category. NONE, LOW, MEDIUM, HIGH, or FLOOR (violates the Brand Safety Floor).", "type": "string" }, "treatment": { "description": "How the category is framed: ABSENT, DOCUMENTARY (neutral journalism), EDITORIAL (opinion or comedy), PROMOTIONAL (endorsement without celebration), or GLAMORIZING (celebrating/normalizing).", "type": "string" }, "verdict_basis": { "description": "Source of signal for this finding: 'content' means the show's editorial substance surfaces the category (host monologue, narrative, journalism, opinion, comedy); 'advertising' means only the show's sponsor ad-reads surface it; 'both' means both editorial and advertising signals are present. Use this to filter findings driven by editorial content separately from findings driven by sponsor adjacency. Omitted when the category was not observed (prevalence is NONE).", "type": "string" } }, "required": [ "code", "description", "prevalence", "treatment", "risk_level", "reasoning" ], "type": "object" }, "PodcastSuitabilityEvidence": { "additionalProperties": false, "properties": { "episode_id": { "description": "Episode the excerpt is drawn from.", "type": "string" }, "episode_slug": { "description": "Episode slug.", "type": "string" }, "episode_title": { "description": "Episode title.", "type": "string" }, "excerpt": { "description": "Verbatim excerpt or paraphrase grounding the finding.", "type": "string" } }, "required": [ "episode_id", "episode_title", "excerpt" ], "type": "object" }, "PodcastSuitabilityHistoryEntry": { "additionalProperties": false, "properties": { "confidence": { "type": "string" }, "episodes_analyzed": { "format": "int64", "type": "integer" }, "evaluated_at": { "format": "date-time", "type": "string" }, "overall_tier": { "type": "string" }, "sample_window_end_at": { "format": "date-time", "type": "string" }, "sample_window_start_at": { "format": "date-time", "type": "string" } }, "required": [ "overall_tier", "confidence", "episodes_analyzed", "sample_window_start_at", "sample_window_end_at", "evaluated_at" ], "type": "object" }, "PodcastSuitabilityTrend": { "additionalProperties": false, "properties": { "changed_categories": { "description": "Categories whose prevalence or treatment changed between assessments.", "items": { "$ref": "#/components/schemas/PodcastSuitabilityTrendChange" }, "type": [ "array", "null" ] }, "direction": { "description": "INSUFFICIENT_HISTORY (fewer than two assessments), STABLE, IMPROVING, or DECLINING.", "type": "string" }, "prior_evaluated_at": { "description": "When the prior assessment was performed. Omitted when there is no prior.", "format": "date-time", "type": "string" } }, "required": [ "direction" ], "type": "object" }, "PodcastSuitabilityTrendChange": { "additionalProperties": false, "properties": { "code": { "type": "string" }, "new_prevalence": { "type": "string" }, "new_risk_level": { "type": "string" }, "new_treatment": { "type": "string" }, "prior_prevalence": { "type": "string" }, "prior_risk_level": { "type": "string" }, "prior_treatment": { "type": "string" } }, "required": [ "code", "prior_prevalence", "new_prevalence", "prior_treatment", "new_treatment", "prior_risk_level", "new_risk_level" ], "type": "object" }, "PodcastTopic": { "additionalProperties": false, "properties": { "ancestry_path": { "description": "Hash-based ancestry path for programmatic filtering", "type": "string" }, "id": { "description": "Unique identifier", "type": "string" }, "name": { "description": "Topic name", "type": "string" }, "podcast_count": { "description": "Number of podcasts covering this topic", "format": "int64", "type": "integer" }, "slug": { "description": "Topic slug, usable as topic_id", "type": "string" } }, "required": [ "id", "name", "slug", "podcast_count" ], "type": "object" }, "PodcastTotals": { "additionalProperties": false, "properties": { "totals": { "description": "Podcast counts by classification. Sum the entries for the total catalog size.", "items": { "$ref": "#/components/schemas/ClassificationCount" }, "type": [ "array", "null" ] } }, "required": [ "totals" ], "type": "object" }, "PrevalenceBreakdown": { "additionalProperties": false, "properties": { "frequent": { "description": "Number where it appears FREQUENTLY.", "format": "int64", "type": "integer" }, "incidental": { "description": "Number where the category appears INCIDENTALLY.", "format": "int64", "type": "integer" }, "none": { "description": "Number of analyzed podcasts where this category is absent (NONE prevalence).", "format": "int64", "type": "integer" }, "occasional": { "description": "Number where it appears OCCASIONALLY.", "format": "int64", "type": "integer" }, "pervasive": { "description": "Number where it is PERVASIVE.", "format": "int64", "type": "integer" } }, "required": [ "none", "incidental", "occasional", "frequent", "pervasive" ], "type": "object" }, "PreviewAlertBody": { "additionalProperties": false, "properties": { "entities": { "description": "Same as CreateAlertBody.entities — exactly one for entity kinds, omitted for KEYWORD_MENTION.", "items": { "$ref": "#/components/schemas/AlertEntity" }, "maxItems": 1, "minItems": 1, "type": [ "array", "null" ] }, "filters": { "$ref": "#/components/schemas/AlertFilters", "description": "Same as CreateAlertBody.filters. Pass the filters you intend to save so the estimate reflects what the alert would actually surface. Only languages and speaker_roles narrow the historical sweep; relevance and source_popularity are read-time projections that don't run on historical episodes, so setting them leaves the count unchanged (the estimate is an upper bound when relevance=RELEVANT)." }, "keyword": { "description": "Same as CreateAlertBody.keyword — required for KEYWORD_MENTION, rejected otherwise. A phrase that matched more than 700 podcast episodes in the past week is rejected with 422, as on create.", "maxLength": 100, "type": "string" }, "kind": { "description": "Same as CreateAlertBody.kind. Defaults to ENTITY_MENTION.", "enum": [ "ENTITY_MENTION", "PODCAST_SPEAKER", "KEYWORD_MENTION" ], "type": "string" } }, "type": "object" }, "PreviewAlertResponseBody": { "additionalProperties": false, "properties": { "preview_id": { "description": "Deterministic preview ID — repeating the same body within the TTL returns the same ID. Poll GET /v1/alerts/preview/{previewId} when status is 'in_progress'.", "type": "string" }, "status": { "description": "'in_progress' means a sweep is running (or was just started); 'completed' means an earlier identical preview is still cached and the result is ready to fetch via GET. A 'failed' prior preview is treated as a cache miss and a fresh sweep is started — callers never see 'failed' on this endpoint.", "enum": [ "in_progress", "completed" ], "type": "string" }, "window_days": { "format": "int64", "type": "integer" } }, "required": [ "preview_id", "status", "window_days" ], "type": "object" }, "PublisherAdvertisingCoverage": { "additionalProperties": false, "properties": { "active_coverage": { "description": "active_podcasts / total_podcasts, clamped to [0, 1]. Treat as a confidence proxy for the rolled-up totals.", "format": "double", "type": "number" }, "active_podcasts": { "description": "Number of catalog podcasts that have at least one detected ad.", "format": "int64", "type": "integer" }, "total_podcasts": { "description": "Number of podcasts in the publisher's catalog (denormalized from podcast_publishers.podcast_count).", "format": "int64", "type": "integer" } }, "required": [ "total_podcasts", "active_podcasts", "active_coverage" ], "type": "object" }, "PublisherAdvertisingLeaderboardEntry": { "additionalProperties": false, "properties": { "ad_count": { "description": "Total ads across the publisher's catalog", "format": "int64", "type": "integer" }, "ads_per_active_podcast": { "description": "Mean ad count across active podcasts — monetization density.", "format": "double", "type": "number" }, "coverage": { "$ref": "#/components/schemas/PublisherAdvertisingCoverage", "description": "Catalog size and how much of it carries ads." }, "episode_reach": { "description": "Distinct episodes with ads", "format": "int64", "type": "integer" }, "publisher": { "$ref": "#/components/schemas/PodcastPublisherCompact", "description": "Publisher reference" }, "rank": { "description": "Position in the leaderboard", "format": "int64", "type": "integer" }, "unique_sponsors": { "description": "Distinct sponsors across the catalog", "format": "int64", "type": "integer" } }, "required": [ "rank", "publisher", "coverage", "ad_count", "unique_sponsors", "episode_reach", "ads_per_active_podcast" ], "type": "object" }, "PublisherAdvertisingPodcastEntry": { "additionalProperties": false, "properties": { "ad_count": { "description": "Total ads detected on this podcast", "format": "int64", "type": "integer" }, "avg_ads_per_episode": { "description": "Mean ads per episode (across episodes with ads)", "format": "double", "type": "number" }, "episodes_with_ads": { "description": "Episodes containing at least one ad", "format": "int64", "type": "integer" }, "podcast": { "$ref": "#/components/schemas/PodcastCompact", "description": "Podcast reference" }, "read_type_breakdown": { "$ref": "#/components/schemas/ReadTypeBreakdown", "description": "Distribution of ad read types" }, "unique_sponsors": { "description": "Distinct sponsors on this podcast", "format": "int64", "type": "integer" } }, "required": [ "podcast", "ad_count", "unique_sponsors", "episodes_with_ads", "avg_ads_per_episode", "read_type_breakdown" ], "type": "object" }, "PublisherAdvertisingProfile": { "additionalProperties": false, "properties": { "ads_per_active_podcast": { "description": "Mean ad count across podcasts that ran at least one ad — monetization density. Same metric the cross-publisher leaderboard ranks on.", "format": "double", "type": "number" }, "coverage": { "$ref": "#/components/schemas/PublisherAdvertisingCoverage", "description": "Catalog size and how much of it carries ads." }, "episode_reach": { "description": "Distinct episodes with ads", "format": "int64", "type": "integer" }, "network_buyers_count": { "description": "Sponsors hitting at least 3 podcasts and at least 25% of the publisher's catalog — the bundle-buy signal.", "format": "int64", "type": "integer" }, "publisher": { "$ref": "#/components/schemas/PodcastPublisherCompact", "description": "The publisher whose catalog is summarized." }, "read_type_breakdown": { "$ref": "#/components/schemas/ReadTypeBreakdown", "description": "Distribution of ad read types" }, "top_sponsors": { "description": "Most frequent sponsors across the catalog", "items": { "$ref": "#/components/schemas/TopPublisherSponsor" }, "type": [ "array", "null" ] }, "total_ads": { "description": "Total ads detected across the catalog (excludes network promos)", "format": "int64", "type": "integer" }, "unique_sponsors": { "description": "Distinct sponsors across the catalog", "format": "int64", "type": "integer" } }, "required": [ "publisher", "coverage", "total_ads", "unique_sponsors", "episode_reach", "ads_per_active_podcast", "read_type_breakdown", "network_buyers_count", "top_sponsors" ], "type": "object" }, "PublisherSponsorEntry": { "additionalProperties": false, "properties": { "ad_count": { "description": "Total ads from this sponsor on this publisher's catalog", "format": "int64", "type": "integer" }, "company": { "$ref": "#/components/schemas/CompanyCompact", "description": "Linked company record" }, "coverage_share": { "description": "podcast_coverage / publisher.total_podcasts (0..1). The bundle-buy signal: a sponsor with coverage_share \u003e= 0.25 is doing a network buy across the publisher.", "format": "double", "type": "number" }, "episode_reach": { "description": "Distinct episodes featuring this sponsor on this publisher's catalog", "format": "int64", "type": "integer" }, "first_seen_at": { "description": "Earliest detected ad appearance on this publisher's catalog", "format": "date-time", "type": "string" }, "id": { "description": "Sponsor ID", "type": "string" }, "last_seen_at": { "description": "Most recent ad appearance on this publisher's catalog", "format": "date-time", "type": "string" }, "name": { "description": "Sponsor name", "type": "string" }, "podcast_coverage": { "description": "Distinct podcasts in the publisher where this sponsor appears", "format": "int64", "type": "integer" } }, "required": [ "id", "name", "ad_count", "podcast_coverage", "coverage_share", "episode_reach" ], "type": "object" }, "PublisherSuitabilityCategoryBreakdown": { "additionalProperties": false, "properties": { "code": { "description": "Brand-safety category code (IAB Tech Lab Content Taxonomy 3.x): adult_sexual, arms_ammunition, crime_harmful_acts, death_injury_military_conflict, online_piracy, hate_speech_aggression, obscenity_profanity, illegal_drugs_alcohol_tobacco, spam_harmful, terrorism, debated_social_issues, misinformation.", "type": "string" }, "description": { "description": "Human-readable description of the category.", "type": "string" }, "exposure_share": { "description": "Share of analyzed podcasts with any non-NONE prevalence in this category (0..1).", "format": "double", "type": "number" }, "frequent": { "description": "Number where the category appears FREQUENTLY.", "format": "int64", "type": "integer" }, "glamorizing": { "description": "Number whose category row carries GLAMORIZING treatment (the most advertiser-toxic treatment).", "format": "int64", "type": "integer" }, "high_risk_count": { "description": "Number of analyzed podcasts with FREQUENT/PERVASIVE prevalence or GLAMORIZING treatment in this category — the advertiser-relevant 'this is a real problem' count.", "format": "int64", "type": "integer" }, "incidental": { "description": "Number where this category appears INCIDENTALLY (1-2 references in the analyzed window).", "format": "int64", "type": "integer" }, "none": { "description": "Number of analyzed podcasts where this category is absent.", "format": "int64", "type": "integer" }, "occasional": { "description": "Number where the category appears OCCASIONALLY.", "format": "int64", "type": "integer" }, "pervasive": { "description": "Number where the category is PERVASIVE.", "format": "int64", "type": "integer" }, "promotional": { "description": "Number of analyzed podcasts whose category row carries PROMOTIONAL treatment (endorsement without celebration).", "format": "int64", "type": "integer" } }, "required": [ "code", "description", "none", "incidental", "occasional", "frequent", "pervasive", "promotional", "glamorizing", "high_risk_count", "exposure_share" ], "type": "object" }, "PublisherSuitabilityCategoryPublisherEntry": { "additionalProperties": false, "properties": { "category_code": { "description": "The GARM category this leaderboard pivots on.", "type": "string" }, "coverage": { "$ref": "#/components/schemas/PublisherSuitabilityCoverage", "description": "Catalog size and how much of it has been analyzed." }, "description": { "description": "Human-readable category description.", "type": "string" }, "example_podcasts": { "description": "Up to three example podcasts in the publisher's catalog that exhibit the highest exposure to this category, ranked by prevalence (PERVASIVE first) then treatment (GLAMORIZING first).", "items": { "$ref": "#/components/schemas/PodcastCompact" }, "type": [ "array", "null" ] }, "exposed_count": { "description": "Number of analyzed podcasts whose category row matched the prevalence + treatment filter.", "format": "int64", "type": "integer" }, "exposure_share": { "description": "exposed_count / analyzed_podcasts, clamped to [0, 1].", "format": "double", "type": "number" }, "high_risk_count": { "description": "FREQUENT+PERVASIVE or GLAMORIZING count for this category.", "format": "int64", "type": "integer" }, "prevalence_breakdown": { "$ref": "#/components/schemas/PrevalenceBreakdown", "description": "Per-prevalence counts across analyzed podcasts." }, "publisher": { "$ref": "#/components/schemas/PodcastPublisherCompact", "description": "The ranked publisher." }, "rank": { "description": "1-indexed rank within the current ordering.", "format": "int64", "type": "integer" }, "treatment_breakdown": { "$ref": "#/components/schemas/TreatmentBreakdown", "description": "Per-treatment counts across analyzed podcasts (only PROMOTIONAL and GLAMORIZING — the two advertiser-relevant treatments)." } }, "required": [ "publisher", "rank", "category_code", "description", "coverage", "exposed_count", "exposure_share", "high_risk_count", "prevalence_breakdown", "treatment_breakdown" ], "type": "object" }, "PublisherSuitabilityConfidenceBreakdown": { "additionalProperties": false, "properties": { "high": { "description": "Number with HIGH confidence.", "format": "int64", "type": "integer" }, "low": { "description": "Number of analyzed podcasts whose verdict carries LOW confidence.", "format": "int64", "type": "integer" }, "medium": { "description": "Number with MEDIUM confidence.", "format": "int64", "type": "integer" } }, "required": [ "low", "medium", "high" ], "type": "object" }, "PublisherSuitabilityCoverage": { "additionalProperties": false, "properties": { "analyzed_coverage": { "description": "analyzed_podcasts / total_podcasts, clamped to [0, 1]. Treat as a confidence proxy for the rolled-up verdict.", "format": "double", "type": "number" }, "analyzed_podcasts": { "description": "Number of catalog podcasts that have an IAB/GARM suitability analysis.", "format": "int64", "type": "integer" }, "quality": { "description": "Qualitative read on how representative the rollup is given current analysis coverage: LOW (\u003c 0.3), MEDIUM (0.3-0.7), HIGH (\u003e= 0.7).", "type": "string" }, "total_podcasts": { "description": "Total number of non-deleted podcasts attributed to this publisher (denormalized from podcast_publishers.podcast_count).", "format": "int64", "type": "integer" } }, "required": [ "total_podcasts", "analyzed_podcasts", "analyzed_coverage", "quality" ], "type": "object" }, "PublisherSuitabilityFlaggedCategory": { "additionalProperties": false, "properties": { "code": { "description": "GARM category code.", "type": "string" }, "prevalence": { "description": "INCIDENTAL, OCCASIONAL, FREQUENT, or PERVASIVE.", "type": "string" }, "risk_level": { "description": "Deterministically-derived risk level: NONE, LOW, MEDIUM, HIGH, or FLOOR.", "type": "string" }, "treatment": { "description": "DOCUMENTARY, EDITORIAL, PROMOTIONAL, or GLAMORIZING.", "type": "string" } }, "required": [ "code", "prevalence", "treatment", "risk_level" ], "type": "object" }, "PublisherSuitabilityLeaderboardEntry": { "additionalProperties": false, "properties": { "coverage": { "$ref": "#/components/schemas/PublisherSuitabilityCoverage", "description": "Catalog size and how much of it has been analyzed." }, "metric_value": { "description": "Value of the metric used to rank — a share in [0, 1] for safest/riskiest/most_placeable, an absolute count for most_analyzed.", "format": "double", "type": "number" }, "publisher": { "$ref": "#/components/schemas/PodcastPublisherCompact", "description": "The ranked publisher." }, "rank": { "description": "1-indexed rank within the current ordering.", "format": "int64", "type": "integer" }, "tier_breakdown": { "$ref": "#/components/schemas/PublisherSuitabilityTierBreakdown", "description": "Per-tier composition across analyzed podcasts." } }, "required": [ "publisher", "rank", "coverage", "tier_breakdown", "metric_value" ], "type": "object" }, "PublisherSuitabilityPodcastEntry": { "additionalProperties": false, "properties": { "confidence": { "description": "LOW, MEDIUM, or HIGH.", "type": "string" }, "evaluated_at": { "description": "When the most recent assessment was performed.", "format": "date-time", "type": "string" }, "flagged_categories": { "description": "Categories with non-NONE prevalence in the most recent assessment. Empty when the podcast came back clean across every dimension. Reasoning and evidence excerpts are not surfaced here — fetch /v1/podcasts/{id}/suitability for per-category detail.", "items": { "$ref": "#/components/schemas/PublisherSuitabilityFlaggedCategory" }, "type": [ "array", "null" ] }, "overall_tier": { "description": "SAFE, LIMITED, SENSITIVE, or UNSAFE.", "type": "string" }, "podcast": { "$ref": "#/components/schemas/PodcastCompact", "description": "The podcast this entry summarizes." } }, "required": [ "podcast", "overall_tier", "confidence", "evaluated_at" ], "type": "object" }, "PublisherSuitabilityProfile": { "additionalProperties": false, "properties": { "category_breakdown": { "description": "Per-GARM-category roll-up across the publisher's analyzed catalog. Always 12 entries in canonical order so callers don't need to merge against the canonical category list. For an analyzed publisher with no exposure in a given category, none equals analyzed_podcasts and every other bucket is 0; only when the publisher has zero analyzed podcasts are all five prevalence buckets 0.", "items": { "$ref": "#/components/schemas/PublisherSuitabilityCategoryBreakdown" }, "type": [ "array", "null" ] }, "confidence_breakdown": { "$ref": "#/components/schemas/PublisherSuitabilityConfidenceBreakdown", "description": "How confident the agent was in the verdicts that produced this rollup, summed across analyzed podcasts." }, "coverage": { "$ref": "#/components/schemas/PublisherSuitabilityCoverage", "description": "Catalog size and how much of it has been analyzed." }, "last_evaluated_at": { "description": "Most recent evaluation timestamp across the publisher's analyses. Omitted when the publisher has zero analyzed podcasts.", "format": "date-time", "type": "string" }, "publisher": { "$ref": "#/components/schemas/PodcastPublisherCompact", "description": "The publisher whose catalog is summarized." }, "tier_breakdown": { "$ref": "#/components/schemas/PublisherSuitabilityTierBreakdown", "description": "Distribution of analyzed podcasts across the four IAB/GARM tiers (SAFE, LIMITED, SENSITIVE, UNSAFE), with counts and shares." }, "top_concerns": { "description": "Up to three highest-exposure GARM categories ranked by high_risk_count, surfaced separately so advertisers can scan the publisher's worst dimensions without traversing the full breakdown.", "items": { "$ref": "#/components/schemas/PublisherSuitabilityTopConcern" }, "type": [ "array", "null" ] } }, "required": [ "publisher", "coverage", "tier_breakdown", "confidence_breakdown", "category_breakdown" ], "type": "object" }, "PublisherSuitabilityTierBreakdown": { "additionalProperties": false, "properties": { "limited": { "description": "Number assigned LIMITED (Medium Risk).", "format": "int64", "type": "integer" }, "limited_share": { "description": "Share assigned LIMITED (0..1).", "format": "double", "type": "number" }, "placeable_share": { "description": "Combined SAFE + LIMITED share (0..1) — the 'broadly buyable' slice an advertiser without category restrictions can typically reach.", "format": "double", "type": "number" }, "safe": { "description": "Number of analyzed podcasts assigned the SAFE (Low Risk) tier.", "format": "int64", "type": "integer" }, "safe_share": { "description": "Share of analyzed podcasts assigned SAFE (0..1).", "format": "double", "type": "number" }, "sensitive": { "description": "Number assigned SENSITIVE (High Risk).", "format": "int64", "type": "integer" }, "sensitive_share": { "description": "Share assigned SENSITIVE (0..1).", "format": "double", "type": "number" }, "unsafe": { "description": "Number assigned UNSAFE (Brand Safety Floor).", "format": "int64", "type": "integer" }, "unsafe_share": { "description": "Share assigned UNSAFE (0..1).", "format": "double", "type": "number" } }, "required": [ "safe", "limited", "sensitive", "unsafe", "safe_share", "limited_share", "sensitive_share", "unsafe_share", "placeable_share" ], "type": "object" }, "PublisherSuitabilityTopConcern": { "additionalProperties": false, "properties": { "code": { "description": "GARM category code.", "type": "string" }, "description": { "description": "Human-readable category description.", "type": "string" }, "exposure_share": { "description": "Share of analyzed podcasts with any non-NONE prevalence in this category (0..1).", "format": "double", "type": "number" }, "high_risk_count": { "description": "FREQUENT+PERVASIVE or GLAMORIZING count for this category.", "format": "int64", "type": "integer" } }, "required": [ "code", "description", "high_risk_count", "exposure_share" ], "type": "object" }, "ReadTypeBreakdown": { "additionalProperties": false, "properties": { "host_read": { "description": "Number of host-read ads", "format": "int64", "type": "integer" }, "pre_recorded": { "description": "Number of pre-recorded ads", "format": "int64", "type": "integer" } }, "required": [ "host_read", "pre_recorded" ], "type": "object" }, "RecommendedContact": { "additionalProperties": false, "properties": { "linkedin_url": { "description": "The person's LinkedIn profile when known — an InMail path even without an email.", "type": "string" }, "person": { "$ref": "#/components/schemas/PersonCompact", "description": "The person; the slug feeds GET /v1/people/{id}." }, "role": { "description": "Contact role class derived from the title; contacts are ordered by how likely the class is to own a sponsorship decision.", "enum": [ "marketing", "brand", "partnerships", "media_advertising", "communications", "growth", "executive", "other" ], "type": "string" }, "title": { "description": "Current title at the company, as recorded.", "type": "string" } }, "required": [ "person", "role" ], "type": "object" }, "RecommendedGuest": { "additionalProperties": false, "properties": { "band": { "description": "Coarse class of the score.", "enum": [ "strong", "moderate", "weak" ], "type": "string" }, "person": { "$ref": "#/components/schemas/PersonCompact", "description": "The recommended guest." }, "score": { "description": "Strength of the recommendation in (0,1): how related the shows that booked this person are, counted once per publisher and damped for how widely the person already circulates. Recurring on any one show does not raise it, and circuit regulars who appear everywhere are excluded.", "format": "double", "type": "number" }, "shared_show_count": { "description": "How many of the show's related shows have booked this person.", "format": "int64", "type": "integer" }, "via": { "description": "The related shows that booked this person, strongest first.", "items": { "$ref": "#/components/schemas/PodcastCompact" }, "type": [ "array", "null" ] } }, "required": [ "person", "score", "band", "shared_show_count" ], "type": "object" }, "RecommendedPodcast": { "additionalProperties": false, "properties": { "band": { "description": "Coarse class of the score; branch on this rather than on exact thresholds.", "enum": [ "strong", "moderate", "weak" ], "type": "string" }, "podcast": { "$ref": "#/components/schemas/PodcastCompact", "description": "The recommended podcast." }, "score": { "description": "Strength of the recommendation in (0,1): the seed shows' relatedness to this one, compounded across the seeds that list it. For a guest the seeds are the shows that booked them, counted once per publisher; for a company the shows it already advertises on, weighted by how much it advertises there.", "format": "double", "type": "number" }, "via": { "description": "The seed shows that led to this recommendation, strongest first: the person's own shows, or the shows the company already buys. The reason to cite when explaining the fit.", "items": { "$ref": "#/components/schemas/PodcastCompact" }, "type": [ "array", "null" ] } }, "required": [ "podcast", "score", "band" ], "type": "object" }, "RecommendedSponsor": { "additionalProperties": false, "properties": { "band": { "description": "Coarse class of the score; branch on this rather than on exact thresholds.", "enum": [ "strong", "moderate", "weak" ], "type": "string" }, "company_contested": { "description": "Whether the company link is disputed: true when the recent majority is under 60%, when the declared domain does not map to a company, when a mapped domain is contradicted by an ad majority of 60% or more, and for every all-time fallback; a weak disagreement with a mapped domain is not contested. A contested company is the best available guess — it is still served, but contacts are withheld.", "type": "boolean" }, "contacts": { "description": "Up to three people at the sponsor's company most likely to own a podcast sponsorship decision (marketing, partnerships, brand, media, communications, growth, then other executives), each with the role class and a LinkedIn URL when known. Present only with include=contacts, only when the sponsor resolves to a company, and never when company_contested is true.", "items": { "$ref": "#/components/schemas/RecommendedContact" }, "type": [ "array", "null" ] }, "last_ad_at": { "description": "Publish date of the sponsor's most recent ad across those shows.", "format": "date-time", "type": "string" }, "score": { "description": "Strength of the recommendation in (0,1): how related the shows that run this sponsor are, counted once per publisher, weighted by whether it is still buying there and how much (saturating after about twenty reads). Compounds across publishers.", "format": "double", "type": "number" }, "shared_show_count": { "description": "How many of the show's related shows run this sponsor.", "format": "int64", "type": "integer" }, "sponsor": { "$ref": "#/components/schemas/SponsorCompact", "description": "The recommended sponsor, with its linked company when known — the company record is the path to people to contact. Sponsor records that resolve to the same company (or the same name) are one row, named by the strongest of them. The link is resolved from the sponsor's declared domain when it maps to one live company, else the company most of its ads that aired in the last 180 days were attributed to, else the all-time majority." }, "total_ads": { "description": "The sponsor's ad reads summed over those related shows (network promos excluded).", "format": "int64", "type": "integer" }, "via": { "description": "The related shows that run this sponsor, most related first (at most three) — the peer set to cite in a pitch.", "items": { "$ref": "#/components/schemas/PodcastCompact" }, "type": [ "array", "null" ] } }, "required": [ "sponsor", "score", "band", "shared_show_count", "total_ads" ], "type": "object" }, "RelatedCoverage": { "additionalProperties": false, "properties": { "computed_at": { "description": "When the related set was last computed; present on every status except not_computed.", "format": "date-time", "type": "string" }, "message": { "description": "Human-readable explanation of the status.", "type": "string" }, "status": { "description": "not_computed: the related set has not been computed yet (retry later); none_above_floor: it was computed and no show cleared the relatedness floor, typically because this show has too few embedded episodes; filtered_out: shows cleared the floor but every one was removed, by the request's filters or by the default policy (flagged feeds, a publisher's duplicate feeds, removed shows).", "enum": [ "not_computed", "none_above_floor", "filtered_out" ], "type": "string" } }, "required": [ "status", "message" ], "type": "object" }, "RelatedEpisode": { "additionalProperties": false, "properties": { "band": { "description": "Coarse class of the score: strong (the same story or subject), moderate (overlapping subject), weak (a loose connection). Branch on this rather than on exact score thresholds.", "enum": [ "strong", "moderate", "weak" ], "type": "string" }, "basis": { "$ref": "#/components/schemas/RelatedEpisodeBasis", "description": "Why the episodes are related. Present only with include=basis." }, "episode": { "$ref": "#/components/schemas/EpisodeCompactWithPodcast", "description": "The related episode with its parent podcast." }, "score": { "description": "Fused relatedness in (0,1]; higher is more likely to be judged related. Comparable across episodes.", "format": "double", "type": "number" } }, "required": [ "episode", "score", "band" ], "type": "object" }, "RelatedEpisodeBasis": { "additionalProperties": false, "properties": { "content_similarity": { "description": "Cosine similarity of the two episodes' content centroids in [0,1]; omitted when either episode has no embedded content segments.", "format": "double", "type": "number" }, "days_apart": { "description": "Absolute difference between the two publish dates, in days. Omitted when either episode has no publish date.", "format": "double", "type": "number" }, "shared_entities": { "description": "Up to three shared entities that contribute most, most significant first. Their ids feed GET /v1/entities/{id} and the mentions tools.", "items": { "$ref": "#/components/schemas/RelatedEpisodeEntity" }, "type": [ "array", "null" ] }, "shared_entity_count": { "description": "Number of salient knowledge-graph entities both episodes are about.", "format": "int64", "type": "integer" }, "shared_guest_count": { "description": "Number of guests who appear in both episodes.", "format": "int64", "type": "integer" }, "shared_story_count": { "description": "Number of news stories both episodes were linked to. Non-zero means the two episodes discuss the same story.", "format": "int64", "type": "integer" }, "shared_topic_count": { "description": "Number of taxonomy topics both episodes were classified under.", "format": "int64", "type": "integer" } }, "required": [ "shared_entity_count", "shared_topic_count", "shared_story_count", "shared_guest_count" ], "type": "object" }, "RelatedEpisodeEntity": { "additionalProperties": false, "properties": { "id": { "description": "Knowledge-graph entity id, valid on GET /v1/entities/{id}.", "type": "string" }, "name": { "description": "Entity name.", "type": "string" } }, "required": [ "id", "name" ], "type": "object" }, "RelatedPodcast": { "additionalProperties": false, "properties": { "band": { "description": "Coarse class of the score: strong (same beat and audience), moderate (overlapping subject or audience), weak (a loose connection). Branch on this rather than on exact score thresholds.", "enum": [ "strong", "moderate", "weak" ], "type": "string" }, "basis": { "$ref": "#/components/schemas/RelatedPodcastBasis", "description": "Why the shows are related. Present only with include=basis." }, "podcast": { "$ref": "#/components/schemas/PodcastCompact", "description": "The related podcast." }, "score": { "description": "Fused relatedness in (0,1], calibrated so that higher values are more likely to be judged related. Comparable across shows.", "format": "double", "type": "number" } }, "required": [ "podcast", "score", "band" ], "type": "object" }, "RelatedPodcastBasis": { "additionalProperties": false, "properties": { "content_similarity": { "description": "Cosine similarity of the two shows' content centroids in [0,1]; omitted when either show has too few embedded episodes.", "format": "double", "type": "number" }, "same_publisher": { "description": "Both shows belong to the same multi-show publisher (network).", "type": "boolean" }, "shared_category_count": { "description": "Number of directory categories the shows share.", "format": "int64", "type": "integer" }, "shared_guest_count": { "description": "Number of guests who appeared on both shows.", "format": "int64", "type": "integer" }, "shared_guests": { "description": "Up to three of the shared guests, most significant first.", "items": { "$ref": "#/components/schemas/PersonCompact" }, "type": [ "array", "null" ] }, "shared_sponsor_count": { "description": "Number of advertisers both shows have carried.", "format": "int64", "type": "integer" }, "shared_topics": { "description": "Up to three topics that contribute most to the overlap.", "items": { "$ref": "#/components/schemas/Topic" }, "type": [ "array", "null" ] }, "topic_overlap": { "description": "Overlap of the shows' topic profiles in [0,1].", "format": "double", "type": "number" } }, "required": [ "shared_guest_count", "same_publisher", "shared_sponsor_count", "shared_category_count" ], "type": "object" }, "RelatedPodcastsPage": { "additionalProperties": false, "properties": { "coverage": { "$ref": "#/components/schemas/RelatedCoverage", "description": "Present only when the first page is empty: why there is nothing to show. Absent whenever data has rows or when paging past the end." }, "cursor": { "description": "Pass to next request for more results", "type": "string" }, "data": { "description": "List of results", "items": { "$ref": "#/components/schemas/RelatedPodcast" }, "type": [ "array", "null" ] }, "has_more": { "description": "Whether more results exist", "type": "boolean" } }, "required": [ "data", "has_more" ], "type": "object" }, "SearchDiagnostics": { "additionalProperties": false, "properties": { "filters": { "description": "Every filter the request applied, in the order applied.", "items": { "$ref": "#/components/schemas/SearchFilterReport" }, "type": [ "array", "null" ] }, "next_steps": { "description": "Concrete retries, most likely to succeed first.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "outcome": { "description": "Stable classification of why the page is empty.", "enum": [ "filter_too_narrow", "over_constrained", "no_match_for_query" ], "type": "string" }, "summary": { "description": "One-sentence plain statement of what emptied the results.", "type": "string" } }, "required": [ "outcome", "summary" ], "type": "object" }, "SearchFilterReport": { "additionalProperties": false, "properties": { "emptied_results": { "description": "True when removing only this filter makes the search return results.", "type": "boolean" }, "parameter": { "description": "The request parameter this filter came from.", "type": "string" }, "remedy": { "description": "Why this filter excluded everything, and what to change.", "type": "string" }, "retry_with": { "additionalProperties": { "type": "string" }, "description": "Parameter changes to apply to the same request to recover results. An empty value means remove that parameter.", "type": "object" }, "value": { "description": "The value the request supplied for it.", "type": "string" } }, "required": [ "parameter" ], "type": "object" }, "Segment": { "additionalProperties": false, "properties": { "audio_url": { "description": "Direct audio URL for this segment", "type": "string" }, "description": { "description": "AI-generated segment description", "type": "string" }, "duration_seconds": { "description": "Segment duration", "format": "double", "type": "number" }, "end_line": { "description": "Last transcript line covered by this segment (1-indexed, inclusive). Omitted for episodes segmented before line ranges were recorded.", "format": "int64", "type": "integer" }, "end_seconds": { "description": "End time within the episode — when the segment's last spoken line ends. Where start_line/end_line are present, segments partition the transcript's lines rather than tiling the wall-clock timeline, and the interval between this and the next segment's start_seconds contains no transcribed speech (typically under a second, occasionally minutes of music or silence). Segments without a recorded line range were produced by an earlier segmenter and a small share of them do leave transcript lines uncovered, so a gap between two such segments may contain real speech. Use start_line/end_line to slice a transcript losslessly.", "format": "double", "type": "number" }, "episode": { "$ref": "#/components/schemas/EpisodeCompactWithPodcast", "description": "Parent episode with podcast context" }, "id": { "description": "Unique identifier", "type": "string" }, "number": { "description": "Segment position within the episode", "format": "int64", "type": "integer" }, "read_type": { "description": "For AD segments, how the ad was delivered (HOST_READ, PRE_RECORDED, NETWORK_PROMO)", "type": "string" }, "start_line": { "description": "First transcript line covered by this segment (1-indexed, inclusive). Line numbers match the number field of GET /v1/podcasts/episodes/{id}/transcript lines. This segment's end_line + 1 is the next segment's start_line, and the segments together cover every line of the transcript. Omitted for episodes segmented before line ranges were recorded.", "format": "int64", "type": "integer" }, "start_seconds": { "description": "Start time within the episode — when the segment's first spoken line begins", "format": "double", "type": "number" }, "summary": { "description": "AI-generated segment summary", "type": "string" }, "title": { "description": "AI-generated segment title", "type": "string" }, "type": { "description": "Segment type (INTRO, PERSONAL_BANTER, TOPIC_DISCUSSION, INTERVIEW, TRANSITION, AD, OUTRO)", "type": "string" } }, "required": [ "id", "number", "type", "title", "start_seconds", "end_seconds", "duration_seconds" ], "type": "object" }, "SegmentCompact": { "additionalProperties": false, "properties": { "id": { "description": "Segment ID", "type": "string" }, "title": { "description": "Segment title", "type": "string" }, "type": { "description": "Segment type", "type": "string" } }, "required": [ "id", "type", "title" ], "type": "object" }, "ShowSummary": { "additionalProperties": false, "properties": { "content_advisory_rating": { "description": "Source-supplied content advisory rating (e.g. 'clean', 'explicit').", "type": "string" }, "description": { "description": "Show description as reported by the source.", "type": "string" }, "feed_url": { "description": "Show's RSS feed URL as reported by the source.", "type": "string" }, "genres": { "description": "Source-reported genre tags (Apple).", "items": { "$ref": "#/components/schemas/Genre" }, "type": [ "array", "null" ] }, "image_url": { "description": "Best-quality cover art URL available from the source.", "type": "string" }, "language": { "description": "ISO 639 language tag as reported by the source.", "type": "string" }, "latest_release_date": { "description": "Source-reported latest episode release date, when present.", "format": "date-time", "type": "string" }, "name": { "description": "Show name as reported by the source.", "type": "string" }, "publisher": { "description": "Publisher name as reported by the source.", "type": "string" }, "total_episodes": { "description": "Source-reported episode count, when present.", "format": "int64", "type": "integer" } }, "required": [ "name" ], "type": "object" }, "SourceAppearanceStat": { "additionalProperties": false, "properties": { "best_category_slug": { "type": "string" }, "best_country": { "type": "string" }, "best_rank": { "format": "int64", "type": "integer" }, "chart_count": { "format": "int64", "type": "integer" }, "source": { "enum": [ "apple", "spotify" ], "type": "string" } }, "required": [ "source", "chart_count", "best_rank" ], "type": "object" }, "Sponsor": { "additionalProperties": false, "properties": { "ad_count": { "description": "Total number of ads (excluding network promos)", "format": "int64", "type": "integer" }, "company": { "$ref": "#/components/schemas/CompanyCompact", "description": "Linked company record" }, "episode_reach": { "description": "Number of distinct episodes featuring the sponsor", "format": "int64", "type": "integer" }, "first_seen_at": { "description": "Earliest detected ad appearance", "format": "date-time", "type": "string" }, "id": { "description": "Unique identifier", "type": "string" }, "last_seen_at": { "description": "Most recent ad appearance", "format": "date-time", "type": "string" }, "name": { "description": "Sponsor name", "type": "string" }, "podcast_reach": { "description": "Number of distinct podcasts the sponsor advertises on", "format": "int64", "type": "integer" } }, "required": [ "id", "name", "ad_count", "podcast_reach", "episode_reach" ], "type": "object" }, "SponsorCompact": { "additionalProperties": false, "properties": { "company": { "$ref": "#/components/schemas/CompanyCompact", "description": "Linked company record" }, "id": { "description": "Unique identifier", "type": "string" }, "name": { "description": "Sponsor name", "type": "string" } }, "required": [ "id", "name" ], "type": "object" }, "SponsorPodcastEntry": { "additionalProperties": false, "properties": { "ad_count": { "description": "Total ads on this podcast from this sponsor", "format": "int64", "type": "integer" }, "episode_count": { "description": "Distinct episodes on this podcast featuring the sponsor", "format": "int64", "type": "integer" }, "last_seen_at": { "description": "Publication time of the sponsor's most recent ad on this podcast", "format": "date-time", "type": "string" }, "podcast": { "$ref": "#/components/schemas/PodcastCompact", "description": "Podcast where the sponsor appears" } }, "required": [ "podcast", "episode_count", "ad_count" ], "type": "object" }, "SponsorPublisherEntry": { "additionalProperties": false, "properties": { "ad_count": { "description": "Ads from this sponsor on the publisher's catalog", "format": "int64", "type": "integer" }, "coverage_share": { "description": "podcast_coverage / publisher.total_podcasts (0..1). A sponsor with coverage_share \u003e= 0.25 on a publisher is doing a network buy across the catalog.", "format": "double", "type": "number" }, "episode_reach": { "description": "Distinct episodes featuring the sponsor on the publisher's catalog", "format": "int64", "type": "integer" }, "first_seen_at": { "description": "Earliest detected ad appearance", "format": "date-time", "type": "string" }, "last_seen_at": { "description": "Most recent ad appearance", "format": "date-time", "type": "string" }, "podcast_coverage": { "description": "Distinct podcasts in the publisher where the sponsor appears", "format": "int64", "type": "integer" }, "publisher": { "$ref": "#/components/schemas/PodcastPublisherCompact", "description": "Publisher reference" }, "publisher_podcast_count": { "description": "Total podcasts in the publisher's catalog", "format": "int64", "type": "integer" } }, "required": [ "publisher", "publisher_podcast_count", "ad_count", "podcast_coverage", "coverage_share", "episode_reach" ], "type": "object" }, "SponsorTrend": { "additionalProperties": false, "properties": { "ad_count_delta": { "description": "recent_ad_count minus previous_ad_count — the ranking signal", "format": "int64", "type": "integer" }, "last_ad_at": { "description": "Publication time of the sponsor's most recent in-window ad", "format": "date-time", "type": "string" }, "previous_ad_count": { "description": "Ads aired inside the equal-length window immediately before the trailing window", "format": "int64", "type": "integer" }, "recent_ad_count": { "description": "Ads aired inside the trailing window", "format": "int64", "type": "integer" }, "sponsor": { "$ref": "#/components/schemas/Sponsor", "description": "Sponsor with activity metrics scoped to the trailing window" } }, "required": [ "sponsor", "recent_ad_count", "previous_ad_count", "ad_count_delta" ], "type": "object" }, "StreamEpisodesPostRequestBody": { "additionalProperties": false, "properties": { "podcast_ids": { "description": "Filter to a set of podcasts by slug or ID. An episode is delivered if its podcast matches any of them. Unknown values are ignored; if none match you receive a terminal error rather than the full firehose.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "popularity_threshold": { "description": "Filter to podcasts whose popularity percentile is at least this value, in (0,1). Omit (or 0) for no popularity filter. Popularity is normalized 0–1 across the catalog, so 0.9 ≈ the top 10%. Combines with podcast_ids as a union.", "exclusiveMaximum": 1, "format": "double", "minimum": 0, "type": "number" } }, "type": "object" }, "StreamError": { "additionalProperties": false, "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object" }, "TopPublisherSponsor": { "additionalProperties": false, "properties": { "ad_count": { "description": "Total number of ads across the publisher's catalog", "format": "int64", "type": "integer" }, "company_id": { "description": "Linked company identifier (domain, slug, or encoded ID)", "type": "string" }, "episode_count": { "description": "Distinct episodes featuring this sponsor", "format": "int64", "type": "integer" }, "podcast_coverage": { "description": "Distinct podcasts in the publisher where this sponsor appears", "format": "int64", "type": "integer" }, "slug": { "description": "Stable human-readable handle (the linked knowledge-graph slug, e.g. 'nvidia'), when known. Prefer it (or company_id) as a /v1/companies key.", "type": "string" }, "sponsor_name": { "description": "Sponsor name", "type": "string" } }, "required": [ "sponsor_name", "ad_count", "podcast_coverage", "episode_count" ], "type": "object" }, "TopSponsorEntry": { "additionalProperties": false, "properties": { "ad_count": { "description": "Total number of ads", "format": "int64", "type": "integer" }, "company_id": { "description": "Linked company identifier (domain, slug, or encoded ID)", "type": "string" }, "episode_count": { "description": "Number of episodes with ads from this sponsor", "format": "int64", "type": "integer" }, "slug": { "description": "Stable human-readable handle (the linked knowledge-graph slug, e.g. 'nvidia'), when known. Prefer it (or company_id) as a /v1/companies key.", "type": "string" }, "sponsor_id": { "description": "Linked sponsor ID, when known. Works as the {id} of /v1/podcasts/advertising/sponsors/{id} and its sub-resources, including when the sponsor has no linked company.", "type": "string" }, "sponsor_name": { "description": "Sponsor name", "type": "string" } }, "required": [ "sponsor_name", "ad_count", "episode_count" ], "type": "object" }, "Topic": { "additionalProperties": false, "properties": { "ancestry": { "description": "Human-readable breadcrumb path (e.g. Business \u003e Technology \u003e AI)", "type": "string" }, "ancestry_path": { "description": "Hash-based ancestry path for programmatic filtering", "type": "string" }, "episode_count": { "description": "Number of episodes in this podcast that cover this topic (only populated for /v1/podcasts/{id} topic lists)", "format": "int64", "type": "integer" }, "id": { "description": "Unique identifier", "type": "string" }, "name": { "description": "Topic name", "type": "string" }, "slug": { "description": "Ancestry-based slug (e.g., technology/artificial-intelligence). Can be used as topic_id.", "type": "string" } }, "required": [ "id", "name", "slug" ], "type": "object" }, "TopicDetail": { "additionalProperties": false, "properties": { "ancestors": { "description": "Ancestor topic names from root to parent", "items": { "type": "string" }, "type": [ "array", "null" ] }, "ancestry": { "description": "Human-readable breadcrumb path (e.g. Business \u003e Technology \u003e AI)", "type": "string" }, "ancestry_path": { "description": "Hash-based ancestry path for programmatic filtering", "type": "string" }, "children": { "description": "Direct child topics, capped — may be truncated. Paginate via /v1/topics?parent_id={id} to enumerate all.", "items": { "$ref": "#/components/schemas/Topic" }, "type": [ "array", "null" ] }, "episode_count": { "description": "Number of episodes in this podcast that cover this topic (only populated for /v1/podcasts/{id} topic lists)", "format": "int64", "type": "integer" }, "id": { "description": "Unique identifier", "type": "string" }, "name": { "description": "Topic name", "type": "string" }, "slug": { "description": "Ancestry-based slug (e.g., technology/artificial-intelligence). Can be used as topic_id.", "type": "string" }, "total_children": { "description": "Total number of direct child topics. May exceed len(children) when truncated; 0 for leaf topics.", "format": "int64", "type": "integer" } }, "required": [ "total_children", "id", "name", "slug" ], "type": "object" }, "TranscriptLine": { "additionalProperties": false, "properties": { "end_seconds": { "description": "End time in seconds (episode-absolute)", "format": "double", "type": "number" }, "is_match": { "description": "Top-scored line within the window for the current query, on /v1/podcasts/episodes/search results. Not set on /v1/podcasts/mentions.", "type": "boolean" }, "is_mention": { "description": "Line contains a textual mention of the resolved entity. Set on /v1/podcasts/mentions only — /v1/podcasts/episodes/search treats entity_id as a filter and does not mark mention lines.", "type": "boolean" }, "matched_terms": { "description": "Terms from the query that occur in this line, longest-first, for clients to highlight. Locate them case-insensitively: each term is spelled as the query spelled it, which may differ in case from the line's text (query \"openai\" is reported for a line reading \"OpenAI\"). Whole-token matches only — a term never matches inside a longer word, so \"AI\" is not reported for \"said\". A multi-word query yields the whole phrase (\"founder mode\") when it occurs contiguously, so clients mark it as one span rather than highlighting each word separately; individual words appear only where they occur outside the phrase. Only the longest term is reported at any position, so terms never overlap. On /v1/podcasts/episodes/search this is set on any line in the window containing the query, not only is_match lines; on /v1/podcasts/mentions it is set only on is_mention lines. Absent when nothing matched or the query was not text-based.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "number": { "description": "Line number within the episode (1-indexed)", "format": "int64", "type": "integer" }, "role": { "description": "Speaker role (HOST, GUEST, etc.)", "type": "string" }, "segment_id": { "description": "The segment containing this line. Set on is_mention lines of /v1/podcasts/mentions, so a mention can be cited by segment even when its window opened in the previous one (a window starts context_lines before its first mention, and the window's segment is where the window starts). Absent elsewhere.", "type": "string" }, "speaker": { "description": "Speaker name or label", "type": "string" }, "start_seconds": { "description": "Start time in seconds (episode-absolute)", "format": "double", "type": "number" }, "text": { "description": "Spoken text", "type": "string" } }, "required": [ "number", "speaker", "start_seconds", "end_seconds", "text" ], "type": "object" }, "TranscriptStatusCount": { "additionalProperties": false, "properties": { "count": { "description": "Discovered episodes with this status.", "format": "int64", "type": "integer" }, "transcript_status": { "description": "The status counted; see Episode.transcript_status.", "enum": [ "transcribed", "processing", "queued", "requestable", "unavailable" ], "type": "string" } }, "required": [ "transcript_status", "count" ], "type": "object" }, "TranscriptWindow": { "additionalProperties": false, "properties": { "end_seconds": { "description": "Window end time in seconds (episode-absolute)", "format": "double", "type": "number" }, "is_preview": { "description": "True when the window is the segment's leading lines (a fallback for when line-level scoring couldn't pinpoint any line) rather than scored matches. False or absent on a scored window.", "type": "boolean" }, "lines": { "description": "Dialogue lines in this window", "items": { "$ref": "#/components/schemas/TranscriptLine" }, "type": [ "array", "null" ] }, "start_seconds": { "description": "Window start time in seconds (episode-absolute)", "format": "double", "type": "number" } }, "required": [ "start_seconds", "end_seconds", "lines" ], "type": "object" }, "TranscriptWord": { "additionalProperties": false, "properties": { "end_seconds": { "description": "End time in seconds", "format": "double", "type": "number" }, "speaker": { "description": "Speaker name or ID", "type": "string" }, "start_seconds": { "description": "Start time in seconds", "format": "double", "type": "number" }, "text": { "description": "Word text", "type": "string" }, "type": { "description": "Token type: word, spacing, audio_event", "type": "string" } }, "required": [ "text", "start_seconds", "end_seconds" ], "type": "object" }, "TreatmentBreakdown": { "additionalProperties": false, "properties": { "glamorizing": { "format": "int64", "type": "integer" }, "promotional": { "format": "int64", "type": "integer" } }, "required": [ "promotional", "glamorizing" ], "type": "object" }, "UpdateAlertBody": { "additionalProperties": false, "properties": { "delivery_cadence": { "enum": [ "REALTIME", "DAILY", "WEEKLY" ], "type": "string" }, "description": { "maxLength": 2000, "type": "string" }, "entities": { "description": "Replacement watch target for ENTITY_MENTION and PODCAST_SPEAKER alerts — exactly one entity. Alerts created before the one-entity rule keep their multi-entity watch list until this field is next written. Rejected on KEYWORD_MENTION alerts.", "items": { "$ref": "#/components/schemas/AlertEntity" }, "maxItems": 1, "minItems": 1, "type": "array" }, "filters": { "$ref": "#/components/schemas/AlertFilters", "description": "Replace the alert's filter set wholesale. Omit to leave the existing filters unchanged; send an empty object {} to clear all filters." }, "is_active": { "description": "Toggle whether the alert produces matches. False pauses; true resumes.", "type": "boolean" }, "keyword": { "description": "Replacement phrase for KEYWORD_MENTION alerts. Rejected on other kinds, and when too broad (see create). Matches already recorded keep the phrase they fired on.", "maxLength": 100, "type": "string" }, "notifications": { "items": { "$ref": "#/components/schemas/AlertNotificationChannel" }, "maxItems": 20, "minItems": 1, "type": "array" }, "title": { "maxLength": 200, "minLength": 1, "type": "string" } }, "type": "object" }, "WebhookConnectionCreated": { "additionalProperties": false, "properties": { "created_at": { "format": "date-time", "type": "string" }, "created_by": { "$ref": "#/components/schemas/Creator", "description": "User who created the connection. Null when created via an API key." }, "id": { "type": "string" }, "name": { "description": "Optional human label for the connection.", "type": "string" }, "project_id": { "type": "string" }, "revoked_at": { "description": "Set when the connection was deleted/revoked; absent for active connections. A revoked connection stops delivering and is skipped by alerts that still reference it.", "format": "date-time", "type": "string" }, "secret": { "description": "Signing secret — shown only at create/rotate time. Store it securely; it cannot be retrieved again. Used to verify the X-Webhook-Signature header on delivered payloads.", "type": "string" }, "secret_prefix": { "description": "Masked signing-secret prefix for identification. The full secret is shown only at create/rotate time and cannot be retrieved afterward.", "type": "string" }, "surface": { "description": "Which Particle surface created this connection. Fixed at create time and inferred from the caller's authenticated surface context. Provenance only — an alert on either surface can deliver through it. Render it to show where the endpoint was registered.", "enum": [ "PLATFORM", "RADAR" ], "type": "string" }, "url": { "description": "Destination URL that signed POSTs are delivered to.", "type": "string" } }, "required": [ "secret", "id", "project_id", "surface", "url", "secret_prefix", "created_at" ], "type": "object" }, "WindowCount": { "additionalProperties": false, "properties": { "count": { "description": "Number of items within the window.", "format": "int64", "type": "integer" }, "window": { "description": "Trailing time window the count covers.", "enum": [ "24h", "7d" ], "type": "string" } }, "required": [ "window", "count" ], "type": "object" }, "WordTranscriptResponse": { "additionalProperties": false, "properties": { "cursor": { "description": "Pass to next request for more results", "type": "string" }, "episode_id": { "description": "Parent episode ID", "type": "string" }, "has_more": { "description": "Whether more words exist beyond this page", "type": "boolean" }, "language": { "description": "Transcript language code", "type": "string" }, "words": { "description": "Word-level timestamped transcript", "items": { "$ref": "#/components/schemas/TranscriptWord" }, "type": [ "array", "null" ] } }, "required": [ "episode_id", "words", "has_more" ], "type": "object" }, "YearCoverage": { "additionalProperties": false, "properties": { "discovered": { "description": "Episodes published that year that we know of.", "format": "int64", "type": "integer" }, "transcribed": { "description": "Of those, episodes with a transcript.", "format": "int64", "type": "integer" }, "year": { "description": "Publication year (UTC).", "format": "int64", "type": "integer" } }, "required": [ "year", "discovered", "transcribed" ], "type": "object" } }, "securitySchemes": { "ApiKeyHeader": { "description": "Pass your API key in the X-API-Key header (recommended).", "in": "header", "name": "X-API-Key", "type": "apiKey" }, "BearerAuth": { "description": "Pass your API key as a Bearer token in the Authorization header.", "scheme": "bearer", "type": "http" }, "MPP": { "description": "MPP EVM charge. Read WWW-Authenticate: Payment on a 402, sign the USDC authorization, and retry with Authorization: Payment. An API key is not required.", "scheme": "Payment", "type": "http" } } }, "externalDocs": { "url": "https://docs.particle.pro" }, "info": { "contact": { "email": "api@particle.pro", "name": "Particle", "url": "https://particle.pro" }, "description": "Podcast API for transcripts, mentions and sponsorship data. 140,000+ podcasts transcribed, diarized and speaker-identified within minutes of airing, about 28,000 episodes a day. Search transcripts by keyword or meaning, track brand and company mentions with alerts, pull sponsor and ad-read data and rankings. REST API plus an MCP server for AI agents. Also company, people and topic intelligence.", "summary": "Podcast API: transcripts, mentions, sponsors and rankings for 140,000+ podcasts.", "termsOfService": "https://particle.pro/legal/tos-api", "title": "Particle API", "version": "0.1.0", "x-guidance": "Podcast, people, company and topic intelligence. Authenticate with a pp_ API key (X-API-Key header) or pay per request with x402: a keyless call to a billable endpoint returns 402 with the payment requirements in the PAYMENT-REQUIRED header; sign the USDC transfer and repeat the request with PAYMENT-SIGNATURE. Start with GET /v1/podcasts/search?q=\u003cshow name\u003e; the slugs in responses are the inputs to the other endpoints. Docs: https://docs.particle.pro; setup playbook: https://api.particle.pro/agents.md; endpoint and tool map with prices: https://api.particle.pro/llms.txt; credential recipe: https://api.particle.pro/auth.md.", "x-logo": { "url": "https://particle.pro/favicon.svg" } }, "openapi": "3.1.0", "paths": { "/v1/alerts/deliveries/{id}": { "get": { "description": "Returns one delivery with its embedded matches (paginated — see matches_cursor). The URL is keyed only by the delivery ID — the parent alert ID is intentionally omitted so a landing-page link can be shared publicly without leaking the alert identifier. Works for all cadences — immediate, daily, weekly digests. URL possession is the access factor; the endpoint is reachable without auth (the IDs are unguessable). Authenticated members of the delivery's owning organization receive the high-resolution payload (transcript Windows when `view=detailed`, mention variants, salience, delivery audit). For a member-viewed WEBHOOK delivery, has_webhook_payload is true and the exact POSTed JSON is available from GET /v1/alerts/deliveries/{id}/webhook-payload (not embedded here — it can be many MB). Unauthenticated and non-member callers receive a reduced public payload — alert title and kind, match entity and episode metadata, no internal fields.", "operationId": "get-alert-delivery", "parameters": [ { "description": "Delivery ID", "in": "path", "name": "id", "required": true, "schema": { "description": "Delivery ID", "type": "string" } }, { "description": "Hydration depth for the embedded matches. Both views include Episode metadata (episode title, podcast title, image) so the FE can render a card per match. 'summary' (default) omits transcript Windows; 'detailed' includes them — pick 'detailed' when rendering a full landing page where each match expands to the spoken excerpt, 'summary' for a list view.", "explode": false, "in": "query", "name": "view", "schema": { "default": "summary", "description": "Hydration depth for the embedded matches. Both views include Episode metadata (episode title, podcast title, image) so the FE can render a card per match. 'summary' (default) omits transcript Windows; 'detailed' includes them — pick 'detailed' when rendering a full landing page where each match expands to the spoken excerpt, 'summary' for a list view.", "enum": [ "summary", "detailed" ], "type": "string" } }, { "description": "Max embedded matches to return in this response (default and max 100). The delivery's true total is always match_count; use matches_cursor to page through the rest.", "explode": false, "in": "query", "name": "matches_limit", "schema": { "default": 100, "description": "Max embedded matches to return in this response (default and max 100). The delivery's true total is always match_count; use matches_cursor to page through the rest.", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque cursor from a previous response's matches_cursor, to fetch the next page of embedded matches.", "explode": false, "in": "query", "name": "matches_cursor", "schema": { "description": "Opaque cursor from a previous response's matches_cursor, to fetch the next page of embedded matches.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertDeliveryDetail" } } }, "description": "OK" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [], "summary": "Get a single alert delivery", "tags": [ "Alerts", "tier:free" ], "x-cost-weight": 0, "x-tier": "free" } }, "/v1/alerts/deliveries/{id}/webhook-payload": { "get": { "description": "Returns the exact JSON body POSTed to the webhook endpoint for a WEBHOOK-channel delivery, reconstructed on demand (never stored) so it matches the delivered bytes. Member-only — the payload carries every match's full content, so unlike the delivery view (which URL possession alone can read), this requires membership of the owning organization. Returns 404 for a non-webhook delivery and 403 for a non-member. Split from the delivery view because for a large digest this reconstructs to many MB; fetch it on demand only when has_webhook_payload is true.", "operationId": "get-alert-delivery-webhook-payload", "parameters": [ { "description": "Delivery ID", "in": "path", "name": "id", "required": true, "schema": { "description": "Delivery ID", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "OK" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [], "summary": "Get the exact JSON a webhook delivery POSTed", "tags": [ "Alerts", "tier:free" ], "x-cost-weight": 0, "x-tier": "free" } }, "/v1/alerts/disable": { "get": { "description": "Returns the alert's current title, kind, cadence, and is_active state for a given disable token without redeeming it. Public — token possession is the auth factor.", "operationId": "preview-alert-disable", "parameters": [ { "description": "Disable-alert token from the footer of an alert email.", "explode": false, "in": "query", "name": "token", "required": true, "schema": { "description": "Disable-alert token from the footer of an alert email.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisableAlertResponseBody" } } }, "description": "OK" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [], "summary": "Preview alert disable action", "tags": [ "Alerts", "tier:free" ], "x-cost-weight": 0, "x-tier": "free" }, "post": { "description": "Redeems a single-use token from the footer of an alert email and flips the alert's is_active flag to false. Idempotent: a replay returns 200 with already_disabled=true. Public — token possession is the auth factor.", "operationId": "disable-alert", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisableAlertBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisableAlertResponseBody" } } }, "description": "OK" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [], "summary": "Disable an alert via email-footer token", "tags": [ "Alerts", "tier:free" ], "x-cost-weight": 0, "x-tier": "free" } }, "/v1/alerts/matches/{id}": { "get": { "description": "Returns one match with full hydration — transcript Windows, source-episode metadata, and the deliveries that included this match. The URL is keyed only by the match ID so a result link can be shared publicly without leaking the alert identifier. Use this for per-match landing pages opened from a digest or results list. URL possession is the access factor; authenticated org members see the full payload while unauthenticated and non-member callers see a reduced public payload (entity + episode, no transcript dialogue). Single-match only: digests (daily/weekly) embed many matches and should be fetched via GET /v1/alerts/deliveries/{id}?view=detailed.", "operationId": "get-alert-match", "parameters": [ { "description": "Match ID", "in": "path", "name": "id", "required": true, "schema": { "description": "Match ID", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertMatch" } } }, "description": "OK" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [], "summary": "Get a single alert match", "tags": [ "Alerts", "tier:free" ], "x-cost-weight": 0, "x-tier": "free" } }, "/v1/alerts/preview/{previewId}": { "get": { "description": "Returns the current state of an async preview sweep. Status transitions in_progress → completed (or failed). Previews are retained for 1 hour; expired IDs return 404.", "operationId": "get-alert-preview", "parameters": [ { "description": "Opaque preview ID returned by POST /v1/projects/{projectId}/alerts/preview.", "in": "path", "name": "previewId", "required": true, "schema": { "description": "Opaque preview ID returned by POST /v1/projects/{projectId}/alerts/preview.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetAlertPreviewResponseBody" } } }, "description": "OK" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "summary": "Get the status and result of an alert preview", "tags": [ "Alerts", "tier:standard" ], "x-cost-weight": 1, "x-entitlement-priced": true, "x-tier": "standard" } }, "/v1/alerts/{id}": { "delete": { "description": "Soft-delete an alert. Existing matches and deliveries are retained for audit but no further matches will be produced. Only the alert's creator or an organization OWNER or ADMIN can delete it; an API key acts as the user who created the key. Any other caller receives 403.", "operationId": "delete-alert", "parameters": [ { "description": "Alert ID", "in": "path", "name": "id", "required": true, "schema": { "description": "Alert ID", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteAlertResponseBody" } } }, "description": "OK" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "summary": "Delete an alert", "tags": [ "Alerts", "tier:standard" ], "x-cost-weight": 1, "x-entitlement-priced": true, "x-tier": "standard" }, "get": { "description": "Returns a single alert by ID.", "operationId": "get-alert", "parameters": [ { "description": "Alert ID", "in": "path", "name": "id", "required": true, "schema": { "description": "Alert ID", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Alert" } } }, "description": "OK" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "summary": "Get an alert", "tags": [ "Alerts", "tier:standard" ], "x-cost-weight": 1, "x-entitlement-priced": true, "x-tier": "standard" }, "patch": { "description": "Partially update an alert. Provided fields replace existing values; the entities list, when provided, replaces the watched entity (exactly one). Alerts are not covered by zero data retention: the alert's definition and its matched results are stored as part of the alerts feature.", "operationId": "update-alert", "parameters": [ { "description": "Alert ID", "in": "path", "name": "id", "required": true, "schema": { "description": "Alert ID", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAlertBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Alert" } } }, "description": "OK" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "summary": "Update an alert", "tags": [ "Alerts", "tier:standard" ], "x-cost-weight": 1, "x-entitlement-priced": true, "x-tier": "standard" } }, "/v1/alerts/{id}/deliveries": { "get": { "description": "Returns the email delivery audit log for the given alert.", "operationId": "list-alert-deliveries", "parameters": [ { "description": "Results per page", "explode": false, "in": "query", "name": "limit", "schema": { "default": 25, "description": "Results per page", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque pagination cursor from previous response", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque pagination cursor from previous response", "type": "string" } }, { "description": "Alert ID", "in": "path", "name": "id", "required": true, "schema": { "description": "Alert ID", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageAlertDelivery" } } }, "description": "OK" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "summary": "List deliveries for an alert", "tags": [ "Alerts", "tier:standard" ], "x-cost-weight": 1, "x-entitlement-priced": true, "x-tier": "standard" } }, "/v1/alerts/{id}/matches": { "get": { "description": "Returns the matches detected for the given alert, newest first.", "operationId": "list-alert-matches", "parameters": [ { "description": "Results per page", "explode": false, "in": "query", "name": "limit", "schema": { "default": 25, "description": "Results per page", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque pagination cursor from previous response", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque pagination cursor from previous response", "type": "string" } }, { "description": "Alert ID", "in": "path", "name": "id", "required": true, "schema": { "description": "Alert ID", "type": "string" } }, { "description": "Only matches detected after this date.", "explode": false, "in": "query", "name": "after", "schema": { "description": "Only matches detected after this date.", "examples": [ "2026-05-01" ], "type": "string" } }, { "description": "Only matches detected before this date.", "explode": false, "in": "query", "name": "before", "schema": { "description": "Only matches detected before this date.", "examples": [ "2026-05-09" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageAlertMatch" } } }, "description": "OK" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "summary": "List matches for an alert", "tags": [ "Alerts", "tier:standard" ], "x-cost-weight": 1, "x-entitlement-priced": true, "x-tier": "standard" } }, "/v1/alerts/{id}/test-webhook": { "post": { "description": "Sends a synthetic `alert.match.created` payload to every active webhook connection attached to this alert, so you can verify your endpoint end to end — receipt, signature, and parsing — without waiting for a real match. The payload is byte-for-byte shaped like a live delivery and carries this alert's real id, title, kind, and first watched entity, but its match content is illustrative sample data and the envelope is flagged `test: true` so your handler can skip real side effects. Nothing is persisted — a test never appears in the alert's delivery log. Returns one result per connection the test was POSTed to: whether the endpoint accepted the POST, its status code, and any error. Channels whose connection has been deleted are skipped and don't appear in the results. A down or non-2xx endpoint is reported as `delivered: false` rather than failing the request. Returns 422 when the alert has no active webhook connection — either none is configured, or every configured connection has been deleted.", "operationId": "send-alert-test-webhook", "parameters": [ { "description": "Alert ID", "in": "path", "name": "id", "required": true, "schema": { "description": "Alert ID", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlertTestWebhookResult" } } }, "description": "OK" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "summary": "Send a test webhook", "tags": [ "Alerts", "tier:standard" ], "x-cost-weight": 1, "x-entitlement-priced": true, "x-tier": "standard" } }, "/v1/companies": { "get": { "description": "Returns a paginated list of companies. Filter by entity slug (e.g., 'apple'), ticker, domain, CIK, or QID. Search by name or fetch updates since a timestamp.", "operationId": "list-companies", "parameters": [ { "description": "Results per page", "explode": false, "in": "query", "name": "limit", "schema": { "default": 25, "description": "Results per page", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque pagination cursor from previous response", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque pagination cursor from previous response", "type": "string" } }, { "description": "Search by name (case-insensitive partial match)", "explode": false, "in": "query", "name": "q", "schema": { "description": "Search by name (case-insensitive partial match)", "examples": [ "Apple" ], "maxLength": 200, "type": "string" } }, { "description": "Only items updated after this ISO 8601 date or date-time (e.g. 2024-01-01 or 2024-01-01T00:00:00Z). Useful for incremental syncing.", "explode": false, "in": "query", "name": "updated_after", "schema": { "description": "Only items updated after this ISO 8601 date or date-time (e.g. 2024-01-01 or 2024-01-01T00:00:00Z). Useful for incremental syncing.", "examples": [ "2024-01-01T00:00:00Z" ], "type": "string" } }, { "description": "Bulk multi-get: one or more company slugs (e.g. 'apple'), domains (e.g. 'apple.com'), or IDs, comma-separated (max 100) — the same identifiers GET /v1/companies/{id} accepts. When set, returns exactly those companies and the other filters/search and pagination are ignored. Refs that don't resolve are omitted from the response.", "explode": false, "in": "query", "name": "ids", "schema": { "description": "Bulk multi-get: one or more company slugs (e.g. 'apple'), domains (e.g. 'apple.com'), or IDs, comma-separated (max 100) — the same identifiers GET /v1/companies/{id} accepts. When set, returns exactly those companies and the other filters/search and pagination are ignored. Refs that don't resolve are omitted from the response.", "examples": [ [ "apple", "tesla.com", "nvidia" ] ], "items": { "type": "string" }, "maxItems": 100, "type": [ "array", "null" ] } }, { "description": "Filter by stock ticker symbol(s), comma-separated", "explode": false, "in": "query", "name": "ticker", "schema": { "description": "Filter by stock ticker symbol(s), comma-separated", "examples": [ [ "AAPL", "GOOG" ] ], "items": { "type": "string" }, "maxItems": 100, "type": [ "array", "null" ] } }, { "description": "Filter by company domain(s), comma-separated", "explode": false, "in": "query", "name": "domain", "schema": { "description": "Filter by company domain(s), comma-separated", "examples": [ [ "apple.com" ] ], "items": { "type": "string" }, "maxItems": 100, "type": [ "array", "null" ] } }, { "description": "Filter by SEC CIK(s), comma-separated", "explode": false, "in": "query", "name": "cik", "schema": { "description": "Filter by SEC CIK(s), comma-separated", "examples": [ [ "0000320193" ] ], "items": { "type": "string" }, "maxItems": 100, "type": [ "array", "null" ] } }, { "description": "Filter by Wikidata QID(s), comma-separated", "explode": false, "in": "query", "name": "qid", "schema": { "description": "Filter by Wikidata QID(s), comma-separated", "examples": [ [ "Q312" ] ], "items": { "type": "string" }, "maxItems": 100, "type": [ "array", "null" ] } }, { "description": "Entity slug(s) (e.g., 'apple', 'nvidia') or ID(s), comma-separated", "explode": false, "in": "query", "name": "entity_id", "schema": { "description": "Entity slug(s) (e.g., 'apple', 'nvidia') or ID(s), comma-separated", "items": { "type": "string" }, "maxItems": 100, "type": [ "array", "null" ] } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageCompany" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.01 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "List companies", "tags": [ "Companies", "tier:standard" ], "x-cost-weight": 1, "x-payment-info": { "offers": [ { "amount": "10000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.010000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "standard" } }, "/v1/companies/{id}": { "get": { "description": "Returns a single company by slug (e.g., 'apple'), domain (e.g., 'apple.com'), or ID.", "operationId": "get-company", "parameters": [ { "description": "Company slug (e.g., 'apple', 'tesla'), domain (e.g., 'apple.com'), or ID", "in": "path", "name": "id", "required": true, "schema": { "description": "Company slug (e.g., 'apple', 'tesla'), domain (e.g., 'apple.com'), or ID", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Company" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.01 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "Get a company", "tags": [ "Companies", "tier:standard" ], "x-cost-weight": 1, "x-payment-info": { "offers": [ { "amount": "10000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.010000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "standard" } }, "/v1/companies/{id}/competitors": { "get": { "description": "Returns a paginated list of competitors for a company, ordered by prominence (news coverage volume, market cap, podcast appearances, Wikidata notability) so the largest / most-newsworthy competitors come first. Each result includes a competitive basis describing the relationship. Identify the company by slug (e.g., 'apple'), domain, or ID.", "operationId": "list-company-competitors", "parameters": [ { "description": "Results per page", "explode": false, "in": "query", "name": "limit", "schema": { "default": 25, "description": "Results per page", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque pagination cursor from previous response", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque pagination cursor from previous response", "type": "string" } }, { "description": "Company slug (e.g., 'apple'), domain (e.g., 'apple.com'), or ID", "in": "path", "name": "id", "required": true, "schema": { "description": "Company slug (e.g., 'apple'), domain (e.g., 'apple.com'), or ID", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageCompetitor" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.03 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "List company competitors", "tags": [ "Companies", "tier:premium" ], "x-cost-weight": 1, "x-payment-info": { "offers": [ { "amount": "30000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.030000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "premium" } }, "/v1/companies/{id}/external-links": { "get": { "description": "Returns every known third-party profile and identifier for the company — LinkedIn, social accounts, its registrable domain, Wikidata QID, SEC CIK, and stock tickers — as one list. Identify the company by slug (e.g., 'apple'), domain, or ID. Pair it with GET /v1/entities/lookup, which resolves any of these identifiers back to the company.", "operationId": "list-company-external-links", "parameters": [ { "description": "Results per page (default: all)", "explode": false, "in": "query", "name": "limit", "schema": { "description": "Results per page (default: all)", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque pagination cursor from previous response", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque pagination cursor from previous response", "type": "string" } }, { "description": "Company slug (e.g., 'apple'), domain (e.g., 'apple.com'), or ID", "in": "path", "name": "id", "required": true, "schema": { "description": "Company slug (e.g., 'apple'), domain (e.g., 'apple.com'), or ID", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageExternalLink" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.04 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "List a company's external profiles", "tags": [ "Companies", "tier:standard" ], "x-cost-weight": 1, "x-payment-info": { "offers": [ { "amount": "40000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.040000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "standard" } }, "/v1/companies/{id}/people": { "get": { "description": "Returns a paginated list of people associated with a company (executives and other known roles), current roles first and most-recently-joined first. Each person carries the full Person payload — bio, role history, external profile links, and knowledge-graph cross-reference. Set current_only=false to include historical roles, or filter by role title. Identify the company by slug (e.g., 'apple'), domain, or ID.", "operationId": "list-company-people", "parameters": [ { "description": "Results per page", "explode": false, "in": "query", "name": "limit", "schema": { "default": 25, "description": "Results per page", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque pagination cursor from previous response", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque pagination cursor from previous response", "type": "string" } }, { "description": "Company slug (e.g., 'apple'), domain (e.g., 'apple.com'), or ID", "in": "path", "name": "id", "required": true, "schema": { "description": "Company slug (e.g., 'apple'), domain (e.g., 'apple.com'), or ID", "type": "string" } }, { "description": "When true (default), only people currently in a role at the company. Set false to include historical roles.", "explode": false, "in": "query", "name": "current_only", "schema": { "default": true, "description": "When true (default), only people currently in a role at the company. Set false to include historical roles.", "type": "boolean" } }, { "description": "Case-insensitive substring filter on role title (e.g. 'chief', 'founder').", "explode": false, "in": "query", "name": "title", "schema": { "description": "Case-insensitive substring filter on role title (e.g. 'chief', 'founder').", "examples": [ "chief" ], "type": "string" } }, { "description": "Only people whose role title falls in this contact role class: current roles by default, historical roles too when current_only=false. The classes are the ones a podcast pitching sponsorship would reach (marketing, partnerships, brand, media and advertising, communications, growth, executive); other is a title that matches none of them. Combines with title.", "explode": false, "in": "query", "name": "role", "schema": { "description": "Only people whose role title falls in this contact role class: current roles by default, historical roles too when current_only=false. The classes are the ones a podcast pitching sponsorship would reach (marketing, partnerships, brand, media and advertising, communications, growth, executive); other is a title that matches none of them. Combines with title.", "enum": [ "marketing", "brand", "partnerships", "media_advertising", "communications", "growth", "executive", "other" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagePerson" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.03 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "List company people", "tags": [ "Companies", "tier:standard" ], "x-cost-weight": 1, "x-payment-info": { "offers": [ { "amount": "30000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.030000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "standard" } }, "/v1/companies/{id}/podcast/advertising": { "get": { "description": "Returns advertising intelligence for a specific company across the podcast ecosystem, including reach metrics and recent ad placements. Identify the company by slug (e.g., 'apple'), domain, or ID.", "operationId": "get-company-podcast-advertising", "parameters": [ { "description": "Company slug (e.g., 'apple'), domain (e.g., 'apple.com'), or ID", "in": "path", "name": "id", "required": true, "schema": { "description": "Company slug (e.g., 'apple'), domain (e.g., 'apple.com'), or ID", "type": "string" } }, { "description": "Only include ads from episodes published on or after this ISO 8601 date or date-time (e.g. 2025-01-01 or 2025-01-01T00:00:00Z)", "explode": false, "in": "query", "name": "since", "schema": { "description": "Only include ads from episodes published on or after this ISO 8601 date or date-time (e.g. 2025-01-01 or 2025-01-01T00:00:00Z)", "examples": [ "2025-01-01T00:00:00Z" ], "type": "string" } }, { "description": "Only include ads from episodes published before this ISO 8601 date or date-time (e.g. 2026-01-01 or 2026-01-01T00:00:00Z)", "explode": false, "in": "query", "name": "until", "schema": { "description": "Only include ads from episodes published before this ISO 8601 date or date-time (e.g. 2026-01-01 or 2026-01-01T00:00:00Z)", "examples": [ "2026-01-01T00:00:00Z" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyAdvertisingProfile" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.03 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "Get company advertising profile", "tags": [ "Companies", "tier:premium" ], "x-cost-weight": 2, "x-payment-info": { "offers": [ { "amount": "30000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.030000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "premium" } }, "/v1/companies/{id}/podcast/advertising/placements": { "get": { "description": "Returns a newest-first, keyset-paginated feed of physical podcast ad placements with a known episode publication time, attributed to a company, with episode and podcast context plus every company-scoped sponsor attribution.", "operationId": "list-company-advertising-placements", "parameters": [ { "description": "Results per page", "explode": false, "in": "query", "name": "limit", "schema": { "default": 25, "description": "Results per page", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque pagination cursor from previous response", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque pagination cursor from previous response", "type": "string" } }, { "description": "Company slug (e.g. 'apple'), domain (e.g. 'apple.com'), or ID", "in": "path", "name": "id", "required": true, "schema": { "description": "Company slug (e.g. 'apple'), domain (e.g. 'apple.com'), or ID", "type": "string" } }, { "description": "Optional sponsor ID. Selects placements attributed to this sponsor while preserving co-sponsors in the response.", "explode": false, "in": "query", "name": "sponsor_id", "schema": { "description": "Optional sponsor ID. Selects placements attributed to this sponsor while preserving co-sponsors in the response.", "type": "string" } }, { "description": "Optional podcast ID, slug, or Apple/iTunes collection ID", "explode": false, "in": "query", "name": "podcast_id", "schema": { "description": "Optional podcast ID, slug, or Apple/iTunes collection ID", "type": "string" } }, { "description": "Only include ads from episodes published on or after this ISO 8601 date or date-time", "explode": false, "in": "query", "name": "since", "schema": { "description": "Only include ads from episodes published on or after this ISO 8601 date or date-time", "examples": [ "2025-01-01T00:00:00Z" ], "type": "string" } }, { "description": "Only include ads before this ISO 8601 date-time. A bare date includes that whole UTC day.", "explode": false, "in": "query", "name": "until", "schema": { "description": "Only include ads before this ISO 8601 date-time. A bare date includes that whole UTC day.", "examples": [ "2026-01-01" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageCompanyAdvertisingPlacement" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.03 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "List company podcast advertising placements", "tags": [ "Companies", "tier:premium" ], "x-cost-weight": 3, "x-payment-info": { "offers": [ { "amount": "30000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.030000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "premium" } }, "/v1/companies/{id}/podcast/advertising/podcasts": { "get": { "description": "Returns podcasts ranked by exact company-linked ad count, with company-wide sponsor filters, per-podcast sponsor breakdowns, recent preview segments, and cursor pagination.", "operationId": "list-company-advertising-podcasts", "parameters": [ { "description": "Company slug (e.g. 'apple'), domain (e.g. 'apple.com'), or ID", "in": "path", "name": "id", "required": true, "schema": { "description": "Company slug (e.g. 'apple'), domain (e.g. 'apple.com'), or ID", "type": "string" } }, { "description": "Results per page", "explode": false, "in": "query", "name": "limit", "schema": { "default": 24, "description": "Results per page", "format": "int64", "maximum": 24, "minimum": 1, "type": "integer" } }, { "description": "Opaque pagination cursor from a previous response", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque pagination cursor from a previous response", "type": "string" } }, { "description": "Optional sponsor ID. Keeps the company constraint while narrowing rows to this sponsor identity.", "explode": false, "in": "query", "name": "sponsor_id", "schema": { "description": "Optional sponsor ID. Keeps the company constraint while narrowing rows to this sponsor identity.", "type": "string" } }, { "description": "Optional podcast ID, slug, or Apple/iTunes collection ID. Filters rich rows without narrowing facets.", "explode": false, "in": "query", "name": "podcast_id", "schema": { "description": "Optional podcast ID, slug, or Apple/iTunes collection ID. Filters rich rows without narrowing facets.", "type": "string" } }, { "description": "Optional publisher ID or slug. Filters rich rows without narrowing facets.", "explode": false, "in": "query", "name": "publisher_id", "schema": { "description": "Optional publisher ID or slug. Filters rich rows without narrowing facets.", "type": "string" } }, { "description": "Include exhaustive lightweight Show and Network filter metadata. Honored only on cursorless requests.", "explode": false, "in": "query", "name": "include_facets", "schema": { "description": "Include exhaustive lightweight Show and Network filter metadata. Honored only on cursorless requests.", "type": "boolean" } }, { "description": "Include company-wide sponsor totals. Disable when loading podcast rows separately from filter metadata; per-podcast sponsors and previews are unchanged.", "explode": false, "in": "query", "name": "include_sponsors", "schema": { "default": true, "description": "Include company-wide sponsor totals. Disable when loading podcast rows separately from filter metadata; per-podcast sponsors and previews are unchanged.", "type": "boolean" } }, { "description": "Include recent ad segment previews per podcast. Disable for count-only consumers to skip preview hydration.", "explode": false, "in": "query", "name": "include_previews", "schema": { "default": true, "description": "Include recent ad segment previews per podcast. Disable for count-only consumers to skip preview hydration.", "type": "boolean" } }, { "description": "Maximum previews per podcast when include_previews is enabled.", "explode": false, "in": "query", "name": "preview_limit", "schema": { "default": 3, "description": "Maximum previews per podcast when include_previews is enabled.", "format": "int64", "maximum": 8, "minimum": 1, "type": "integer" } }, { "description": "Only include ads from episodes published on or after this ISO 8601 date or date-time", "explode": false, "in": "query", "name": "since", "schema": { "description": "Only include ads from episodes published on or after this ISO 8601 date or date-time", "examples": [ "2025-01-01T00:00:00Z" ], "type": "string" } }, { "description": "Only include ads before this ISO 8601 date-time. A bare date includes that whole UTC day.", "explode": false, "in": "query", "name": "until", "schema": { "description": "Only include ads before this ISO 8601 date-time. A bare date includes that whole UTC day.", "examples": [ "2026-01-01" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyAdvertisingPodcastsPage" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.03 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "List podcasts carrying company advertising", "tags": [ "Companies", "tier:premium" ], "x-cost-weight": 3, "x-payment-info": { "offers": [ { "amount": "30000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.030000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "premium" } }, "/v1/companies/{id}/podcast/recommendations": { "get": { "description": "Returns shows the company does NOT advertise on, ranked by how related they are to the shows it DOES — the buy-side prospect list. Each seed show counts by how much the company advertises there, so a list is anchored on its main venues; every show it has ever bought is excluded. Each row carries the podcast, a calibrated score in (0,1), a band (strong / moderate / weak), and with include=via the company's own shows that led there. Companies with no podcast advertising get an empty page.", "operationId": "list-company-podcast-recommendations", "parameters": [ { "description": "Results per page", "explode": false, "in": "query", "name": "limit", "schema": { "default": 25, "description": "Results per page", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque pagination cursor from previous response", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque pagination cursor from previous response", "type": "string" } }, { "description": "Company identifier — slug, domain, or canonical ID", "in": "path", "name": "id", "required": true, "schema": { "description": "Company identifier — slug, domain, or canonical ID", "type": "string" } }, { "description": "Optional response sections. Pass include=via to attach, for each recommendation, the company's own shows that led to it — the venues to cite when explaining why the recommendation fits.", "explode": false, "in": "query", "name": "include", "schema": { "description": "Optional response sections. Pass include=via to attach, for each recommendation, the company's own shows that led to it — the venues to cite when explaining why the recommendation fits.", "items": { "enum": [ "via" ], "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Only recommendations at or above this score, applied within the 200 strongest recommendations the list holds. Omit (or 0) for every recommendation; the band field is the recommended way to filter by strength.", "explode": false, "in": "query", "name": "min_score", "schema": { "description": "Only recommendations at or above this score, applied within the 200 strongest recommendations the list holds. Omit (or 0) for every recommendation; the band field is the recommended way to filter by strength.", "format": "double", "maximum": 1, "minimum": 0, "type": "number" } }, { "description": "Only shows in this language (ISO 639-1 code, e.g. 'en', 'es'; a region suffix such as 'fr-CA' is reduced to the language), applied within the 200 strongest recommendations the list holds.", "explode": false, "in": "query", "name": "language", "schema": { "description": "Only shows in this language (ISO 639-1 code, e.g. 'en', 'es'; a region suffix such as 'fr-CA' is reduced to the language), applied within the 200 strongest recommendations the list holds.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageRecommendedPodcast" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.03 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "List podcasts a company could advertise on next", "tags": [ "Companies", "tier:premium" ], "x-cost-weight": 3, "x-payment-info": { "offers": [ { "amount": "30000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.030000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "premium" } }, "/v1/companies/{id}/products": { "get": { "description": "Returns the product hierarchy for a company as a nested tree. Segments contain product lines, which contain individual products. Identify the company by slug (e.g., 'apple'), domain, or ID. Defaults to active products only.", "operationId": "list-company-products", "parameters": [ { "description": "Company slug (e.g., 'apple'), domain (e.g., 'apple.com'), or ID", "in": "path", "name": "id", "required": true, "schema": { "description": "Company slug (e.g., 'apple'), domain (e.g., 'apple.com'), or ID", "type": "string" } }, { "description": "Filter by lifecycle status (default: active), comma-separated for union.", "explode": false, "in": "query", "name": "status", "schema": { "description": "Filter by lifecycle status (default: active), comma-separated for union.", "examples": [ [ "active" ] ], "items": { "type": "string" }, "type": [ "array", "null" ] } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageCompanyProduct" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.03 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "List company products", "tags": [ "Companies", "tier:standard" ], "x-cost-weight": 1, "x-payment-info": { "offers": [ { "amount": "30000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.030000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "standard" } }, "/v1/embed/clips/{id}": { "get": { "description": "Returns a minimal public representation of a clip for embed rendering.", "operationId": "get-clip-embed", "parameters": [ { "description": "Clip ID", "in": "path", "name": "id", "required": true, "schema": { "description": "Clip ID", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClipEmbed" } } }, "description": "OK", "headers": { "Cache-Control": { "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [], "summary": "Get clip embed", "tags": [ "Embed", "tier:free" ], "x-cost-weight": 0, "x-tier": "free" } }, "/v1/embed/clips/{id}/transcript": { "get": { "description": "Returns the diarized transcript for a clip embed.", "operationId": "get-clip-embed-transcript", "parameters": [ { "description": "Clip ID", "in": "path", "name": "id", "required": true, "schema": { "description": "Clip ID", "type": "string" } }, { "description": "Output format", "explode": false, "in": "query", "name": "format", "schema": { "default": "dialogue", "description": "Output format", "enum": [ "dialogue", "text", "srt", "words" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "OK", "headers": { "Cache-Control": { "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [], "summary": "Get clip embed transcript", "tags": [ "Embed", "tier:free" ], "x-cost-weight": 0, "x-tier": "free" } }, "/v1/embed/episodes/{episode_id}/code": { "get": { "description": "Returns a paste-ready \u003cparticle-podcast-clip\u003e HTML snippet for an existing clip or a custom timestamp range within an episode. Either clip_id or start (with optional end) must be supplied; the two modes are mutually exclusive.\n\nFor slices: when end is omitted, it defaults to start + 120 seconds. The embed widget caps slice length at 120 seconds, so any end value beyond start + 120s is silently clamped to start + 120s. End is also clamped to the episode duration. The actual range used is encoded in the returned script_url.", "operationId": "get-episode-embed-code", "parameters": [ { "description": "Episode slug or ID", "in": "path", "name": "episode_id", "required": true, "schema": { "description": "Episode slug or ID", "type": "string" } }, { "description": "Clip ID. Mutually exclusive with start/end.", "explode": false, "in": "query", "name": "clip_id", "schema": { "description": "Clip ID. Mutually exclusive with start/end.", "type": "string" } }, { "description": "Slice start in seconds. Mutually exclusive with clip_id.", "explode": false, "in": "query", "name": "start", "schema": { "description": "Slice start in seconds. Mutually exclusive with clip_id.", "format": "double", "minimum": 0, "type": "number" } }, { "description": "Slice end in seconds. Optional: when omitted, defaults to start + 120s. The widget caps slices at 120s, so end values further than 120s past start are silently clamped to start + 120s.", "explode": false, "in": "query", "name": "end", "schema": { "description": "Slice end in seconds. Optional: when omitted, defaults to start + 120s. The widget caps slices at 120s, so end values further than 120s past start are silently clamped to start + 120s.", "format": "double", "minimum": 0, "type": "number" } }, { "description": "Widget theme", "explode": false, "in": "query", "name": "theme", "schema": { "default": "light", "description": "Widget theme", "enum": [ "light", "dark", "color-light", "color-dark" ], "type": "string" } }, { "description": "Widget size", "explode": false, "in": "query", "name": "size", "schema": { "default": "regular", "description": "Widget size", "enum": [ "regular", "compact" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EpisodeEmbedCode" } } }, "description": "OK", "headers": { "Cache-Control": { "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [], "summary": "Get episode embed code", "tags": [ "Embed", "tier:free" ], "x-cost-weight": 0, "x-tier": "free" } }, "/v1/entities": { "get": { "description": "List knowledge graph entities (people, organizations, places) across all podcast content. Defaults to the most frequently appearing entities, ranked by the number of distinct podcast episodes featuring them. Filter by podcast slug or ID, or fetch specific entities with `ids`. To search by name, use GET /v1/entities/search.", "operationId": "list-entities", "parameters": [ { "description": "Results per page", "explode": false, "in": "query", "name": "limit", "schema": { "default": 25, "description": "Results per page", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque pagination cursor from previous response", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque pagination cursor from previous response", "type": "string" } }, { "description": "Bulk multi-get: one or more entity slugs (e.g. 'sam-altman', 'apple') or IDs, comma-separated (max 100). When set, returns exactly those entities and the other filters (type, podcast_id) and pagination are ignored. Refs that don't resolve are omitted from the response.", "explode": false, "in": "query", "name": "ids", "schema": { "description": "Bulk multi-get: one or more entity slugs (e.g. 'sam-altman', 'apple') or IDs, comma-separated (max 100). When set, returns exactly those entities and the other filters (type, podcast_id) and pagination are ignored. Refs that don't resolve are omitted from the response.", "examples": [ [ "sam-altman", "openai" ] ], "items": { "type": "string" }, "maxItems": 100, "type": [ "array", "null" ] } }, { "description": "Podcast slug (e.g., 'all-in'), internal ID, or numeric iTunes ID. Filter to entities appearing in a specific podcast.", "explode": false, "in": "query", "name": "podcast_id", "schema": { "description": "Podcast slug (e.g., 'all-in'), internal ID, or numeric iTunes ID. Filter to entities appearing in a specific podcast.", "type": "string" } }, { "description": "Filter to an entity category. See GET /v1/entities/types for the available slugs (e.g. 'person', 'company', 'movie', 'sports-team').", "explode": false, "in": "query", "name": "type", "schema": { "description": "Filter to an entity category. See GET /v1/entities/types for the available slugs (e.g. 'person', 'company', 'movie', 'sports-team').", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageEntity" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.01 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "List entities", "tags": [ "Entities", "tier:standard" ], "x-cost-weight": 1, "x-payment-info": { "offers": [ { "amount": "10000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.010000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "standard" } }, "/v1/entities/lookup": { "get": { "description": "Resolves external identifiers — LinkedIn slugs, social handles, company domains, stock tickers, SEC CIKs, Wikidata QIDs — to the people and companies that carry them. It is the reverse of GET /v1/people/{slug}/external-links and GET /v1/companies/{id}/external-links. Pass a comma-separated `identifier` list (up to 100 per call); `platform` is optional, so a handle with no known source still resolves. A full profile URL works in place of a bare identifier and the platform is inferred from it, and the stored form is matched for you — pass `satyanadella` or the profile URL, not `in/satyanadella`.\n\nEach result echoes the input identifier and carries a `matches` array, because an identifier is not unique to an entity: a LinkedIn profile claimed by two duplicate person records resolves to both, and `match_count` reports the total. Unresolved identifiers come back with an empty `matches`, so a bulk caller never has to reconcile a shorter response against a longer request. Correlate by the echoed `identifier` rather than by position, since duplicate identifiers collapse to one result.\n\nUse GET /v1/entities/search instead when you have a name rather than an identifier, and GET /v1/podcasts/lookup or GET /v1/podcasts/episodes/lookup for podcast and episode identifiers.", "operationId": "lookup-entities", "parameters": [ { "description": "One or more external identifiers to resolve. Pass a comma-separated list to look up many at once (max 100 per call). A full profile URL works in place of a bare identifier and the platform is inferred from it. The identifier is echoed back exactly as supplied, not normalized.", "explode": false, "in": "query", "name": "identifier", "required": true, "schema": { "description": "One or more external identifiers to resolve. Pass a comma-separated list to look up many at once (max 100 per call). A full profile URL works in place of a bare identifier and the platform is inferred from it. The identifier is echoed back exactly as supplied, not normalized.", "examples": [ [ "in/satyanadella", "microsoft.com" ] ], "items": { "type": "string" }, "maxItems": 100, "minItems": 1, "type": [ "array", "null" ] } }, { "description": "Restrict the lookup to one platform. Optional — omit it to match the identifier on any platform, which is what you want when you hold a handle but not its source. Accepts any platform reported on the external-links endpoints plus the company identifier namespaces 'domain', 'ticker', 'sec' (CIK) and 'wikidata' (QID).", "explode": false, "in": "query", "name": "platform", "schema": { "description": "Restrict the lookup to one platform. Optional — omit it to match the identifier on any platform, which is what you want when you hold a handle but not its source. Accepts any platform reported on the external-links endpoints plus the company identifier namespaces 'domain', 'ticker', 'sec' (CIK) and 'wikidata' (QID).", "examples": [ "linkedin" ], "type": "string" } }, { "description": "Restrict results to one kind of entity. Omit to search people and companies together.", "explode": false, "in": "query", "name": "type", "schema": { "description": "Restrict results to one kind of entity. Omit to search people and companies together.", "enum": [ "person", "company" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityLookup" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.01 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "Look up people and companies by external identifier", "tags": [ "Entities", "tier:standard" ], "x-cost-weight": 1, "x-payment-info": { "offers": [ { "amount": "10000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.010000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "standard" } }, "/v1/entities/search": { "get": { "description": "Find a person, company, or knowledge graph entity by free-text query — a name, partial name, nickname, stock ticker, @handle, or website domain. Returns the best matches ranked by relevance, each tagged with a `match_quality` so you can tell an exact identification from a fuzzy guess. Use it to turn what a user typed into a specific entity — for example before creating an alert to watch it for podcast mentions. Unlike a knowledge graph entity, a result's top-level `type` may be `person`, `company`, or `knowledge_graph_entity`; pass its `id` or `slug` to the matching resource endpoint (/v1/people, /v1/companies, /v1/entities), or its `id` to alert creation.", "operationId": "search-entities", "parameters": [ { "description": "Results per page", "explode": false, "in": "query", "name": "limit", "schema": { "default": 25, "description": "Results per page", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque pagination cursor from previous response", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque pagination cursor from previous response", "type": "string" } }, { "description": "Free-text query: a name, partial name, nickname, stock ticker, @handle, or website domain (e.g. 'sam altman', 'coca cola', 'AAPL', '@sama', 'apple.com').", "explode": false, "in": "query", "name": "q", "required": true, "schema": { "description": "Free-text query: a name, partial name, nickname, stock ticker, @handle, or website domain (e.g. 'sam altman', 'coca cola', 'AAPL', '@sama', 'apple.com').", "minLength": 1, "type": "string" } }, { "description": "Restrict results to one kind. Omit to search people, companies, and knowledge graph entities together.", "explode": false, "in": "query", "name": "type", "schema": { "description": "Restrict results to one kind. Omit to search people, companies, and knowledge graph entities together.", "enum": [ "person", "company", "knowledge_graph_entity" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageEntitySearchHit" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.01 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "Search entities", "tags": [ "Entities", "tier:standard" ], "x-cost-weight": 1, "x-payment-info": { "offers": [ { "amount": "10000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.010000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "standard" } }, "/v1/entities/types": { "get": { "description": "Returns the entity categories supported as values for the `type` query parameter on /v1/entities and the `entity_type` query parameter on /v1/podcasts/episodes/search.", "operationId": "list-entity-types", "parameters": [ { "description": "Results per page (default: all)", "explode": false, "in": "query", "name": "limit", "schema": { "description": "Results per page (default: all)", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque pagination cursor from previous response", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque pagination cursor from previous response", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageEntityType" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.01 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "List entity types", "tags": [ "Entities", "tier:standard" ], "x-cost-weight": 1, "x-payment-info": { "offers": [ { "amount": "10000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.010000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "standard" } }, "/v1/entities/{id}": { "get": { "description": "Returns a single knowledge graph entity by slug (e.g., 'sam-altman', 'apple') or ID. A person slug or ID (as returned by a `person` hit on /v1/entities/search) also resolves, to that person's linked knowledge graph entity.", "operationId": "get-entity", "parameters": [ { "description": "Entity slug (e.g., 'sam-altman', 'apple') or ID", "in": "path", "name": "id", "required": true, "schema": { "description": "Entity slug (e.g., 'sam-altman', 'apple') or ID", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entity" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.01 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "Get an entity", "tags": [ "Entities", "tier:standard" ], "x-cost-weight": 1, "x-payment-info": { "offers": [ { "amount": "10000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.010000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "standard" } }, "/v1/people/{id}": { "get": { "description": "Returns the comprehensive Person payload including display name, slug, headshot, curated bio, the Person's company-role history (most recent first), known third-party profile links, and an optional knowledge-graph cross-reference. The {id} parameter accepts the Person slug (recommended) or the encoded Person UUID.", "operationId": "get-person", "parameters": [ { "description": "Person identifier. Accepts the Person slug (recommended) or the encoded Person UUID returned as 'id' on every Person payload.", "in": "path", "name": "id", "required": true, "schema": { "description": "Person identifier. Accepts the Person slug (recommended) or the encoded Person UUID returned as 'id' on every Person payload.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Person" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.01 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "Get a Person", "tags": [ "People", "tier:standard" ], "x-cost-weight": 1, "x-payment-info": { "offers": [ { "amount": "10000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.010000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "standard" } }, "/v1/people/{slug}/external-links": { "get": { "description": "Returns every known third-party profile (LinkedIn, Wikipedia, social) for the Person. Discovery happens asynchronously via the v1.person.created enrichment subscriber; a freshly-created Person may not yet have all its profiles populated. Any identifier here resolves back to the Person through GET /v1/entities/lookup.", "operationId": "list-person-external-links", "parameters": [ { "description": "Results per page (default: all)", "explode": false, "in": "query", "name": "limit", "schema": { "description": "Results per page (default: all)", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque pagination cursor from previous response", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque pagination cursor from previous response", "type": "string" } }, { "description": "Person slug (e.g., 'satya-nadella') or the encoded Person UUID.", "in": "path", "name": "slug", "required": true, "schema": { "description": "Person slug (e.g., 'satya-nadella') or the encoded Person UUID.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageExternalLink" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.04 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "List a Person's external profiles", "tags": [ "People", "tier:standard" ], "x-cost-weight": 1, "x-payment-info": { "offers": [ { "amount": "40000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.040000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "standard" } }, "/v1/podcasts": { "get": { "description": "Returns a paginated list of podcasts, with filters for topic, language, suitability tier, popularity, and format. The `q` parameter searches by name and is kept for backwards compatibility — `GET /v1/podcasts/search` is the canonical way to search podcasts, and `q` here may be removed in a future version.", "operationId": "list-podcasts", "parameters": [ { "description": "Results per page", "explode": false, "in": "query", "name": "limit", "schema": { "default": 25, "description": "Results per page", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque pagination cursor from previous response", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque pagination cursor from previous response", "type": "string" } }, { "description": "Search the catalog by podcast name. GET /v1/podcasts/search is the canonical search endpoint and accepts the same parameters. The search is forgiving: it handles typos, missing or extra words ('offline jon favreau' finds Offline with Jon Favreau), a name plus qualifiers ('equity techcrunch'), and pasted episode titles ('Ferrari | Acquired' finds Acquired). The best matches come first, and each result's match_quality tells you how confident the match is — including when a show matched only through its description (match_quality=description) rather than its name.", "explode": false, "in": "query", "name": "q", "schema": { "description": "Search the catalog by podcast name. GET /v1/podcasts/search is the canonical search endpoint and accepts the same parameters. The search is forgiving: it handles typos, missing or extra words ('offline jon favreau' finds Offline with Jon Favreau), a name plus qualifiers ('equity techcrunch'), and pasted episode titles ('Ferrari | Acquired' finds Acquired). The best matches come first, and each result's match_quality tells you how confident the match is — including when a show matched only through its description (match_quality=description) rather than its name.", "maxLength": 200, "type": "string" } }, { "description": "Result ordering. relevance — the default whenever q is present — ranks by how well each podcast matches the query, breaking ties by popularity. popularity orders purely by the global popularity percentile (most popular first; podcasts not currently charting sort last), and also overrides topic_id's concentration ordering. Without q or topic_id, results are popularity-ordered either way.", "explode": false, "in": "query", "name": "sort", "schema": { "description": "Result ordering. relevance — the default whenever q is present — ranks by how well each podcast matches the query, breaking ties by popularity. popularity orders purely by the global popularity percentile (most popular first; podcasts not currently charting sort last), and also overrides topic_id's concentration ordering. Without q or topic_id, results are popularity-ordered either way.", "enum": [ "relevance", "popularity" ], "type": "string" } }, { "description": "Filter by exact podcast slug (e.g., 'all-in'). Slugs are stable, human-readable identifiers returned on every podcast object.", "explode": false, "in": "query", "name": "slug", "schema": { "description": "Filter by exact podcast slug (e.g., 'all-in'). Slugs are stable, human-readable identifiers returned on every podcast object.", "maxLength": 200, "type": "string" } }, { "description": "Filter by topic ID, ancestry slug (e.g., technology/artificial-intelligence), or ancestry path hash. Matches podcasts where the topic accounts for at least 20% of the show's episodes, ranked by topic concentration — not merely podcasts that mention it once.", "explode": false, "in": "query", "name": "topic_id", "schema": { "description": "Filter by topic ID, ancestry slug (e.g., technology/artificial-intelligence), or ancestry path hash. Matches podcasts where the topic accounts for at least 20% of the show's episodes, ranked by topic concentration — not merely podcasts that mention it once.", "type": "string" } }, { "description": "Filter by the podcast's language (ISO 639-1 code, e.g. 'en', 'fr'). Matches the primary language subtag, so 'fr' covers 'fr-FR'.", "explode": false, "in": "query", "name": "language", "schema": { "description": "Filter by the podcast's language (ISO 639-1 code, e.g. 'en', 'fr'). Matches the primary language subtag, so 'fr' covers 'fr-FR'.", "examples": [ "fr" ], "type": "string" } }, { "description": "Filter by brand-suitability tier (IAB Tech Lab Brand Safety \u0026 Suitability Framework, formerly GARM). Only returns podcasts whose most recent suitability analysis assigned this tier. Podcasts without a suitability analysis are excluded when this filter is set.", "explode": false, "in": "query", "name": "suitability_tier", "schema": { "description": "Filter by brand-suitability tier (IAB Tech Lab Brand Safety \u0026 Suitability Framework, formerly GARM). Only returns podcasts whose most recent suitability analysis assigned this tier. Podcasts without a suitability analysis are excluded when this filter is set.", "enum": [ "SAFE", "LIMITED", "SENSITIVE", "UNSAFE" ], "type": "string" } }, { "description": "Restrict results to podcasts whose global popularity percentile is at least this value (accepted range [0,1]). Omitting the parameter or passing 0 disables the filter; only a value greater than 0 activates it. Popularity is always global — a cume_dist ranking over all currently-charting podcasts (Apple Podcasts) — never scoped to topic_id or any other filter. When the filter is active (threshold \u003e 0), podcasts not currently charting have no percentile and are excluded, so a high threshold combined with a narrow topic_id may return zero results; lower or remove the threshold to widen the set.", "explode": false, "in": "query", "name": "popularity_threshold", "schema": { "description": "Restrict results to podcasts whose global popularity percentile is at least this value (accepted range [0,1]). Omitting the parameter or passing 0 disables the filter; only a value greater than 0 activates it. Popularity is always global — a cume_dist ranking over all currently-charting podcasts (Apple Podcasts) — never scoped to topic_id or any other filter. When the filter is active (threshold \u003e 0), podcasts not currently charting have no percentile and are excluded, so a high threshold combined with a narrow topic_id may return zero results; lower or remove the threshold to widen the set.", "format": "double", "maximum": 1, "minimum": 0, "type": "number" } }, { "description": "Filter by how often episodes feature a guest. Pass a comma-separated list to match any of several buckets — e.g. regular,always for interview-driven shows, or never for shows that don't host guests. Only matches podcasts with enough analyzed episodes to judge; values mirror the format.guest_frequency field on podcast responses.", "explode": false, "in": "query", "name": "guest_frequency", "schema": { "description": "Filter by how often episodes feature a guest. Pass a comma-separated list to match any of several buckets — e.g. regular,always for interview-driven shows, or never for shows that don't host guests. Only matches podcasts with enough analyzed episodes to judge; values mirror the format.guest_frequency field on podcast responses.", "examples": [ [ "regular", "always" ] ], "items": { "enum": [ "never", "rare", "occasional", "regular", "always" ], "type": "string" }, "maxItems": 5, "type": [ "array", "null" ] } }, { "description": "Filter by detected production format. Pass a comma-separated list to match any of several formats — e.g. panel,call_in. Values mirror the format.signals field on podcast responses; a show can carry several signals.", "explode": false, "in": "query", "name": "format_signal", "schema": { "description": "Filter by detected production format. Pass a comma-separated list to match any of several formats — e.g. panel,call_in. Values mirror the format.signals field on podcast responses; a show can carry several signals.", "examples": [ [ "interview" ] ], "items": { "enum": [ "interview", "panel", "call_in", "solo_narrated" ], "type": "string" }, "maxItems": 4, "type": [ "array", "null" ] } }, { "description": "Filter by advertiser presence. Pass false to find ad-free shows — an assertion that requires the show to have enough analyzed episodes, so sparsely-analyzed podcasts are excluded rather than presumed ad-free.", "explode": false, "in": "query", "name": "has_ads", "schema": { "description": "Filter by advertiser presence. Pass false to find ad-free shows — an assertion that requires the show to have enough analyzed episodes, so sparsely-analyzed podcasts are excluded rather than presumed ad-free.", "enum": [ "true", "false" ], "type": "string" } }, { "description": "Filter by whether episodes have discovered video versions (e.g. YouTube releases).", "explode": false, "in": "query", "name": "has_video", "schema": { "description": "Filter by whether episodes have discovered video versions (e.g. YouTube releases).", "enum": [ "true", "false" ], "type": "string" } }, { "description": "Only podcasts whose average episode runs at least this many minutes. Combine with max_avg_episode_minutes to target a length band (e.g. 20–40 minute commute shows).", "explode": false, "in": "query", "name": "min_avg_episode_minutes", "schema": { "description": "Only podcasts whose average episode runs at least this many minutes. Combine with max_avg_episode_minutes to target a length band (e.g. 20–40 minute commute shows).", "format": "int64", "maximum": 10080, "minimum": 0, "type": "integer" } }, { "description": "Only podcasts whose average episode runs at most this many minutes.", "explode": false, "in": "query", "name": "max_avg_episode_minutes", "schema": { "description": "Only podcasts whose average episode runs at most this many minutes.", "format": "int64", "maximum": 10080, "minimum": 0, "type": "integer" } }, { "description": "Only podcasts publishing at least this many episodes per week on average (e.g. 5 for weekday dailies). Cadence is measured over the trailing 90 days; podcasts tracked too briefly to measure are excluded.", "explode": false, "in": "query", "name": "min_episodes_per_week", "schema": { "description": "Only podcasts publishing at least this many episodes per week on average (e.g. 5 for weekday dailies). Cadence is measured over the trailing 90 days; podcasts tracked too briefly to measure are excluded.", "format": "double", "minimum": 0, "type": "number" } }, { "description": "Only podcasts publishing at most this many episodes per week on average (e.g. 0.5 for fortnightly-or-slower shows).", "explode": false, "in": "query", "name": "max_episodes_per_week", "schema": { "description": "Only podcasts publishing at most this many episodes per week on average (e.g. 0.5 for fortnightly-or-slower shows).", "format": "double", "minimum": 0, "type": "number" } }, { "description": "Filter by publishing activity: active shows have released an episode within the last 90 days; dormant shows have not.", "explode": false, "in": "query", "name": "publishing_status", "schema": { "description": "Filter by publishing activity: active shows have released an episode within the last 90 days; dormant shows have not.", "enum": [ "active", "dormant" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagePodcast" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.01 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "List and search podcasts", "tags": [ "Podcasts", "tier:standard" ], "x-cost-weight": 1, "x-payment-info": { "offers": [ { "amount": "10000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.010000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "standard" } }, "/v1/podcasts/advertising/co-occurrence": { "get": { "description": "Returns pairs of sponsors that frequently appear together in the same podcast episodes.", "operationId": "get-sponsor-co-occurrence", "parameters": [ { "description": "Results per page", "explode": false, "in": "query", "name": "limit", "schema": { "default": 25, "description": "Results per page", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque pagination cursor from previous response", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque pagination cursor from previous response", "type": "string" } }, { "description": "Filter to pairs involving this sponsor ID", "explode": false, "in": "query", "name": "sponsor_id", "schema": { "description": "Filter to pairs involving this sponsor ID", "type": "string" } }, { "description": "Filter by company ID, domain, or entity slug", "explode": false, "in": "query", "name": "company_id", "schema": { "description": "Filter by company ID, domain, or entity slug", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageCoOccurrenceEntry" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.04 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "Get sponsor co-occurrence", "tags": [ "Podcast Advertising", "tier:premium" ], "x-cost-weight": 3, "x-payment-info": { "offers": [ { "amount": "40000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.040000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "premium" } }, "/v1/podcasts/advertising/leaderboard": { "get": { "description": "Returns the top podcast advertising sponsors ranked by the specified metric, with optional time range and company filtering. All-time rankings — and two day-anchored windows: the trailing 7 days (since = UTC today−7d, no until) and the 7-day window ending 30 days ago (since = today−37d, until = today−30d) — reflect periodically refreshed snapshots; other time-windowed and company-filtered results may be cached for up to one hour.", "operationId": "get-advertising-leaderboard", "parameters": [ { "description": "Results per page", "explode": false, "in": "query", "name": "limit", "schema": { "default": 25, "description": "Results per page", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque pagination cursor from previous response", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque pagination cursor from previous response", "type": "string" } }, { "description": "Metric to rank sponsors by", "explode": false, "in": "query", "name": "metric", "schema": { "default": "ad_count", "description": "Metric to rank sponsors by", "enum": [ "ad_count", "podcast_reach", "episode_reach" ], "type": "string" } }, { "description": "Only include ads from episodes published on or after this ISO 8601 date or date-time (e.g. 2025-01-01 or 2025-01-01T00:00:00Z)", "explode": false, "in": "query", "name": "since", "schema": { "description": "Only include ads from episodes published on or after this ISO 8601 date or date-time (e.g. 2025-01-01 or 2025-01-01T00:00:00Z)", "examples": [ "2025-01-01T00:00:00Z" ], "type": "string" } }, { "description": "Only include ads from episodes published before this ISO 8601 date or date-time (e.g. 2026-01-01 or 2026-01-01T00:00:00Z)", "explode": false, "in": "query", "name": "until", "schema": { "description": "Only include ads from episodes published before this ISO 8601 date or date-time (e.g. 2026-01-01 or 2026-01-01T00:00:00Z)", "examples": [ "2026-01-01T00:00:00Z" ], "type": "string" } }, { "description": "Filter by company ID, domain, or entity slug", "explode": false, "in": "query", "name": "company_id", "schema": { "description": "Filter by company ID, domain, or entity slug", "type": "string" } }, { "description": "Restrict the leaderboard to ads on podcasts attributed to this publisher (slug or ID)", "explode": false, "in": "query", "name": "publisher_id", "schema": { "description": "Restrict the leaderboard to ads on podcasts attributed to this publisher (slug or ID)", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageLeaderboardEntryV1" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.04 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "Get advertising leaderboard", "tags": [ "Podcast Advertising", "tier:premium" ], "x-cost-weight": 3, "x-payment-info": { "offers": [ { "amount": "40000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.040000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "premium" } }, "/v1/podcasts/advertising/leaderboard/preview": { "get": { "description": "Returns the top 10 advertising sponsors of the trailing 7 days ranked by the chosen metric, each with its rank movement versus the equivalent 7-day window ending 30 days ago. Every caller gets the same board regardless of plan, so unlike get-advertising-leaderboard this endpoint requires no premium access and is safe to render for signed-out visitors. Use get-advertising-leaderboard for deeper pages, other time windows, and company or publisher filtering.", "operationId": "get-advertising-leaderboard-preview", "parameters": [ { "description": "Metric to rank sponsors by", "explode": false, "in": "query", "name": "metric", "schema": { "default": "ad_count", "description": "Metric to rank sponsors by", "enum": [ "ad_count", "podcast_reach", "episode_reach" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageLeaderboardPreviewEntry" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.01 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "Get advertising leaderboard preview", "tags": [ "Podcast Advertising", "tier:standard" ], "x-cost-weight": 1, "x-payment-info": { "offers": [ { "amount": "10000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.010000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "standard" } }, "/v1/podcasts/advertising/publishers/leaderboard": { "get": { "description": "Ranks podcast publishers by an advertising activity metric across their entire catalog. ads_per_active_podcast is the monetization-density metric — small sub-networks (e.g. 'iHeartPodcasts and The Volume', 'Dan Patrick Network') typically rank far above broad catalogs on this dimension.", "operationId": "get-publisher-advertising-leaderboard", "parameters": [ { "description": "Results per page", "explode": false, "in": "query", "name": "limit", "schema": { "default": 25, "description": "Results per page", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque pagination cursor from previous response", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque pagination cursor from previous response", "type": "string" } }, { "description": "Metric to rank publishers by. ads_per_active_podcast surfaces monetization density (small sub-networks often outrank big catalogs). Ranking reflects an all-time MV-fresh snapshot; this endpoint does not currently support time-window filters.", "explode": false, "in": "query", "name": "metric", "schema": { "default": "ad_count", "description": "Metric to rank publishers by. ads_per_active_podcast surfaces monetization density (small sub-networks often outrank big catalogs). Ranking reflects an all-time MV-fresh snapshot; this endpoint does not currently support time-window filters.", "enum": [ "ad_count", "unique_sponsors", "podcast_reach", "episode_reach", "ads_per_active_podcast" ], "type": "string" } }, { "description": "Only rank publishers with at least this many active podcasts (catalog podcasts that have run at least one detected ad). Guards ads_per_active_podcast and the other density-style metrics against tiny catalogs dominating the leaderboard — single-show publishers can otherwise rank #1 on ads_per_active_podcast purely on noise.", "explode": false, "in": "query", "name": "min_active_podcasts", "schema": { "default": 5, "description": "Only rank publishers with at least this many active podcasts (catalog podcasts that have run at least one detected ad). Guards ads_per_active_podcast and the other density-style metrics against tiny catalogs dominating the leaderboard — single-show publishers can otherwise rank #1 on ads_per_active_podcast purely on noise.", "format": "int64", "maximum": 1000, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagePublisherAdvertisingLeaderboardEntry" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.04 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "Get publisher advertising leaderboard", "tags": [ "Podcast Advertising", "tier:premium" ], "x-cost-weight": 3, "x-payment-info": { "offers": [ { "amount": "40000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.040000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "premium" } }, "/v1/podcasts/advertising/sponsors": { "get": { "description": "Returns a paginated list of podcast advertising sponsors, optionally filtered by name search or company.", "operationId": "list-sponsors", "parameters": [ { "description": "Results per page", "explode": false, "in": "query", "name": "limit", "schema": { "default": 25, "description": "Results per page", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque pagination cursor from previous response", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque pagination cursor from previous response", "type": "string" } }, { "description": "Search by name (case-insensitive partial match)", "explode": false, "in": "query", "name": "q", "schema": { "description": "Search by name (case-insensitive partial match)", "examples": [ "Apple" ], "maxLength": 200, "type": "string" } }, { "description": "Filter by company ID, domain, or entity slug", "explode": false, "in": "query", "name": "company_id", "schema": { "description": "Filter by company ID, domain, or entity slug", "type": "string" } }, { "description": "Scope each sponsor's ad_count, podcast_reach, and episode_reach to ads from episodes published on or after this ISO 8601 date or date-time. Does not exclude sponsors with zero activity in the window.", "explode": false, "in": "query", "name": "since", "schema": { "description": "Scope each sponsor's ad_count, podcast_reach, and episode_reach to ads from episodes published on or after this ISO 8601 date or date-time. Does not exclude sponsors with zero activity in the window.", "examples": [ "2025-01-01T00:00:00Z" ], "type": "string" } }, { "description": "Scope each sponsor's ad_count, podcast_reach, and episode_reach to ads from episodes published before this ISO 8601 date or date-time.", "explode": false, "in": "query", "name": "until", "schema": { "description": "Scope each sponsor's ad_count, podcast_reach, and episode_reach to ads from episodes published before this ISO 8601 date or date-time.", "examples": [ "2026-01-01T00:00:00Z" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageSponsor" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.03 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "List sponsors", "tags": [ "Podcast Advertising", "tier:premium" ], "x-cost-weight": 2, "x-payment-info": { "offers": [ { "amount": "30000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.030000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "premium" } }, "/v1/podcasts/advertising/sponsors/trends": { "get": { "description": "Surfaces advertisers whose podcast ad volume is accelerating. Each row compares the sponsor's ads aired in the trailing window (default 7 days) against the equal-length window immediately before it, ranked by the delta. Windowing follows episode publication dates, so rankings reflect when ads aired, not when they were ingested. Results may be cached for up to one hour.", "operationId": "list-sponsor-trends", "parameters": [ { "description": "Results per page", "explode": false, "in": "query", "name": "limit", "schema": { "default": 25, "description": "Results per page", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque pagination cursor from previous response", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque pagination cursor from previous response", "type": "string" } }, { "description": "Length in days of each comparison window. Sponsors are ranked by ads aired in the trailing window_days versus the equal-length window immediately before it.", "explode": false, "in": "query", "name": "window_days", "schema": { "default": 7, "description": "Length in days of each comparison window. Sponsors are ranked by ads aired in the trailing window_days versus the equal-length window immediately before it.", "format": "int64", "maximum": 90, "minimum": 1, "type": "integer" } }, { "description": "Only include sponsors whose in-window ads span at least this many distinct podcasts. Guards the ranking against a single show binge-publishing episodes of one sponsor.", "explode": false, "in": "query", "name": "min_podcast_reach", "schema": { "default": 3, "description": "Only include sponsors whose in-window ads span at least this many distinct podcasts. Guards the ranking against a single show binge-publishing episodes of one sponsor.", "format": "int64", "maximum": 1000, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageSponsorTrend" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.04 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "List trending sponsors", "tags": [ "Podcast Advertising", "tier:premium" ], "x-cost-weight": 3, "x-payment-info": { "offers": [ { "amount": "40000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.040000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "premium" } }, "/v1/podcasts/advertising/sponsors/{id}": { "get": { "description": "Returns a single advertising sponsor with activity metrics. The {id} path parameter accepts a sponsor ID, a company ID, a company domain, or a company slug.", "operationId": "get-sponsor", "parameters": [ { "description": "Sponsor ID, company ID, company domain, or company slug. When a company reference matches multiple sponsor aliases, the most-recently-active sponsor is returned.", "in": "path", "name": "id", "required": true, "schema": { "description": "Sponsor ID, company ID, company domain, or company slug. When a company reference matches multiple sponsor aliases, the most-recently-active sponsor is returned.", "type": "string" } }, { "description": "Only include ads from episodes published on or after this ISO 8601 date or date-time", "explode": false, "in": "query", "name": "since", "schema": { "description": "Only include ads from episodes published on or after this ISO 8601 date or date-time", "examples": [ "2025-01-01T00:00:00Z" ], "type": "string" } }, { "description": "Only include ads from episodes published before this ISO 8601 date or date-time", "explode": false, "in": "query", "name": "until", "schema": { "description": "Only include ads from episodes published before this ISO 8601 date or date-time", "examples": [ "2026-01-01T00:00:00Z" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Sponsor" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.03 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "Get a sponsor", "tags": [ "Podcast Advertising", "tier:premium" ], "x-cost-weight": 2, "x-payment-info": { "offers": [ { "amount": "30000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.030000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "premium" } }, "/v1/podcasts/advertising/sponsors/{id}/podcasts": { "get": { "description": "Returns a paginated list of podcasts where the sponsor advertises, ordered by the number of episodes featuring the sponsor.", "operationId": "list-sponsor-podcasts", "parameters": [ { "description": "Results per page", "explode": false, "in": "query", "name": "limit", "schema": { "default": 25, "description": "Results per page", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque pagination cursor from previous response", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque pagination cursor from previous response", "type": "string" } }, { "description": "Sponsor ID, company ID, company domain, or company slug", "in": "path", "name": "id", "required": true, "schema": { "description": "Sponsor ID, company ID, company domain, or company slug", "type": "string" } }, { "description": "Only include ads from episodes published on or after this ISO 8601 date or date-time", "explode": false, "in": "query", "name": "since", "schema": { "description": "Only include ads from episodes published on or after this ISO 8601 date or date-time", "examples": [ "2025-01-01T00:00:00Z" ], "type": "string" } }, { "description": "Only include ads from episodes published before this ISO 8601 date or date-time", "explode": false, "in": "query", "name": "until", "schema": { "description": "Only include ads from episodes published before this ISO 8601 date or date-time", "examples": [ "2026-01-01T00:00:00Z" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageSponsorPodcastEntry" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.03 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "List podcasts for a sponsor", "tags": [ "Podcast Advertising", "tier:premium" ], "x-cost-weight": 3, "x-payment-info": { "offers": [ { "amount": "30000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.030000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "premium" } }, "/v1/podcasts/advertising/sponsors/{id}/publishers": { "get": { "description": "Returns the podcast publishers a sponsor advertises across, ordered by podcast coverage (the count of distinct publisher podcasts where the sponsor appears). Surfaces the bundle-buy signature: a sponsor showing 60–100% coverage on multiple publishers is doing network buys, not per-show buys.", "operationId": "list-sponsor-publishers", "parameters": [ { "description": "Results per page", "explode": false, "in": "query", "name": "limit", "schema": { "default": 25, "description": "Results per page", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque pagination cursor from previous response", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque pagination cursor from previous response", "type": "string" } }, { "description": "Sponsor ID, company ID, company domain, or company slug. When the value resolves to a company (not a specific sponsor), the response aggregates across every sponsor linked to that company — the canonical 'where does this advertiser buy?' view. When it resolves to a sponsor ID, the response is scoped to that single deduped sponsor.", "in": "path", "name": "id", "required": true, "schema": { "description": "Sponsor ID, company ID, company domain, or company slug. When the value resolves to a company (not a specific sponsor), the response aggregates across every sponsor linked to that company — the canonical 'where does this advertiser buy?' view. When it resolves to a sponsor ID, the response is scoped to that single deduped sponsor.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageSponsorPublisherEntry" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.03 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "List publishers for a sponsor", "tags": [ "Podcast Advertising", "tier:premium" ], "x-cost-weight": 2, "x-payment-info": { "offers": [ { "amount": "30000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.030000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "premium" } }, "/v1/podcasts/advertising/sponsors/{id}/segments": { "get": { "description": "Returns the individual ad segments attributed to a sponsor, ordered by episode publication date descending, optionally scoped to a single podcast. Results are consistent with the ad_count values from the sponsor podcasts endpoint. Network promos are excluded.", "operationId": "list-sponsor-segments", "parameters": [ { "description": "Results per page", "explode": false, "in": "query", "name": "limit", "schema": { "default": 25, "description": "Results per page", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque pagination cursor from previous response", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque pagination cursor from previous response", "type": "string" } }, { "description": "Sponsor ID, company ID, company domain, or company slug", "in": "path", "name": "id", "required": true, "schema": { "description": "Sponsor ID, company ID, company domain, or company slug", "type": "string" } }, { "description": "Scope results to one podcast by slug, internal ID, or numeric iTunes ID", "explode": false, "in": "query", "name": "podcast_id", "schema": { "description": "Scope results to one podcast by slug, internal ID, or numeric iTunes ID", "type": "string" } }, { "description": "Only include ads from episodes published on or after this ISO 8601 date or date-time", "explode": false, "in": "query", "name": "since", "schema": { "description": "Only include ads from episodes published on or after this ISO 8601 date or date-time", "examples": [ "2025-01-01T00:00:00Z" ], "type": "string" } }, { "description": "Only include ads from episodes published before this ISO 8601 date or date-time", "explode": false, "in": "query", "name": "until", "schema": { "description": "Only include ads from episodes published before this ISO 8601 date or date-time", "examples": [ "2026-01-01T00:00:00Z" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageSegment" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.03 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "List ad segments for a sponsor", "tags": [ "Podcast Advertising", "tier:premium" ], "x-cost-weight": 3, "x-payment-info": { "offers": [ { "amount": "30000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.030000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "premium" } }, "/v1/podcasts/advertising/timeseries": { "get": { "description": "Returns time-bucketed ad placement counts for a sponsor or company, split into host-read and pre-recorded placements, plus range totals. Exactly one of sponsor_id or company_id is required; company_id aggregates across every sponsor alias linked to the company. Pass podcast_id or publisher_id to scope the counts to one show or network, matching the mentions timeseries so both series can be charted under the same scope. Counts use the same attribution as the sponsor podcasts and segments endpoints, so bucket sums agree with their ad_count values. Network promos are excluded.", "operationId": "get-advertising-timeseries", "parameters": [ { "description": "Sponsor ID. Exactly one of sponsor_id or company_id is required.", "explode": false, "in": "query", "name": "sponsor_id", "schema": { "description": "Sponsor ID. Exactly one of sponsor_id or company_id is required.", "type": "string" } }, { "description": "Company ID, domain, or entity slug. Aggregates across every sponsor alias linked to the company.", "explode": false, "in": "query", "name": "company_id", "schema": { "description": "Company ID, domain, or entity slug. Aggregates across every sponsor alias linked to the company.", "type": "string" } }, { "description": "Restrict to ad placements on one podcast, by slug or ID.", "explode": false, "in": "query", "name": "podcast_id", "schema": { "description": "Restrict to ad placements on one podcast, by slug or ID.", "type": "string" } }, { "description": "Restrict to ad placements on podcasts attributed to one publisher (network), by slug or ID.", "explode": false, "in": "query", "name": "publisher_id", "schema": { "description": "Restrict to ad placements on podcasts attributed to one publisher (network), by slug or ID.", "type": "string" } }, { "description": "Inclusive start of the range as an ISO 8601 date or date-time. Omit for all time.", "explode": false, "in": "query", "name": "published_after", "schema": { "description": "Inclusive start of the range as an ISO 8601 date or date-time. Omit for all time.", "type": "string" } }, { "description": "End of the range as an ISO 8601 date or date-time. A bare date includes that whole day. Defaults to now.", "explode": false, "in": "query", "name": "published_before", "schema": { "description": "End of the range as an ISO 8601 date or date-time. A bare date includes that whole day. Defaults to now.", "type": "string" } }, { "description": "Bucket width. Weeks start on Monday and all buckets are UTC-aligned.", "explode": false, "in": "query", "name": "interval", "schema": { "default": "week", "description": "Bucket width. Weeks start on Monday and all buckets are UTC-aligned.", "enum": [ "day", "week", "month" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdvertisingTimeseries" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.04 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "Get advertising timeseries", "tags": [ "Podcast Advertising", "tier:premium" ], "x-cost-weight": 3, "x-payment-info": { "offers": [ { "amount": "40000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.040000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "premium" } }, "/v1/podcasts/archive/download": { "get": { "description": "Downloads every live podcast as gzip-compressed JSON Lines, one show per line. Each line is the podcast exactly as `GET /v1/podcasts/{id}` returns it with every section (`include=related,recommended_guests,recommended_sponsors,coverage`), plus its `external_links` with their attributes, as `GET /v1/podcasts/{id}/external-links` returns them. **Available by arrangement**, with the episode archive. The file is rebuilt twice a day; its values, popularity and audience metrics among them, are as of the current build, which `Last-Modified` dates. Replace your copy rather than merging into it: a show missing from a newer download has been removed. The download can be resumed with a Range request, and `If-None-Match` with its `ETag` returns 304 until the next build.", "operationId": "download-podcast-archive", "responses": { "200": { "content": { "application/gzip": { "schema": { "contentMediaType": "application/octet-stream", "format": "binary", "type": "string" } } }, "description": "The file." }, "206": { "content": { "application/gzip": { "schema": { "contentMediaType": "application/octet-stream", "format": "binary", "type": "string" } } }, "description": "The requested byte range of the file, answering a Range request." }, "304": { "description": "Not modified: the If-None-Match tag still matches, or, without one, the file has not changed since If-Modified-Since. No body." }, "416": { "description": "The requested range lies outside the file." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "summary": "Download the show archive", "tags": [ "Podcasts", "tier:standard" ], "x-cost-weight": 1, "x-entitlement-priced": true, "x-episode-archive-only": true, "x-tier": "standard" } }, "/v1/podcasts/bias/publishers/leaderboard": { "get": { "description": "Returns a paginated leaderboard ranking publishers by a chosen bias metric: most_left_leaning, most_right_leaning, most_political, most_diverse, most_monolithic, or most_analyzed. min_analyzed_podcasts and min_political_podcasts gate small-sample publishers from the ranking. Optional political_context, since, and until restrict the corpus before aggregation.", "operationId": "get-podcast-publisher-bias-leaderboard", "parameters": [ { "description": "Results per page", "explode": false, "in": "query", "name": "limit", "schema": { "default": 25, "description": "Results per page", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque pagination cursor from previous response", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque pagination cursor from previous response", "type": "string" } }, { "description": "Ranking metric. most_left/right_leaning rank by avg_lean_score; most_political by share of political podcasts in the catalog; most_diverse / most_monolithic by stddev of lean across political podcasts; most_analyzed by catalog coverage.", "explode": false, "in": "query", "name": "metric", "required": true, "schema": { "description": "Ranking metric. most_left/right_leaning rank by avg_lean_score; most_political by share of political podcasts in the catalog; most_diverse / most_monolithic by stddev of lean across political podcasts; most_analyzed by catalog coverage.", "enum": [ "most_left_leaning", "most_right_leaning", "most_political", "most_diverse", "most_monolithic", "most_analyzed" ], "type": "string" } }, { "description": "Restrict the underlying corpus to a single political framework before aggregating.", "explode": false, "in": "query", "name": "political_context", "schema": { "description": "Restrict the underlying corpus to a single political framework before aggregating.", "enum": [ "US", "UK", "EU", "CANADA", "AUSTRALIA", "INDIA", "OTHER", "UNKNOWN" ], "type": "string" } }, { "description": "Only rank publishers with at least this many analyzed podcasts. Below the default of 5, aggregate signals are unreliable.", "explode": false, "in": "query", "name": "min_analyzed_podcasts", "schema": { "default": 5, "description": "Only rank publishers with at least this many analyzed podcasts. Below the default of 5, aggregate signals are unreliable.", "format": "int64", "maximum": 500, "minimum": 1, "type": "integer" } }, { "description": "Only rank publishers with at least this many political podcasts. Applied to score and diversity metrics; ignored for coverage metrics.", "explode": false, "in": "query", "name": "min_political_podcasts", "schema": { "default": 5, "description": "Only rank publishers with at least this many political podcasts. Applied to score and diversity metrics; ignored for coverage metrics.", "format": "int64", "maximum": 500, "minimum": 1, "type": "integer" } }, { "description": "Restrict to analyses evaluated on or after this timestamp (RFC 3339)", "explode": false, "in": "query", "name": "since", "schema": { "description": "Restrict to analyses evaluated on or after this timestamp (RFC 3339)", "format": "date-time", "type": "string" } }, { "description": "Restrict to analyses evaluated strictly before this timestamp (RFC 3339)", "explode": false, "in": "query", "name": "until", "schema": { "description": "Restrict to analyses evaluated strictly before this timestamp (RFC 3339)", "format": "date-time", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagePodcastPublisherBiasLeaderboardEntry" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.04 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "Rank publishers by political bias metric", "tags": [ "Podcast Bias", "tier:premium" ], "x-cost-weight": 3, "x-payment-info": { "offers": [ { "amount": "40000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.040000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "premium" } }, "/v1/podcasts/bias/{result}/publishers": { "get": { "description": "Returns a paginated list of publishers whose analyzed catalog contains at least min_count podcasts in the requested bias bucket, ranked by raw count or by share of the publisher's analyzed catalog. Useful as a flip of the publisher bias profile — answers 'which publishers carry the most RIGHT-leaning shows?'.", "operationId": "list-bias-podcast-publishers", "parameters": [ { "description": "Results per page", "explode": false, "in": "query", "name": "limit", "schema": { "default": 25, "description": "Results per page", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque pagination cursor from previous response", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque pagination cursor from previous response", "type": "string" } }, { "description": "Bias bucket to flip on", "in": "path", "name": "result", "required": true, "schema": { "description": "Bias bucket to flip on", "enum": [ "NOT_POLITICAL", "EXTREME_LEFT", "LEFT", "LEANS_LEFT", "CENTER", "LEANS_RIGHT", "RIGHT", "EXTREME_RIGHT" ], "type": "string" } }, { "description": "Restrict the underlying corpus to a single political framework before aggregating.", "explode": false, "in": "query", "name": "political_context", "schema": { "description": "Restrict the underlying corpus to a single political framework before aggregating.", "enum": [ "US", "UK", "EU", "CANADA", "AUSTRALIA", "INDIA", "OTHER", "UNKNOWN" ], "type": "string" } }, { "description": "Only return publishers with at least this many podcasts in the requested bucket.", "explode": false, "in": "query", "name": "min_count", "schema": { "default": 1, "description": "Only return publishers with at least this many podcasts in the requested bucket.", "format": "int64", "maximum": 500, "minimum": 1, "type": "integer" } }, { "description": "count ranks by raw podcasts_in_bucket; share ranks by podcasts_in_bucket / analyzed_podcasts to surface publishers whose catalog is concentrated in this bucket.", "explode": false, "in": "query", "name": "sort", "schema": { "default": "count", "description": "count ranks by raw podcasts_in_bucket; share ranks by podcasts_in_bucket / analyzed_podcasts to surface publishers whose catalog is concentrated in this bucket.", "enum": [ "count", "share" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageBiasPodcastPublisherEntry" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.03 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "List publishers with podcasts in a bias bucket", "tags": [ "Podcast Bias", "tier:premium" ], "x-cost-weight": 2, "x-payment-info": { "offers": [ { "amount": "30000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.030000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "premium" } }, "/v1/podcasts/clips": { "get": { "description": "Returns AI-extracted highlight clips across podcast episodes, ranked by engagement potential. Filter by podcast, episode, clip type, minimum engagement score, or speaker (the person talking in the clip). For text-based clip discovery (semantic, keyword, or entity mention search), use GET /v1/podcasts/episodes/search — matching clips are embedded inside each search result alongside the parent segment and dialogue.", "operationId": "list-clips", "parameters": [ { "description": "Results per page", "explode": false, "in": "query", "name": "limit", "schema": { "default": 25, "description": "Results per page", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque pagination cursor from previous response", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque pagination cursor from previous response", "type": "string" } }, { "description": "Filter to a specific episode by slug or ID", "explode": false, "in": "query", "name": "episode_id", "schema": { "description": "Filter to a specific episode by slug or ID", "type": "string" } }, { "description": "Podcast slug (e.g., 'all-in'), internal ID, or numeric iTunes ID", "explode": false, "in": "query", "name": "podcast_id", "schema": { "description": "Podcast slug (e.g., 'all-in'), internal ID, or numeric iTunes ID", "type": "string" } }, { "description": "Speaker filter: person slug (e.g., 'sam-altman'), knowledge-graph entity slug for the same person, or ID. Returns only clips whose primary speaker is this person.", "explode": false, "in": "query", "name": "speaker", "schema": { "description": "Speaker filter: person slug (e.g., 'sam-altman'), knowledge-graph entity slug for the same person, or ID. Returns only clips whose primary speaker is this person.", "type": "string" } }, { "description": "Clip type filter: SPICY, CONTROVERSIAL, EMOTIONAL, FUNNY, SHOCKING, INSIGHTFUL, INFORMATIVE, EDUCATIONAL, PHILOSOPHICAL, AHA_MOMENT, NOTABLE_LINE, BEST_STORY, DEBATE_DISAGREEMENT", "explode": false, "in": "query", "name": "type", "schema": { "description": "Clip type filter: SPICY, CONTROVERSIAL, EMOTIONAL, FUNNY, SHOCKING, INSIGHTFUL, INFORMATIVE, EDUCATIONAL, PHILOSOPHICAL, AHA_MOMENT, NOTABLE_LINE, BEST_STORY, DEBATE_DISAGREEMENT", "type": "string" } }, { "description": "Minimum engagement potential score (integer, 0 to 100). Values above 70 are typical for a strong clip.", "explode": false, "in": "query", "name": "min_engagement", "schema": { "description": "Minimum engagement potential score (integer, 0 to 100). Values above 70 are typical for a strong clip.", "format": "int64", "maximum": 100, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageClip" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.03 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "List clips", "tags": [ "Podcast Clips", "tier:standard" ], "x-cost-weight": 1, "x-payment-info": { "offers": [ { "amount": "30000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.030000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "standard" } }, "/v1/podcasts/clips/{id}": { "get": { "description": "Returns a single clip by its unique identifier.", "operationId": "get-clip", "parameters": [ { "description": "Clip ID", "in": "path", "name": "id", "required": true, "schema": { "description": "Clip ID", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Clip" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.03 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "Get a clip", "tags": [ "Podcast Clips", "tier:standard" ], "x-cost-weight": 1, "x-payment-info": { "offers": [ { "amount": "30000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.030000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "standard" } }, "/v1/podcasts/clips/{id}/transcript": { "get": { "description": "Returns the diarized transcript for a specific clip.", "operationId": "get-clip-transcript", "parameters": [ { "description": "Clip ID", "in": "path", "name": "id", "required": true, "schema": { "description": "Clip ID", "type": "string" } }, { "description": "Output format", "explode": false, "in": "query", "name": "format", "schema": { "default": "dialogue", "description": "Output format", "enum": [ "dialogue", "text", "srt" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.03 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "Get clip transcript", "tags": [ "Podcast Transcripts", "tier:standard" ], "x-cost-weight": 1, "x-payment-info": { "offers": [ { "amount": "30000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.030000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "standard" } }, "/v1/podcasts/entities/charts": { "get": { "description": "Returns every entity chart with the headline state of its current edition: the edition date, whether narratives have been written yet, and what sits at rank 1. Each chart's `source` says whether its entries measure entity mentions or guest appearances, `group` tabs the directory into overall, entertainment, and sports, and `windows` lists the windows that chart publishes. Use the returned `category_slug` to fetch a full chart. Every chart lists, but `leader` is omitted for charts the caller may not read: an API key reads every chart, while a session without paid Radar access reads only the `all` chart.", "operationId": "list-entity-charts", "parameters": [ { "description": "Measurement window for the editions to summarize.", "explode": false, "in": "query", "name": "window", "schema": { "default": "7d", "description": "Measurement window for the editions to summarize.", "enum": [ "7d", "24h" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageEntityChartSummary" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.10 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "List entity charts", "tags": [ "Entity Charts", "tier:standard" ], "x-cost-weight": 1, "x-payment-info": { "offers": [ { "amount": "100000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.100000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "standard" } }, "/v1/podcasts/entities/charts/{category}": { "get": { "description": "Returns the current edition of one chart, each entry with its movement since the previous edition. How the chart ranks depends on the chart. The per-category mention charts (`tv-series`, `movies`, `video-games`) rank entities by how many distinct podcasts mentioned them organically in the window, which is `podcast_count`. The sports charts (`nfl`, `nba`, `mlb`, `nhl`, `college-football`, `wnba`, `college-basketball`, `soccer`, `golf`, `tennis`, `formula-1`, `nascar`, `pro-wrestling`) rank the players, teams, coaches, and events resolved into that league or sport rather than a single entity type, so their entries mix subject kinds. A sports chart blends each member's reach, measured against members of the same kind, with 52-day elevation, so its ranks do not follow `podcast_count`, and league organizations such as divisions sit below the top 10. The composite charts rank by a blend of reach and 52-day elevation, so their ranks do not follow `podcast_count`: `all` draws on a wider curated pool of entity types — people, books, music, brands, companies and organizations, sports, events, and products as well as the three published categories — while `all-entertainment` and `all-sports` pool only their own group's charts, so an entry there always has a sibling chart to drill into. The guests chart ranks people by the distinct shows they appeared on. When the narrative pipeline has explained an entry, `why` carries a one-line explanation and, when one was captured, the verbatim quote with its source episode and the offsets to play it from; `why.verifiable` says whether that episode still exists. `why` is absent for entries with no explanation, which is normal: a flat hold or an ordinary decline is deliberately left unexplained. Access: an API key reads every chart at full depth. A session without paid Radar access reads only the composite `all` chart, its top 10 entries with the signal operands (`signals.trend_*`, `signals.elevation_*`) omitted, and is refused the per-category charts. The composite charts (`all`, `all-entertainment`, `all-sports`) and every sports chart except `nfl`, `nba`, `mlb`, `nhl`, and `college-football` publish the 7d window only, so requesting one with `window=24h` is a 422.", "operationId": "get-entity-chart", "parameters": [ { "description": "Chart identifier from GET /v1/podcasts/entities/charts (e.g. 'all', 'tv-series', 'movies', 'video-games', 'guests', 'all-sports', 'nfl').", "in": "path", "name": "category", "required": true, "schema": { "description": "Chart identifier from GET /v1/podcasts/entities/charts (e.g. 'all', 'tv-series', 'movies', 'video-games', 'guests', 'all-sports', 'nfl').", "type": "string" } }, { "description": "Measurement window for the edition to return. The all chart publishes 7d only.", "explode": false, "in": "query", "name": "window", "schema": { "default": "7d", "description": "Measurement window for the edition to return. The all chart publishes 7d only.", "enum": [ "7d", "24h" ], "type": "string" } }, { "description": "How many ranked entries to return, from rank 1 down. Editions persist far deeper than the product surfaces, so raise this to page further into the chart. A session without paid Radar access reads the all chart 10 entries deep regardless of limit.", "explode": false, "in": "query", "name": "limit", "schema": { "default": 10, "description": "How many ranked entries to return, from rank 1 down. Editions persist far deeper than the product surfaces, so raise this to page further into the chart. A session without paid Radar access reads the all chart 10 entries deep regardless of limit.", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Response ordering. 'rank' returns the chart as published. 'acceleration' reorders the whole persisted edition by each entry's accel_multiple, fastest first, so a fast riser deep in the chart can surface; entries without a multiple or with fewer than 5 podcasts follow in rank order. Acceleration is not measured for the guests chart, so 'acceleration' returns guests in rank order.", "explode": false, "in": "query", "name": "sort", "schema": { "default": "rank", "description": "Response ordering. 'rank' returns the chart as published. 'acceleration' reorders the whole persisted edition by each entry's accel_multiple, fastest first, so a fast riser deep in the chart can surface; entries without a multiple or with fewer than 5 podcasts follow in rank order. Acceleration is not measured for the guests chart, so 'acceleration' returns guests in rank order.", "enum": [ "rank", "acceleration" ], "type": "string" } }, { "description": "Optional response sections (comma-separated). 'timeseries' adds each entry's daily podcast and mention history. 'driven_by' adds, on a derivative entry, the entry whose coverage drives it, for grouping derivative entries under what drives them.", "explode": false, "in": "query", "name": "include", "schema": { "description": "Optional response sections (comma-separated). 'timeseries' adds each entry's daily podcast and mention history. 'driven_by' adds, on a derivative entry, the entry whose coverage drives it, for grouping derivative entries under what drives them.", "items": { "enum": [ "timeseries", "driven_by" ], "type": "string" }, "type": [ "array", "null" ] } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityChart" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.10 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "Get an entity chart", "tags": [ "Entity Charts", "tier:standard" ], "x-cost-weight": 1, "x-payment-info": { "offers": [ { "amount": "100000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.100000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "standard" } }, "/v1/podcasts/episodes": { "get": { "description": "Returns a paginated list of podcast episodes across all podcasts. Filter by podcast slug or ID, entity slug or ID, company slug or domain, date range, and language.", "operationId": "list-episodes", "parameters": [ { "description": "Results per page", "explode": false, "in": "query", "name": "limit", "schema": { "default": 25, "description": "Results per page", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque pagination cursor from previous response", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque pagination cursor from previous response", "type": "string" } }, { "description": "Podcast slug (e.g., 'all-in'), internal ID, or numeric iTunes ID", "explode": false, "in": "query", "name": "podcast_id", "schema": { "description": "Podcast slug (e.g., 'all-in'), internal ID, or numeric iTunes ID", "type": "string" } }, { "description": "Entity slug (e.g., 'elon-musk', 'openai') or ID. Returns episodes featuring this entity as a speaker or mentioned entity.", "explode": false, "in": "query", "name": "entity_id", "schema": { "description": "Entity slug (e.g., 'elon-musk', 'openai') or ID. Returns episodes featuring this entity as a speaker or mentioned entity.", "type": "string" } }, { "description": "Person slug (e.g., 'dick-costolo'), knowledge-graph entity slug for the same person, or ID. Returns episodes featuring this person as a speaker — works even when the speaker has no knowledge-graph entity linked. When the value itself matches a knowledge-graph entity slug (corroborated to the same person), the default and 'mention' roles also include episodes that merely mention the person, matching entity_id semantics; pass a speaker role (guest, host, panelist, correspondent) for speaker-only results.", "explode": false, "in": "query", "name": "person_id", "schema": { "description": "Person slug (e.g., 'dick-costolo'), knowledge-graph entity slug for the same person, or ID. Returns episodes featuring this person as a speaker — works even when the speaker has no knowledge-graph entity linked. When the value itself matches a knowledge-graph entity slug (corroborated to the same person), the default and 'mention' roles also include episodes that merely mention the person, matching entity_id semantics; pass a speaker role (guest, host, panelist, correspondent) for speaker-only results.", "type": "string" } }, { "description": "Company slug (e.g., 'nvidia'), domain (e.g., 'nvidia.com'), or ID. Resolves to the company's linked entity.", "explode": false, "in": "query", "name": "company_id", "schema": { "description": "Company slug (e.g., 'nvidia'), domain (e.g., 'nvidia.com'), or ID. Resolves to the company's linked entity.", "type": "string" } }, { "description": "Entity role filter. Constrains which episodes match the entity_id, person_id, or company_id. 'speaker' matches any speaking role (host, co-host, guest, panelist, correspondent) without including mention-only episodes.", "explode": false, "in": "query", "name": "role", "schema": { "description": "Entity role filter. Constrains which episodes match the entity_id, person_id, or company_id. 'speaker' matches any speaking role (host, co-host, guest, panelist, correspondent) without including mention-only episodes.", "enum": [ "guest", "host", "panelist", "correspondent", "speaker", "mention" ], "type": "string" } }, { "description": "Only episodes published after this ISO 8601 date or date-time (e.g. 2024-01-01 or 2024-01-01T00:00:00Z)", "explode": false, "in": "query", "name": "published_after", "schema": { "description": "Only episodes published after this ISO 8601 date or date-time (e.g. 2024-01-01 or 2024-01-01T00:00:00Z)", "type": "string" } }, { "description": "Only episodes published before this ISO 8601 date or date-time (e.g. 2024-01-01 or 2024-01-01T00:00:00Z)", "explode": false, "in": "query", "name": "published_before", "schema": { "description": "Only episodes published before this ISO 8601 date or date-time (e.g. 2024-01-01 or 2024-01-01T00:00:00Z)", "type": "string" } }, { "description": "Restrict to episodes of podcasts in this language (ISO 639-1 code, e.g. 'fr'). Matches the podcast's primary language subtag, so 'fr' covers 'fr-FR'.", "explode": false, "in": "query", "name": "language", "schema": { "description": "Restrict to episodes of podcasts in this language (ISO 639-1 code, e.g. 'fr'). Matches the podcast's primary language subtag, so 'fr' covers 'fr-FR'.", "examples": [ "fr" ], "type": "string" } }, { "description": "Only episodes with completed transcripts", "explode": false, "in": "query", "name": "has_transcript", "schema": { "description": "Only episodes with completed transcripts", "type": "boolean" } }, { "description": "Filter by where episodes stand on the way to a transcript. Omitted, the list holds the episodes we have ingested, as it always has. any, untranscribed and requestable also list the podcast's back catalogue — episodes we have discovered in its feed but not transcribed — so they require podcast_id: any lists every discovered episode, untranscribed those without a transcript, requestable back-catalogue episodes whose transcript can be requested. transcribed lists episodes with a transcript, like has_transcript, which it replaces. Back-catalogue episodes carry no speakers, entities or topics, so entity_id, person_id, company_id and fully_ingested leave them out.", "explode": false, "in": "query", "name": "transcript_status", "schema": { "description": "Filter by where episodes stand on the way to a transcript. Omitted, the list holds the episodes we have ingested, as it always has. any, untranscribed and requestable also list the podcast's back catalogue — episodes we have discovered in its feed but not transcribed — so they require podcast_id: any lists every discovered episode, untranscribed those without a transcript, requestable back-catalogue episodes whose transcript can be requested. transcribed lists episodes with a transcript, like has_transcript, which it replaces. Back-catalogue episodes carry no speakers, entities or topics, so entity_id, person_id, company_id and fully_ingested leave them out.", "enum": [ "any", "transcribed", "untranscribed", "requestable" ], "type": "string" } }, { "description": "Only episodes that have reached the terminal ingestion milestone (the highest stage exposed by the episode firehose)", "explode": false, "in": "query", "name": "fully_ingested", "schema": { "description": "Only episodes that have reached the terminal ingestion milestone (the highest stage exposed by the episode firehose)", "type": "boolean" } }, { "description": "Minimum episode duration in seconds", "explode": false, "in": "query", "name": "min_duration", "schema": { "description": "Minimum episode duration in seconds", "format": "int64", "maximum": 9223372036, "minimum": 0, "type": "integer" } }, { "description": "Maximum episode duration in seconds", "explode": false, "in": "query", "name": "max_duration", "schema": { "description": "Maximum episode duration in seconds", "format": "int64", "maximum": 9223372036, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageEpisode" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.01 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "List episodes", "tags": [ "Podcast Episodes", "tier:standard" ], "x-cost-weight": 1, "x-payment-info": { "offers": [ { "amount": "10000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.010000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "standard" } }, "/v1/podcasts/episodes/archive": { "get": { "description": "Lists the months and days of the podcast episode archive, the complete history of transcribed episodes delivered as bulk files. **Available by arrangement.** Download a month or a day with `GET /v1/podcasts/episodes/archive/download`, then follow `GET /v1/podcasts/episodes/stream` from `stream_since`. To keep a copy current, list again with `updated_since` set to your previous `as_of` and download the days it returns.", "operationId": "list-episode-archive", "parameters": [ { "description": "Only list the days whose content changed after this time, to re-sync a copy you already hold. Pass the as_of of your previous sync. A listed day with 0 episodes no longer has any; remove your copy.", "explode": false, "in": "query", "name": "updated_since", "schema": { "description": "Only list the days whose content changed after this time, to re-sync a copy you already hold. Pass the as_of of your previous sync. A listed day with 0 episodes no longer has any; remove your copy.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EpisodeArchive" } } }, "description": "OK" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "summary": "List the episode archive", "tags": [ "Podcast Episodes", "tier:standard" ], "x-cost-weight": 1, "x-entitlement-priced": true, "x-episode-archive-only": true, "x-tier": "standard" } }, "/v1/podcasts/episodes/archive/download": { "get": { "description": "Downloads a month or a day of the podcast episode archive as gzip-compressed JSON Lines, one episode per line, ordered by publication time. Each line is the episode exactly as `GET /v1/podcasts/episodes/stream` delivers it with `include=all`. **Available by arrangement.** A day can be resumed with a Range request; a month cannot, so download days when your connection is unreliable. A download is a complete snapshot of its period: replace your copy rather than merging into it. Conditional requests with `If-None-Match` or `If-Modified-Since` return 304 when nothing changed, and `HEAD` returns the headers alone.", "operationId": "download-episode-archive", "parameters": [ { "description": "A month (YYYY-MM) or a day (YYYY-MM-DD), by UTC publication date.", "explode": false, "in": "query", "name": "period", "required": true, "schema": { "description": "A month (YYYY-MM) or a day (YYYY-MM-DD), by UTC publication date.", "examples": [ "2026-09" ], "pattern": "^\\d{4}-\\d{2}(-\\d{2})?$", "type": "string" } }, { "description": "Heavy relations to keep in each episode. Defaults to all of them. Narrowing it costs nothing to you but is served more slowly, and a narrowed download cannot be resumed with Range.", "explode": false, "in": "query", "name": "include", "schema": { "description": "Heavy relations to keep in each episode. Defaults to all of them. Narrowing it costs nothing to you but is served more slowly, and a narrowed download cannot be resumed with Range.", "items": { "enum": [ "transcript", "segments", "clips", "entities", "ads", "all" ], "type": "string" }, "type": [ "array", "null" ] } } ], "responses": { "200": { "content": { "application/gzip": { "schema": { "contentMediaType": "application/octet-stream", "format": "binary", "type": "string" } } }, "description": "The file." }, "206": { "content": { "application/gzip": { "schema": { "contentMediaType": "application/octet-stream", "format": "binary", "type": "string" } } }, "description": "The requested byte range of the file, answering a Range request." }, "304": { "description": "Not modified: the If-None-Match tag still matches, or, without one, the file has not changed since If-Modified-Since. No body." }, "416": { "description": "The requested range lies outside the file." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "summary": "Download the episode archive", "tags": [ "Podcast Episodes", "tier:standard" ], "x-cost-weight": 1, "x-entitlement-priced": true, "x-episode-archive-only": true, "x-tier": "standard" } }, "/v1/podcasts/episodes/archive/stream": { "get": { "description": "Replays a month or a day of the podcast episode archive as Server-Sent Events, so a consumer of `GET /v1/podcasts/episodes/stream` can load history through the same code. Each `episode` event carries the episode exactly as the stream delivers it, in publication order, and a `complete` event closes a full replay. Resume a dropped connection with `cursor`. **Available by arrangement.** For bulk loading, the download endpoint is several times faster.", "operationId": "stream-episode-archive", "parameters": [ { "description": "A month (YYYY-MM) or a day (YYYY-MM-DD), by UTC publication date.", "explode": false, "in": "query", "name": "period", "required": true, "schema": { "description": "A month (YYYY-MM) or a day (YYYY-MM-DD), by UTC publication date.", "examples": [ "2026-09" ], "pattern": "^\\d{4}-\\d{2}(-\\d{2})?$", "type": "string" } }, { "description": "Heavy relations to keep in each episode. Defaults to all of them.", "explode": false, "in": "query", "name": "include", "schema": { "description": "Heavy relations to keep in each episode. Defaults to all of them.", "items": { "enum": [ "transcript", "segments", "clips", "entities", "ads", "all" ], "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Resume after this event: pass the cursor of the last episode you processed. If the period was rebuilt since, the replay answers with an error event; start it again without a cursor.", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Resume after this event: pass the cursor of the last episode you processed. If the period was rebuilt since, the replay answers with an error event; start it again without a cursor.", "type": "string" } } ], "responses": { "200": { "content": { "text/event-stream": { "schema": { "description": "Each oneOf object in the array represents one possible Server Sent Events (SSE) message, serialized as UTF-8 text according to the SSE specification.", "items": { "oneOf": [ { "properties": { "data": { "$ref": "#/components/schemas/EpisodeArchiveComplete" }, "event": { "const": "complete", "description": "The event name.", "type": "string" }, "id": { "description": "The event ID.", "type": "integer" }, "retry": { "description": "The retry time in milliseconds.", "type": "integer" } }, "required": [ "data", "event" ], "title": "Event complete", "type": "object" }, { "properties": { "data": { "properties": { "cursor": { "description": "Pass as cursor= to resume after this episode.", "type": "string" }, "episode": { "$ref": "#/components/schemas/Episode" } }, "required": [ "cursor", "episode" ], "type": "object" }, "event": { "const": "episode", "description": "The event name.", "type": "string" }, "id": { "description": "The event ID.", "type": "integer" }, "retry": { "description": "The retry time in milliseconds.", "type": "integer" } }, "required": [ "data", "event" ], "title": "Event episode", "type": "object" }, { "properties": { "data": { "$ref": "#/components/schemas/StreamError" }, "event": { "const": "error", "description": "The event name.", "type": "string" }, "id": { "description": "The event ID.", "type": "integer" }, "retry": { "description": "The retry time in milliseconds.", "type": "integer" } }, "required": [ "data", "event" ], "title": "Event error", "type": "object" } ] }, "title": "Server Sent Events", "type": "array" } } }, "description": "OK" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "summary": "Replay the episode archive", "tags": [ "Podcast Episodes", "tier:standard" ], "x-cost-weight": 1, "x-entitlement-priced": true, "x-episode-archive-only": true, "x-tier": "standard" } }, "/v1/podcasts/episodes/feed": { "get": { "description": "Resumable, strictly-ordered poll of episodes as they are ingested — the all-plans pull alternative to the Enterprise stream. Subscribe to a milestone (default transcribed); each call returns episodes that reached it since your cursor, in ingestion order, with a cursor to poll again. Filter by podcast_ids, topic_ids, and/or popularity_threshold — a filter is required, and coverage is capped at 100 podcasts. Enterprise organizations are exempt: they may poll unfiltered (the pull form of the stream) and popularity_threshold applies uncapped.", "operationId": "feed-episodes", "parameters": [ { "description": "Deliver episodes once they reach this ingestion stage. Ordered discovered \u003c transcribed \u003c segmented \u003c fully_ingested.", "explode": false, "in": "query", "name": "milestone", "schema": { "default": "transcribed", "description": "Deliver episodes once they reach this ingestion stage. Ordered discovered \u003c transcribed \u003c segmented \u003c fully_ingested.", "enum": [ "discovered", "transcribed", "segmented", "fully_ingested" ], "type": "string" } }, { "description": "Filter to a set of podcasts by slug or ID (comma-separated). Hard limit of 100 per request. Unknown values are ignored; if no filter matches any podcast you get a 404. Always included over popularity_threshold.", "explode": false, "in": "query", "name": "podcast_ids", "schema": { "description": "Filter to a set of podcasts by slug or ID (comma-separated). Hard limit of 100 per request. Unknown values are ignored; if no filter matches any podcast you get a 404. Always included over popularity_threshold.", "items": { "type": "string" }, "maxItems": 100, "type": [ "array", "null" ] } }, { "description": "Filter to the most-popular podcasts whose popularity percentile is at least this value, in (0,1). Omit (or 0) for no popularity filter. The feed covers at most 100 podcasts total: your podcast_ids plus the most-popular podcasts above this threshold, with the least-popular trimmed to fit. Enterprise organizations are exempt from the cap when topic_ids is omitted — the threshold applies to every qualifying podcast, and they may also poll with no filter at all. Requests with topic_ids remain capped at 100 podcasts on every plan.", "explode": false, "in": "query", "name": "popularity_threshold", "schema": { "description": "Filter to the most-popular podcasts whose popularity percentile is at least this value, in (0,1). Omit (or 0) for no popularity filter. The feed covers at most 100 podcasts total: your podcast_ids plus the most-popular podcasts above this threshold, with the least-popular trimmed to fit. Enterprise organizations are exempt from the cap when topic_ids is omitted — the threshold applies to every qualifying podcast, and they may also poll with no filter at all. Requests with topic_ids remain capped at 100 podcasts on every plan.", "exclusiveMaximum": 1, "format": "double", "minimum": 0, "type": "number" } }, { "description": "Scope the feed to one or more topics (comma-separated): each a topic slug path (e.g. sports/football/fantasy-football), ID, or ancestry-path hash. A topic also matches its descendants, and multiple topics are unioned. Only podcasts that regularly cover the topic are included — a show that merely mentions it in passing is excluded. The feed still covers at most 100 podcasts total, so combine with popularity_threshold to keep just the most popular. An unknown topic returns a 404.", "explode": false, "in": "query", "name": "topic_ids", "schema": { "description": "Scope the feed to one or more topics (comma-separated): each a topic slug path (e.g. sports/football/fantasy-football), ID, or ancestry-path hash. A topic also matches its descendants, and multiple topics are unioned. Only podcasts that regularly cover the topic are included — a show that merely mentions it in passing is excluded. The feed still covers at most 100 podcasts total, so combine with popularity_threshold to keep just the most popular. An unknown topic returns a 404.", "items": { "type": "string" }, "maxItems": 20, "type": [ "array", "null" ] } }, { "description": "Opaque cursor from a prior feed response. Poll again with it to receive episodes ingested since. Omit (with no since) to start from now.", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque cursor from a prior feed response. Poll again with it to receive episodes ingested since. Omit (with no since) to start from now.", "type": "string" } }, { "description": "ISO 8601 date or date-time to start from when no cursor is supplied. Ignored if cursor is set.", "explode": false, "in": "query", "name": "since", "schema": { "description": "ISO 8601 date or date-time to start from when no cursor is supplied. Ignored if cursor is set.", "type": "string" } }, { "description": "Maximum episodes per page.", "explode": false, "in": "query", "name": "limit", "schema": { "default": 25, "description": "Maximum episodes per page.", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Heavy relations to embed in each episode (comma-separated). transcript is the dialogue transcript; segments and clips are the AI-derived sets; entities are the knowledge graph entities discussed, with the transcript lines that mention each; ads are the advertising spots detected; all means everything available at the chosen milestone. A field is only valid when its data is guaranteed at the milestone (transcript→transcribed, segments→segmented, clips, entities and ads→fully_ingested); requesting one earlier is a 422.", "explode": false, "in": "query", "name": "include", "schema": { "description": "Heavy relations to embed in each episode (comma-separated). transcript is the dialogue transcript; segments and clips are the AI-derived sets; entities are the knowledge graph entities discussed, with the transcript lines that mention each; ads are the advertising spots detected; all means everything available at the chosen milestone. A field is only valid when its data is guaranteed at the milestone (transcript→transcribed, segments→segmented, clips, entities and ads→fully_ingested); requesting one earlier is a 422.", "items": { "enum": [ "transcript", "segments", "clips", "entities", "ads", "all" ], "type": "string" }, "type": [ "array", "null" ] } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageEpisode" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.01 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "Poll the episode feed", "tags": [ "Podcast Episodes", "tier:standard" ], "x-cost-weight": 1, "x-payment-info": { "offers": [ { "amount": "10000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.010000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "standard" } }, "/v1/podcasts/episodes/lookup": { "get": { "description": "Resolves one or more external episode identifiers to Particle episodes. Eight kinds are accepted. Platform IDs: Apple Podcasts episode IDs (the `?i=` value in an Apple Podcasts URL) and YouTube video IDs. Feed and index IDs: the episode's RSS `guid` — the identifier the publisher's own feed carries, and the one most podcast tooling keys on — and a `podcastindex` episode ID. Hosting-platform IDs, read from the episode's audio URL: `megaphone`, `omny`, `acast` and `art19`. Pass `platform` once and a comma-separated list of identifiers (up to 100 per call). A full platform URL is accepted in place of a bare ID and the identifier is parsed out of it — an Apple Podcasts episode URL, or a YouTube watch, youtu.be, /live/, /shorts/ or /embed/ URL. Guids and hosting-platform IDs are matched exactly as supplied and never parsed, since a guid is whatever string the feed carries and is often itself a URL. Because identifiers are comma-separated, a guid that itself contains a comma cannot be expressed here — about 1.2% of episodes, almost all of them SoundCloud-hosted, whose guids take the form `tag:soundcloud,2010:tracks/123`; look those episodes up by another identifier. Each result echoes the input identifier alongside the matched episode and its podcast; unresolved identifiers omit the `episode` field entirely so bulk callers can correlate inputs and outputs by key presence without doing a separate join. This is the episode-level counterpart to GET /v1/podcasts/lookup. Coverage is partial and differs by identifier, so a miss is not an error: Apple exposes only the most recent episodes of each show, so older back-catalogue episodes may not resolve; YouTube resolves any video already discovered for an episode; `guid` is the broadest at roughly 89% of episodes; and a hosting-platform ID resolves only for episodes served by that host.", "operationId": "lookup-episodes", "parameters": [ { "description": "What kind of identifier you are resolving. 'apple' (alias 'itunes') resolves Apple Podcasts episode IDs — the ?i= value in an Apple Podcasts URL. 'youtube' resolves YouTube video IDs against the videos discovered for each episode. 'guid' resolves the episode's RSS guid, the identifier carried in the publisher's own feed and the one most podcast tooling keys on. 'podcastindex' resolves a PodcastIndex episode ID. 'megaphone', 'omny', 'acast' and 'art19' resolve a hosting platform's own episode ID, read from the episode's audio URL. Platform slugs must be ones reported on external-links responses; 'rss' is not accepted here because a feed URL identifies a show, not an episode.", "explode": false, "in": "query", "name": "platform", "required": true, "schema": { "description": "What kind of identifier you are resolving. 'apple' (alias 'itunes') resolves Apple Podcasts episode IDs — the ?i= value in an Apple Podcasts URL. 'youtube' resolves YouTube video IDs against the videos discovered for each episode. 'guid' resolves the episode's RSS guid, the identifier carried in the publisher's own feed and the one most podcast tooling keys on. 'podcastindex' resolves a PodcastIndex episode ID. 'megaphone', 'omny', 'acast' and 'art19' resolve a hosting platform's own episode ID, read from the episode's audio URL. Platform slugs must be ones reported on external-links responses; 'rss' is not accepted here because a feed URL identifies a show, not an episode.", "examples": [ "apple" ], "type": "string" } }, { "description": "One or more episode identifiers to resolve. Pass a comma-separated list to look up many at once (max 100 per call). A full platform URL is accepted in place of a bare identifier and the ID is parsed out of it: for apple/itunes an Apple Podcasts episode URL (the ?i= value); for youtube a watch?v=, youtu.be/, /live/, /shorts/ or /embed/ URL. guid, podcastindex and hosting-platform values are used as given — a guid is whatever string the feed carries, which is often itself a URL, so it is never parsed. The identifier is echoed back exactly as supplied, not normalized.", "explode": false, "in": "query", "name": "identifier", "required": true, "schema": { "description": "One or more episode identifiers to resolve. Pass a comma-separated list to look up many at once (max 100 per call). A full platform URL is accepted in place of a bare identifier and the ID is parsed out of it: for apple/itunes an Apple Podcasts episode URL (the ?i= value); for youtube a watch?v=, youtu.be/, /live/, /shorts/ or /embed/ URL. guid, podcastindex and hosting-platform values are used as given — a guid is whatever string the feed carries, which is often itself a URL, so it is never parsed. The identifier is echoed back exactly as supplied, not normalized.", "examples": [ [ "1000785846210", "1000786587166" ] ], "items": { "type": "string" }, "maxItems": 100, "minItems": 1, "type": [ "array", "null" ] } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EpisodeLookup" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.01 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "Look up episodes by external identifier", "tags": [ "Podcast Episodes", "tier:standard" ], "x-cost-weight": 1, "x-payment-info": { "offers": [ { "amount": "10000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.010000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "standard" } }, "/v1/podcasts/episodes/search": { "get": { "description": "To find podcasts (shows) by name or topic, use `/v1/podcasts/search?q=…`. This endpoint searches *inside* episode dialogue — by meaning (`semantic_search`), by exact phrase (`keyword_search`), or both at once (hybrid). Each result is a segment of an episode, returned with bounded preview windows of dialogue and any highlight clips that overlap the segment.\n\nFor \"every line about a person or company\" use `/v1/podcasts/mentions` instead — that endpoint returns episode-grouped mention windows with line-level highlights and is shaped for the read-everything-about-X use case. `entity_id` and `company_id` here narrow the result set to episodes featuring the resolved entity, but the ranking still comes from `semantic_search` / `keyword_search`.", "operationId": "search-episodes", "parameters": [ { "description": "Vector-similarity search by meaning. Express the query the way you'd describe the topic to a colleague — paraphrase tolerant, finds segments that express the same idea in different vocabulary. Combine with keyword_search for hybrid ranking. Describe a topic, not a name: to find a specific person or company, filter with entity_id / company_id (or use /v1/podcasts/mentions for every line about them) — and for an exact token like a ticker, use keyword_search.", "explode": false, "in": "query", "name": "semantic_search", "schema": { "description": "Vector-similarity search by meaning. Express the query the way you'd describe the topic to a colleague — paraphrase tolerant, finds segments that express the same idea in different vocabulary. Combine with keyword_search for hybrid ranking. Describe a topic, not a name: to find a specific person or company, filter with entity_id / company_id (or use /v1/podcasts/mentions for every line about them) — and for an exact token like a ticker, use keyword_search.", "maxLength": 500, "type": "string" } }, { "description": "BM25 lexical search over dialogue. Use when an exact token must appear verbatim — tickers, drug names, product codes. By default every token must appear somewhere in the matched segment (see keyword_match). Wrap any token sequence in double quotes (e.g. \"machine learning\") to additionally require those words adjacent and in order in the segment's spoken dialogue — a speaker's own name is not indexed as dialogue, so quoting a person's name finds segments where the name appears in what was said, not segments they speak in. Adjacency spans consecutive lines, so a phrase may rarely straddle a line break. Multiple quoted phrases AND together (e.g. \"central bank\" \"interest rates\"). There is no boolean OR — a bare OR is treated as an ordinary word, so pass alternatives as separate requests.", "explode": false, "in": "query", "name": "keyword_search", "schema": { "description": "BM25 lexical search over dialogue. Use when an exact token must appear verbatim — tickers, drug names, product codes. By default every token must appear somewhere in the matched segment (see keyword_match). Wrap any token sequence in double quotes (e.g. \"machine learning\") to additionally require those words adjacent and in order in the segment's spoken dialogue — a speaker's own name is not indexed as dialogue, so quoting a person's name finds segments where the name appears in what was said, not segments they speak in. Adjacency spans consecutive lines, so a phrase may rarely straddle a line break. Multiple quoted phrases AND together (e.g. \"central bank\" \"interest rates\"). There is no boolean OR — a bare OR is treated as an ordinary word, so pass alternatives as separate requests.", "maxLength": 500, "type": "string" } }, { "description": "How unquoted keyword_search terms are applied. 'required' (default) filters to segments containing every term, so results are guaranteed to contain what you typed — this also constrains semantic_search, making a hybrid query an intersection of the two. 'ranked' instead lets unquoted terms only boost BM25 relevance without excluding anything, which widens recall for loose bag-of-words queries but returns segments that may contain none of them. Quoted phrases are unaffected: they filter in BOTH modes, so to relax a phrase remove its quotes. Ignored when keyword_search is empty.", "explode": false, "in": "query", "name": "keyword_match", "schema": { "default": "required", "description": "How unquoted keyword_search terms are applied. 'required' (default) filters to segments containing every term, so results are guaranteed to contain what you typed — this also constrains semantic_search, making a hybrid query an intersection of the two. 'ranked' instead lets unquoted terms only boost BM25 relevance without excluding anything, which widens recall for loose bag-of-words queries but returns segments that may contain none of them. Quoted phrases are unaffected: they filter in BOTH modes, so to relax a phrase remove its quotes. Ignored when keyword_search is empty.", "enum": [ "required", "ranked" ], "type": "string" } }, { "description": "Optional entity slug or ID. Filters results to episodes featuring this entity. For 'every line about X', use /v1/podcasts/mentions instead.", "explode": false, "in": "query", "name": "entity_id", "schema": { "description": "Optional entity slug or ID. Filters results to episodes featuring this entity. For 'every line about X', use /v1/podcasts/mentions instead.", "type": "string" } }, { "description": "Optional entity category slug. Filters to episodes that *mention* any entity in that category (e.g. 'company', 'school', 'book'). Speakers are always people, so this filter only narrows mentioned entities. Cannot be combined with 'role'. Ignored when entity_id resolves to a specific entity. See GET /v1/entities/types for the available slugs.", "explode": false, "in": "query", "name": "entity_type", "schema": { "description": "Optional entity category slug. Filters to episodes that *mention* any entity in that category (e.g. 'company', 'school', 'book'). Speakers are always people, so this filter only narrows mentioned entities. Cannot be combined with 'role'. Ignored when entity_id resolves to a specific entity. See GET /v1/entities/types for the available slugs.", "type": "string" } }, { "description": "Optional company slug, domain, or ID. Resolves to the company's linked entity and applies as a filter.", "explode": false, "in": "query", "name": "company_id", "schema": { "description": "Optional company slug, domain, or ID. Resolves to the company's linked entity and applies as a filter.", "type": "string" } }, { "description": "Filter to a specific episode by slug or ID.", "explode": false, "in": "query", "name": "episode_id", "schema": { "description": "Filter to a specific episode by slug or ID.", "type": "string" } }, { "description": "Podcast slug, internal ID, or numeric iTunes ID.", "explode": false, "in": "query", "name": "podcast_id", "schema": { "description": "Podcast slug, internal ID, or numeric iTunes ID.", "type": "string" } }, { "description": "Segment type filter.", "explode": false, "in": "query", "name": "type", "schema": { "description": "Segment type filter.", "enum": [ "INTRO", "PERSONAL_BANTER", "TOPIC_DISCUSSION", "INTERVIEW", "TRANSITION", "AD", "OUTRO" ], "type": "string" } }, { "description": "How the entity must relate to the episode. Speaking roles: 'guest', 'host', 'panelist', 'correspondent', or 'speaker' for any of them. 'mention' means the entity is talked about rather than speaking. Omit to match both. Matches the role values on /v1/podcasts/episodes.", "explode": false, "in": "query", "name": "role", "schema": { "description": "How the entity must relate to the episode. Speaking roles: 'guest', 'host', 'panelist', 'correspondent', or 'speaker' for any of them. 'mention' means the entity is talked about rather than speaking. Omit to match both. Matches the role values on /v1/podcasts/episodes.", "enum": [ "guest", "host", "panelist", "correspondent", "speaker", "mention" ], "type": "string" } }, { "description": "Restrict to episodes of podcasts in this language (ISO 639-1 code, e.g. 'fr'). Matches the podcast's primary language subtag, so 'fr' covers 'fr-FR'.", "explode": false, "in": "query", "name": "language", "schema": { "description": "Restrict to episodes of podcasts in this language (ISO 639-1 code, e.g. 'fr'). Matches the podcast's primary language subtag, so 'fr' covers 'fr-FR'.", "examples": [ "fr" ], "type": "string" } }, { "description": "Only segments from episodes published after this date.", "explode": false, "in": "query", "name": "since", "schema": { "description": "Only segments from episodes published after this date.", "examples": [ "2024-01-01" ], "type": "string" } }, { "description": "Only segments from episodes published on or before this date. A bare date includes that whole day.", "explode": false, "in": "query", "name": "until", "schema": { "description": "Only segments from episodes published on or before this date. A bare date includes that whole day.", "examples": [ "2024-06-01" ], "type": "string" } }, { "description": "Sort order. Defaults to relevance.", "explode": false, "in": "query", "name": "sort", "schema": { "description": "Sort order. Defaults to relevance.", "enum": [ "relevance", "recency" ], "type": "string" } }, { "description": "Response shape. 'full' (default) carries each match's bounded dialogue windows and overlapping clips. 'compact' omits windows and clips and skips the transcript load and line scoring that produce them, so the page is a fraction of the size and returns sooner: each match keeps its episode, its segment (id, title, description, summary, bounds) and its relevance score. Use it to screen many results — a fan-out over companies, themes, or dates — and fetch dialogue only for the matches that survive, via GET /v1/podcasts/segments/{id}/transcript or a full-format search narrowed with episode_id.", "explode": false, "in": "query", "name": "format", "schema": { "default": "full", "description": "Response shape. 'full' (default) carries each match's bounded dialogue windows and overlapping clips. 'compact' omits windows and clips and skips the transcript load and line scoring that produce them, so the page is a fraction of the size and returns sooner: each match keeps its episode, its segment (id, title, description, summary, bounds) and its relevance score. Use it to screen many results — a fan-out over companies, themes, or dates — and fetch dialogue only for the matches that survive, via GET /v1/podcasts/segments/{id}/transcript or a full-format search narrowed with episode_id.", "enum": [ "full", "compact" ], "type": "string" } }, { "description": "Lines of surrounding dialogue around each matched line (1-15, default 1). Widens each match's transcript window in place — request more context instead of fetching the full transcript. Window size stays bounded even at the maximum. Ignored when format=compact.", "explode": false, "in": "query", "name": "context", "schema": { "default": 1, "description": "Lines of surrounding dialogue around each matched line (1-15, default 1). Widens each match's transcript window in place — request more context instead of fetching the full transcript. Window size stays bounded even at the maximum. Ignored when format=compact.", "format": "int64", "maximum": 15, "minimum": 1, "type": "integer" } }, { "description": "Results per page (1-100, default 25).", "explode": false, "in": "query", "name": "limit", "schema": { "default": 25, "description": "Results per page (1-100, default 25).", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque cursor from a previous response.", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque cursor from a previous response.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastSearchPage" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.03 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "Search podcast episode content", "tags": [ "Podcast Episode Search", "tier:standard" ], "x-cost-weight": 1, "x-payment-info": { "offers": [ { "amount": "30000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.030000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "standard" } }, "/v1/podcasts/episodes/stream": { "get": { "description": "Server-Sent Events stream of podcast episodes as they are ingested. **Enterprise plan only** — other plans should poll `GET /v1/podcasts/episodes/feed` instead. Subscribe to a single hydration `milestone` (default `transcribed`); each episode is delivered once it reaches that stage. Optionally filter by `podcast_ids` (slug or ID) and/or `popularity_threshold`. Supply `cursor` or `since` to backfill, then the stream continues live. Delivery is at-least-once — dedupe on the episode id. For more than 100 explicit podcast ids, use the POST form.", "operationId": "stream-episodes", "parameters": [ { "description": "Hydration milestone to stream. Episodes are delivered once they reach this stage. Milestones are ordered discovered \u003c transcribed \u003c segmented \u003c fully_ingested.", "explode": false, "in": "query", "name": "milestone", "schema": { "default": "transcribed", "description": "Hydration milestone to stream. Episodes are delivered once they reach this stage. Milestones are ordered discovered \u003c transcribed \u003c segmented \u003c fully_ingested.", "enum": [ "discovered", "transcribed", "segmented", "fully_ingested" ], "type": "string" } }, { "description": "Filter to a set of podcasts by slug or ID (comma-separated). An episode is delivered if its podcast matches any of them. Unknown values are ignored; if none match you receive a terminal error. For more than 100, use the POST form.", "explode": false, "in": "query", "name": "podcast_ids", "schema": { "description": "Filter to a set of podcasts by slug or ID (comma-separated). An episode is delivered if its podcast matches any of them. Unknown values are ignored; if none match you receive a terminal error. For more than 100, use the POST form.", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Filter to podcasts whose popularity percentile is at least this value, in (0,1). Omit (or 0) for no popularity filter. Popularity is normalized 0–1 across the catalog, so 0.9 ≈ the top 10%. Combines with podcast_ids as a union.", "explode": false, "in": "query", "name": "popularity_threshold", "schema": { "description": "Filter to podcasts whose popularity percentile is at least this value, in (0,1). Omit (or 0) for no popularity filter. Popularity is normalized 0–1 across the catalog, so 0.9 ≈ the top 10%. Combines with podcast_ids as a union.", "exclusiveMaximum": 1, "format": "double", "minimum": 0, "type": "number" } }, { "description": "Opaque cursor from a prior event envelope. When supplied, the stream replays everything after it then continues live.", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque cursor from a prior event envelope. When supplied, the stream replays everything after it then continues live.", "type": "string" } }, { "description": "ISO 8601 date or date-time to backfill from when no cursor is supplied. Ignored if cursor is set.", "explode": false, "in": "query", "name": "since", "schema": { "description": "ISO 8601 date or date-time to backfill from when no cursor is supplied. Ignored if cursor is set.", "type": "string" } }, { "description": "Heavy relations to embed in each episode (comma-separated). transcript is the dialogue transcript; segments and clips are the AI-derived sets; entities are the knowledge graph entities discussed, with the transcript lines that mention each; ads are the advertising spots detected; all means everything available at the chosen milestone. A field is only valid when its data is guaranteed at the milestone (transcript→transcribed, segments→segmented, clips, entities and ads→fully_ingested); requesting one earlier is a terminal error.", "explode": false, "in": "query", "name": "include", "schema": { "description": "Heavy relations to embed in each episode (comma-separated). transcript is the dialogue transcript; segments and clips are the AI-derived sets; entities are the knowledge graph entities discussed, with the transcript lines that mention each; ads are the advertising spots detected; all means everything available at the chosen milestone. A field is only valid when its data is guaranteed at the milestone (transcript→transcribed, segments→segmented, clips, entities and ads→fully_ingested); requesting one earlier is a terminal error.", "items": { "enum": [ "transcript", "segments", "clips", "entities", "ads", "all" ], "type": "string" }, "type": [ "array", "null" ] } } ], "responses": { "200": { "content": { "text/event-stream": { "schema": { "description": "Each oneOf object in the array represents one possible Server Sent Events (SSE) message, serialized as UTF-8 text according to the SSE specification.", "items": { "oneOf": [ { "properties": { "data": { "$ref": "#/components/schemas/EpisodeStreamEvent" }, "event": { "const": "episode", "description": "The event name.", "type": "string" }, "id": { "description": "The event ID.", "type": "integer" }, "retry": { "description": "The retry time in milliseconds.", "type": "integer" } }, "required": [ "data", "event" ], "title": "Event episode", "type": "object" }, { "properties": { "data": { "$ref": "#/components/schemas/StreamError" }, "event": { "const": "error", "description": "The event name.", "type": "string" }, "id": { "description": "The event ID.", "type": "integer" }, "retry": { "description": "The retry time in milliseconds.", "type": "integer" } }, "required": [ "data", "event" ], "title": "Event error", "type": "object" } ] }, "title": "Server Sent Events", "type": "array" } } }, "description": "OK" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "summary": "Stream episodes", "tags": [ "Podcast Episodes", "tier:standard" ], "x-cost-weight": 1, "x-enterprise-only": true, "x-entitlement-priced": true, "x-tier": "standard" }, "post": { "description": "Identical to the GET form (**Enterprise plan only**), but accepts the podcast filter in a JSON body so you can pass a large `podcast_ids` set (up to 1000) without hitting query-string limits. The `milestone`, `cursor`, and `since` controls remain query parameters.", "operationId": "stream-episodes-post", "parameters": [ { "description": "Hydration milestone to stream. Episodes are delivered once they reach this stage. Milestones are ordered discovered \u003c transcribed \u003c segmented \u003c fully_ingested.", "explode": false, "in": "query", "name": "milestone", "schema": { "default": "transcribed", "description": "Hydration milestone to stream. Episodes are delivered once they reach this stage. Milestones are ordered discovered \u003c transcribed \u003c segmented \u003c fully_ingested.", "enum": [ "discovered", "transcribed", "segmented", "fully_ingested" ], "type": "string" } }, { "description": "Opaque cursor from a prior event envelope. When supplied, the stream replays everything after it then continues live.", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque cursor from a prior event envelope. When supplied, the stream replays everything after it then continues live.", "type": "string" } }, { "description": "ISO 8601 date or date-time to backfill from when no cursor is supplied. Ignored if cursor is set.", "explode": false, "in": "query", "name": "since", "schema": { "description": "ISO 8601 date or date-time to backfill from when no cursor is supplied. Ignored if cursor is set.", "type": "string" } }, { "description": "Heavy relations to embed in each episode (comma-separated). transcript is the dialogue transcript; segments and clips are the AI-derived sets; entities are the knowledge graph entities discussed, with the transcript lines that mention each; ads are the advertising spots detected; all means everything available at the chosen milestone. A field is only valid when its data is guaranteed at the milestone (transcript→transcribed, segments→segmented, clips, entities and ads→fully_ingested); requesting one earlier is a terminal error.", "explode": false, "in": "query", "name": "include", "schema": { "description": "Heavy relations to embed in each episode (comma-separated). transcript is the dialogue transcript; segments and clips are the AI-derived sets; entities are the knowledge graph entities discussed, with the transcript lines that mention each; ads are the advertising spots detected; all means everything available at the chosen milestone. A field is only valid when its data is guaranteed at the milestone (transcript→transcribed, segments→segmented, clips, entities and ads→fully_ingested); requesting one earlier is a terminal error.", "items": { "enum": [ "transcript", "segments", "clips", "entities", "ads", "all" ], "type": "string" }, "type": [ "array", "null" ] } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StreamEpisodesPostRequestBody" } } }, "required": true }, "responses": { "200": { "content": { "text/event-stream": { "schema": { "description": "Each oneOf object in the array represents one possible Server Sent Events (SSE) message, serialized as UTF-8 text according to the SSE specification.", "items": { "oneOf": [ { "properties": { "data": { "$ref": "#/components/schemas/EpisodeStreamEvent" }, "event": { "const": "episode", "description": "The event name.", "type": "string" }, "id": { "description": "The event ID.", "type": "integer" }, "retry": { "description": "The retry time in milliseconds.", "type": "integer" } }, "required": [ "data", "event" ], "title": "Event episode", "type": "object" }, { "properties": { "data": { "$ref": "#/components/schemas/StreamError" }, "event": { "const": "error", "description": "The event name.", "type": "string" }, "id": { "description": "The event ID.", "type": "integer" }, "retry": { "description": "The retry time in milliseconds.", "type": "integer" } }, "required": [ "data", "event" ], "title": "Event error", "type": "object" } ] }, "title": "Server Sent Events", "type": "array" } } }, "description": "OK" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "summary": "Stream episodes (POST)", "tags": [ "Podcast Episodes", "tier:standard" ], "x-cost-weight": 1, "x-enterprise-only": true, "x-entitlement-priced": true, "x-tier": "standard" } }, "/v1/podcasts/episodes/timeseries": { "get": { "description": "Returns time-bucketed counts of episodes matching the same filters as GET /v1/podcasts/episodes, plus range totals. Use it for appearance, publication, or topic trend charts instead of paging the episode list or search once per period. keyword_search counts episodes whose transcripts match (exact counts, no pagination floors) and adds per-bucket mention_count plus total_mentions; semantic_search does the same by meaning, using the search endpoint's similarity threshold, and requires published_after. The two cannot be combined. Buckets are UTC-aligned, zero-filled, and Monday-aligned for weeks. A published_after or published_before inside a bucket produces a partial first or last bucket labeled with the full bucket's start date. Requires at least one of entity_id, person_id, company_id, podcast_id, keyword_search, or semantic_search. Omitting published_after aggregates all time, except with semantic_search, which always requires it. Ranges are capped at 1000 buckets.", "operationId": "episode-timeseries", "parameters": [ { "description": "Podcast slug (e.g., 'all-in'), internal ID, or numeric iTunes ID", "explode": false, "in": "query", "name": "podcast_id", "schema": { "description": "Podcast slug (e.g., 'all-in'), internal ID, or numeric iTunes ID", "type": "string" } }, { "description": "Entity slug (e.g., 'elon-musk', 'openai') or ID. Counts episodes featuring this entity as a speaker or mentioned entity.", "explode": false, "in": "query", "name": "entity_id", "schema": { "description": "Entity slug (e.g., 'elon-musk', 'openai') or ID. Counts episodes featuring this entity as a speaker or mentioned entity.", "type": "string" } }, { "description": "Person slug (e.g., 'dick-costolo'), knowledge-graph entity slug for the same person, or ID. Counts episodes featuring this person as a speaker. Works even when the speaker has no knowledge-graph entity linked. When the value itself matches a knowledge-graph entity slug (corroborated to the same person), the default and 'mention' roles also count episodes that merely mention the person, matching entity_id semantics; pass a speaker role (guest, host, panelist, correspondent) for speaker-only counts.", "explode": false, "in": "query", "name": "person_id", "schema": { "description": "Person slug (e.g., 'dick-costolo'), knowledge-graph entity slug for the same person, or ID. Counts episodes featuring this person as a speaker. Works even when the speaker has no knowledge-graph entity linked. When the value itself matches a knowledge-graph entity slug (corroborated to the same person), the default and 'mention' roles also count episodes that merely mention the person, matching entity_id semantics; pass a speaker role (guest, host, panelist, correspondent) for speaker-only counts.", "type": "string" } }, { "description": "Company slug (e.g., 'nvidia'), domain (e.g., 'nvidia.com'), or ID. Resolves to the company's linked entity.", "explode": false, "in": "query", "name": "company_id", "schema": { "description": "Company slug (e.g., 'nvidia'), domain (e.g., 'nvidia.com'), or ID. Resolves to the company's linked entity.", "type": "string" } }, { "description": "Entity role filter. Constrains which episodes match the entity_id, person_id, or company_id. 'speaker' matches any speaking role (host, co-host, guest, panelist, correspondent) without including mention-only episodes.", "explode": false, "in": "query", "name": "role", "schema": { "description": "Entity role filter. Constrains which episodes match the entity_id, person_id, or company_id. 'speaker' matches any speaking role (host, co-host, guest, panelist, correspondent) without including mention-only episodes.", "enum": [ "guest", "host", "panelist", "correspondent", "speaker", "mention" ], "type": "string" } }, { "description": "Keyword filter over episode transcript content. Double-quoted substrings must appear as exact phrases; unquoted terms must all appear in a transcript segment. Counts episodes with at least one matching segment and adds mention_count fields to the response. Combines with the other filters, but not with semantic_search.", "explode": false, "in": "query", "name": "keyword_search", "schema": { "description": "Keyword filter over episode transcript content. Double-quoted substrings must appear as exact phrases; unquoted terms must all appear in a transcript segment. Counts episodes with at least one matching segment and adds mention_count fields to the response. Combines with the other filters, but not with semantic_search.", "maxLength": 500, "type": "string" } }, { "description": "Vector-similarity filter by meaning over episode transcript content — the counting twin of the search endpoint's semantic_search, using the same similarity threshold. Express the query the way you'd describe the topic to a colleague; paraphrase tolerant. Counts episodes with at least one semantically matching segment and adds mention_count fields to the response; for pathologically broad queries the mention counts can be lower bounds. Requires published_after (ranges up to ~2 years). Combines with the other filters, but not with keyword_search.", "explode": false, "in": "query", "name": "semantic_search", "schema": { "description": "Vector-similarity filter by meaning over episode transcript content — the counting twin of the search endpoint's semantic_search, using the same similarity threshold. Express the query the way you'd describe the topic to a colleague; paraphrase tolerant. Counts episodes with at least one semantically matching segment and adds mention_count fields to the response; for pathologically broad queries the mention counts can be lower bounds. Requires published_after (ranges up to ~2 years). Combines with the other filters, but not with keyword_search.", "maxLength": 500, "type": "string" } }, { "description": "Inclusive start of the range as an ISO 8601 date or date-time. Omit for all time.", "explode": false, "in": "query", "name": "published_after", "schema": { "description": "Inclusive start of the range as an ISO 8601 date or date-time. Omit for all time.", "type": "string" } }, { "description": "End of the range as an ISO 8601 date or date-time. A bare date includes that whole day. Defaults to now.", "explode": false, "in": "query", "name": "published_before", "schema": { "description": "End of the range as an ISO 8601 date or date-time. A bare date includes that whole day. Defaults to now.", "type": "string" } }, { "description": "Bucket width. Weeks start on Monday and all buckets are UTC-aligned.", "explode": false, "in": "query", "name": "interval", "schema": { "default": "week", "description": "Bucket width. Weeks start on Monday and all buckets are UTC-aligned.", "enum": [ "day", "week", "month" ], "type": "string" } }, { "description": "Restrict to episodes of podcasts in this language (ISO 639-1 code, e.g. 'fr'). Matches the podcast's primary language subtag, so 'fr' covers 'fr-FR'.", "explode": false, "in": "query", "name": "language", "schema": { "description": "Restrict to episodes of podcasts in this language (ISO 639-1 code, e.g. 'fr'). Matches the podcast's primary language subtag, so 'fr' covers 'fr-FR'.", "examples": [ "fr" ], "type": "string" } }, { "description": "Only count episodes with completed transcripts", "explode": false, "in": "query", "name": "has_transcript", "schema": { "description": "Only count episodes with completed transcripts", "type": "boolean" } }, { "description": "Only count episodes that have reached the terminal ingestion milestone", "explode": false, "in": "query", "name": "fully_ingested", "schema": { "description": "Only count episodes that have reached the terminal ingestion milestone", "type": "boolean" } }, { "description": "Minimum episode duration in seconds", "explode": false, "in": "query", "name": "min_duration", "schema": { "description": "Minimum episode duration in seconds", "format": "int64", "maximum": 9223372036, "minimum": 0, "type": "integer" } }, { "description": "Maximum episode duration in seconds", "explode": false, "in": "query", "name": "max_duration", "schema": { "description": "Maximum episode duration in seconds", "format": "int64", "maximum": 9223372036, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EpisodeTimeseries" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.01 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "Get episode timeseries", "tags": [ "Podcast Episodes", "tier:standard" ], "x-cost-weight": 1, "x-payment-info": { "offers": [ { "amount": "10000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.010000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "standard" } }, "/v1/podcasts/episodes/{id}": { "get": { "description": "Returns a single episode by its unique identifier.", "operationId": "get-episode", "parameters": [ { "description": "Episode slug or ID", "in": "path", "name": "id", "required": true, "schema": { "description": "Episode slug or ID", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Episode" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.01 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "Get an episode", "tags": [ "Podcast Episodes", "tier:standard" ], "x-cost-weight": 1, "x-payment-info": { "offers": [ { "amount": "10000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.010000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "standard" } }, "/v1/podcasts/episodes/{id}/ads": { "get": { "description": "Returns the advertising spots detected in a specific episode, including the sponsor, the linked company in the knowledge graph, the advertised product or offer, the read type (HOST_READ vs PRE_RECORDED), and the placement (PRE_ROLL/MID_ROLL/POST_ROLL). Network promos are excluded.", "operationId": "list-episode-ads", "parameters": [ { "description": "Episode slug or ID", "in": "path", "name": "id", "required": true, "schema": { "description": "Episode slug or ID", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageAdDetail" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.03 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "List ads in an episode", "tags": [ "Podcast Episodes", "tier:premium" ], "x-cost-weight": 2, "x-payment-info": { "offers": [ { "amount": "30000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.030000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "premium" } }, "/v1/podcasts/episodes/{id}/clips": { "get": { "description": "Returns the AI-extracted highlight clips for a specific episode, sorted by engagement score.", "operationId": "list-episode-clips", "parameters": [ { "description": "Results per page", "explode": false, "in": "query", "name": "limit", "schema": { "default": 25, "description": "Results per page", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque pagination cursor from previous response", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque pagination cursor from previous response", "type": "string" } }, { "description": "Episode slug or ID", "in": "path", "name": "id", "required": true, "schema": { "description": "Episode slug or ID", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageClip" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.01 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "List clips for an episode", "tags": [ "Podcast Clips", "tier:standard" ], "x-cost-weight": 1, "x-payment-info": { "offers": [ { "amount": "10000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.010000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "standard" } }, "/v1/podcasts/episodes/{id}/entities": { "get": { "description": "Returns knowledge graph entities mentioned in a specific episode, with salience scores and occurrence counts.", "operationId": "list-episode-entities", "parameters": [ { "description": "Results per page (default: all)", "explode": false, "in": "query", "name": "limit", "schema": { "description": "Results per page (default: all)", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque pagination cursor from previous response", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque pagination cursor from previous response", "type": "string" } }, { "description": "Episode slug or ID", "in": "path", "name": "id", "required": true, "schema": { "description": "Episode slug or ID", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageEpisodeEntityAppearance" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.03 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "List entities in an episode", "tags": [ "Podcast Episodes", "tier:standard" ], "x-cost-weight": 1, "x-payment-info": { "offers": [ { "amount": "30000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.030000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "standard" } }, "/v1/podcasts/episodes/{id}/related": { "get": { "description": "Returns episodes from other shows that cover the same story or subject as this episode, best first: a live nearest-neighbour search over episode content, reranked on shared salient entities, shared topics and a shared news story. Each result carries a calibrated score and a band (strong / moderate / weak); pass include=basis to see the signals behind each match. Use published_within_days for 'who else covered this story this week'; pass same_podcast=true to admit the show's own episodes. Returns an empty page when the episode has no embedded content yet, and 404 when the episode is not found.", "operationId": "list-related-episodes", "parameters": [ { "description": "Results per page", "explode": false, "in": "query", "name": "limit", "schema": { "default": 25, "description": "Results per page", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque pagination cursor from previous response", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque pagination cursor from previous response", "type": "string" } }, { "description": "Episode slug or ID", "in": "path", "name": "id", "required": true, "schema": { "description": "Episode slug or ID", "type": "string" } }, { "description": "Admit episodes of the same show. Off by default: a show's own episodes are its episode list (GET /v1/podcasts/{id}/episodes), not its related content.", "explode": false, "in": "query", "name": "same_podcast", "schema": { "description": "Admit episodes of the same show. Off by default: a show's own episodes are its episode list (GET /v1/podcasts/{id}/episodes), not its related content.", "type": "boolean" } }, { "description": "Only episodes published within this many days of the query episode, on either side. Omit (or 0) for no window. Use a short window (7–30) for 'who else covered this story'.", "explode": false, "in": "query", "name": "published_within_days", "schema": { "description": "Only episodes published within this many days of the query episode, on either side. Omit (or 0) for no window. Use a short window (7–30) for 'who else covered this story'.", "format": "int64", "maximum": 3650, "minimum": 0, "type": "integer" } }, { "description": "Optional response sections. Pass include=basis to attach, for every result, the signals that make the two episodes related: content similarity, shared entities (with names), shared topics, a shared news story, shared guests, and days apart.", "explode": false, "in": "query", "name": "include", "schema": { "description": "Optional response sections. Pass include=basis to attach, for every result, the signals that make the two episodes related: content similarity, shared entities (with names), shared topics, a shared news story, shared guests, and days apart.", "items": { "enum": [ "basis" ], "type": "string" }, "type": [ "array", "null" ] } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageRelatedEpisode" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.03 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "List related episodes", "tags": [ "Podcast Episodes", "tier:standard" ], "x-cost-weight": 1, "x-payment-info": { "offers": [ { "amount": "30000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.030000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "standard" } }, "/v1/podcasts/episodes/{id}/segments": { "get": { "description": "Returns the AI-identified segments for a specific episode in chronological order.", "operationId": "list-episode-segments", "parameters": [ { "description": "Results per page (default: all)", "explode": false, "in": "query", "name": "limit", "schema": { "description": "Results per page (default: all)", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque pagination cursor from previous response", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque pagination cursor from previous response", "type": "string" } }, { "description": "Episode slug or ID", "in": "path", "name": "id", "required": true, "schema": { "description": "Episode slug or ID", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageSegment" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.03 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "List segments for an episode", "tags": [ "Podcast Segments", "tier:standard" ], "x-cost-weight": 1, "x-payment-info": { "offers": [ { "amount": "30000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.030000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "standard" } }, "/v1/podcasts/episodes/{id}/speakers": { "get": { "description": "Returns the identified speakers in a specific episode with their roles and speaking durations.", "operationId": "list-episode-speakers", "parameters": [ { "description": "Results per page (default: all)", "explode": false, "in": "query", "name": "limit", "schema": { "description": "Results per page (default: all)", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque pagination cursor from previous response", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque pagination cursor from previous response", "type": "string" } }, { "description": "Episode slug or ID", "in": "path", "name": "id", "required": true, "schema": { "description": "Episode slug or ID", "type": "string" } }, { "description": "Comma-separated speaker role filter, case-insensitive. Defaults to host,guest,panelist,correspondent — the people taking part in the conversation. Name a role to widen: 'advertiser' for sponsor reads, 'soundbite_speaker' for played clips, 'narrator'/'announcer'/'voice_actor' for scripted voices, 'audience' for callers and audience members, 'producer' for production staff, 'unknown' for speakers we could not identify, 'other' for anything else.", "explode": false, "in": "query", "name": "role", "schema": { "description": "Comma-separated speaker role filter, case-insensitive. Defaults to host,guest,panelist,correspondent — the people taking part in the conversation. Name a role to widen: 'advertiser' for sponsor reads, 'soundbite_speaker' for played clips, 'narrator'/'announcer'/'voice_actor' for scripted voices, 'audience' for callers and audience members, 'producer' for production staff, 'unknown' for speakers we could not identify, 'other' for anything else.", "examples": [ [ "host", "guest" ] ], "items": { "enum": [ "host", "guest", "panelist", "correspondent", "moderator", "narrator", "announcer", "voice_actor", "soundbite_speaker", "audience", "advertiser", "producer", "unknown", "other" ], "type": "string" }, "maxItems": 14, "type": [ "array", "null" ] } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageEpisodeSpeaker" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.03 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "List speakers in an episode", "tags": [ "Podcast Episodes", "tier:standard" ], "x-cost-weight": 1, "x-payment-info": { "offers": [ { "amount": "30000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.030000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "standard" } }, "/v1/podcasts/episodes/{id}/topics": { "get": { "description": "Returns the topic taxonomy classifications for a specific episode.", "operationId": "list-episode-topics", "parameters": [ { "description": "Results per page (default: all)", "explode": false, "in": "query", "name": "limit", "schema": { "description": "Results per page (default: all)", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque pagination cursor from previous response", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque pagination cursor from previous response", "type": "string" } }, { "description": "Episode slug or ID", "in": "path", "name": "id", "required": true, "schema": { "description": "Episode slug or ID", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageTopic" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.03 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "List topics for an episode", "tags": [ "Podcast Episodes", "tier:standard" ], "x-cost-weight": 1, "x-payment-info": { "offers": [ { "amount": "30000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.030000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "standard" } }, "/v1/podcasts/episodes/{id}/transcript": { "get": { "description": "Returns the diarized transcript for a podcast episode. Supports dialogue (speaker-attributed lines), plain text, and SRT subtitle formats. Optionally filter by speaker or time range.", "operationId": "get-episode-transcript", "parameters": [ { "description": "Episode slug or ID", "in": "path", "name": "id", "required": true, "schema": { "description": "Episode slug or ID", "type": "string" } }, { "description": "Output format: dialogue (speaker-attributed lines), text (plain text), srt (SubRip subtitles)", "explode": false, "in": "query", "name": "format", "schema": { "default": "dialogue", "description": "Output format: dialogue (speaker-attributed lines), text (plain text), srt (SubRip subtitles)", "enum": [ "dialogue", "text", "srt" ], "type": "string" } }, { "description": "Filter to lines from a specific speaker. Accepts a speaker name (full or partial, case-insensitive) or a knowledge graph entity reference (canonical id or slug).", "explode": false, "in": "query", "name": "speaker", "schema": { "description": "Filter to lines from a specific speaker. Accepts a speaker name (full or partial, case-insensitive) or a knowledge graph entity reference (canonical id or slug).", "type": "string" } }, { "description": "Start time in seconds for time-range clipping", "explode": false, "in": "query", "name": "start", "schema": { "description": "Start time in seconds for time-range clipping", "format": "double", "type": "number" } }, { "description": "End time in seconds for time-range clipping", "explode": false, "in": "query", "name": "end", "schema": { "description": "End time in seconds for time-range clipping", "format": "double", "type": "number" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.03 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "Get episode transcript", "tags": [ "Podcast Transcripts", "tier:standard" ], "x-cost-weight": 1, "x-payment-info": { "offers": [ { "amount": "30000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.030000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "standard" } }, "/v1/podcasts/episodes/{id}/transcript/mentions": { "get": { "description": "Finds all mentions of a specific entity within an episode's transcript and returns each mention with surrounding dialogue context. Useful for seeing exactly where and how an entity is discussed.", "operationId": "get-episode-entity-mentions", "parameters": [ { "description": "Episode slug or ID", "in": "path", "name": "id", "required": true, "schema": { "description": "Episode slug or ID", "type": "string" } }, { "description": "Entity identifier (KGE ID or slug). When omitted, returns mentions for all entities.", "explode": false, "in": "query", "name": "entity_id", "schema": { "description": "Entity identifier (KGE ID or slug). When omitted, returns mentions for all entities.", "type": "string" } }, { "description": "Lines of dialogue context returned on each side of every mention line. A single mention yields up to 2*context_lines+1 lines (clamped at transcript boundaries). Adjacent or overlapping windows merge into one chunk.", "explode": false, "in": "query", "name": "context_lines", "schema": { "default": 2, "description": "Lines of dialogue context returned on each side of every mention line. A single mention yields up to 2*context_lines+1 lines (clamped at transcript boundaries). Adjacent or overlapping windows merge into one chunk.", "format": "int64", "maximum": 20, "minimum": 0, "type": "integer" } }, { "description": "Results per page. When entity_id is set, paginates the mentions[] (windows) for that entity; otherwise paginates the top-level entities[].", "explode": false, "in": "query", "name": "limit", "schema": { "default": 25, "description": "Results per page. When entity_id is set, paginates the mentions[] (windows) for that entity; otherwise paginates the top-level entities[].", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque pagination cursor from a previous response.", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque pagination cursor from a previous response.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityMentionsResponse" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.03 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "Get entity mentions in transcript", "tags": [ "Podcast Transcripts", "tier:standard" ], "x-cost-weight": 1, "x-payment-info": { "offers": [ { "amount": "30000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.030000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "standard" } }, "/v1/podcasts/episodes/{id}/transcript/preview": { "get": { "description": "Returns one segment of an episode's transcript: the latest segment starting at or before `at` (seconds), or the opening segment when `at` is omitted. A moment falling between two segments resolves to the earlier one, and a moment outside the episode clamps to the first or last segment, so the returned range does not always contain `at` — `segment_start_seconds` and `segment_end_seconds` report what was actually returned. Every caller gets the same excerpt for a given moment regardless of plan, so unlike the full transcript this response is cacheable and safe to render for signed-out visitors. Use this to open a deep link on a moment; use get-episode-transcript for the whole episode.", "operationId": "get-episode-transcript-preview", "parameters": [ { "description": "Episode slug or ID", "in": "path", "name": "id", "required": true, "schema": { "description": "Episode slug or ID", "type": "string" } }, { "description": "A moment in the episode, in seconds. Returns the latest segment starting at or before it, which is not always a segment containing it: a value falling in the gap between two segments resolves to the earlier one, and a value outside the episode clamps to the first or last segment. Read segment_start_seconds/segment_end_seconds for the range actually returned. Omit for the opening segment.", "explode": false, "in": "query", "name": "at", "schema": { "description": "A moment in the episode, in seconds. Returns the latest segment starting at or before it, which is not always a segment containing it: a value falling in the gap between two segments resolves to the earlier one, and a value outside the episode clamps to the first or last segment. Read segment_start_seconds/segment_end_seconds for the range actually returned. Omit for the opening segment.", "format": "double", "type": "number" } }, { "description": "Output format: dialogue (speaker-attributed lines), text (plain text), srt (SubRip subtitles)", "explode": false, "in": "query", "name": "format", "schema": { "default": "dialogue", "description": "Output format: dialogue (speaker-attributed lines), text (plain text), srt (SubRip subtitles)", "enum": [ "dialogue", "text", "srt" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "OK", "headers": { "Cache-Control": { "schema": { "type": "string" } }, "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.01 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "Get a transcript excerpt around a moment", "tags": [ "Podcast Transcripts", "tier:standard" ], "x-cost-weight": 1, "x-payment-info": { "offers": [ { "amount": "10000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.010000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "standard" } }, "/v1/podcasts/episodes/{id}/transcript/words": { "get": { "description": "Returns the word-level timestamped transcript for a podcast episode. Use start/end to extract a time range, limit/cursor to paginate (defaults to all words), and exclude_spacing=true to drop the inter-word whitespace tokens that NLP/LLM consumers don't need.", "operationId": "get-episode-word-transcript", "parameters": [ { "description": "Episode slug or ID", "in": "path", "name": "id", "required": true, "schema": { "description": "Episode slug or ID", "type": "string" } }, { "description": "Start time in seconds", "explode": false, "in": "query", "name": "start", "schema": { "description": "Start time in seconds", "format": "double", "type": "number" } }, { "description": "End time in seconds", "explode": false, "in": "query", "name": "end", "schema": { "description": "End time in seconds", "format": "double", "type": "number" } }, { "description": "Max words per page. Omit to return all matching words.", "explode": false, "in": "query", "name": "limit", "schema": { "description": "Max words per page. Omit to return all matching words.", "format": "int64", "maximum": 5000, "minimum": 1, "type": "integer" } }, { "description": "Opaque pagination cursor from a previous response.", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque pagination cursor from a previous response.", "type": "string" } }, { "description": "Drop type:\"spacing\" tokens (whitespace between words). Pass true for NLP, search, and LLM consumption — roughly halves the payload. Leave false for caption/karaoke rendering where inter-word timing matters.", "explode": false, "in": "query", "name": "exclude_spacing", "schema": { "description": "Drop type:\"spacing\" tokens (whitespace between words). Pass true for NLP, search, and LLM consumption — roughly halves the payload. Leave false for caption/karaoke rendering where inter-word timing matters.", "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WordTranscriptResponse" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.03 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "Get word-level transcript", "tags": [ "Podcast Transcripts", "tier:standard" ], "x-cost-weight": 1, "x-payment-info": { "offers": [ { "amount": "30000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.030000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "standard" } }, "/v1/podcasts/guests": { "get": { "description": "Returns a paginated directory of Persons who have appeared on at least one podcast episode in a non-host listing role. Filter by name, topic, podcast, date, and brand-safety tier.", "operationId": "list-podcast-guests", "parameters": [ { "description": "Results per page", "explode": false, "in": "query", "name": "limit", "schema": { "default": 25, "description": "Results per page", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque pagination cursor from previous response", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque pagination cursor from previous response", "type": "string" } }, { "description": "Case-insensitive substring match against the guest's display name", "explode": false, "in": "query", "name": "q", "schema": { "description": "Case-insensitive substring match against the guest's display name", "type": "string" } }, { "description": "Minimum lifetime appearance count to include (default 1)", "explode": false, "in": "query", "name": "min_appearances", "schema": { "description": "Minimum lifetime appearance count to include (default 1)", "format": "int64", "minimum": 1, "type": "integer" } }, { "description": "Restrict to guests who have appeared on this podcast (slug or ID)", "explode": false, "in": "query", "name": "podcast_id", "schema": { "description": "Restrict to guests who have appeared on this podcast (slug or ID)", "type": "string" } }, { "description": "Restrict to guests with at least one appearance on an episode classified under this topic", "explode": false, "in": "query", "name": "topic_id", "schema": { "description": "Restrict to guests with at least one appearance on an episode classified under this topic", "type": "string" } }, { "description": "Only include guests with at least one appearance published on or after this ISO 8601 date", "explode": false, "in": "query", "name": "appeared_since", "schema": { "description": "Only include guests with at least one appearance published on or after this ISO 8601 date", "type": "string" } }, { "description": "Restrict to guests whose appearances are on podcasts at or below this IAB Tech Lab brand-safety tier", "explode": false, "in": "query", "name": "suitability_tier_max", "schema": { "description": "Restrict to guests whose appearances are on podcasts at or below this IAB Tech Lab brand-safety tier", "enum": [ "SAFE", "LIMITED", "SENSITIVE", "UNSAFE" ], "type": "string" } }, { "description": "Sort order (default: appearances)", "explode": false, "in": "query", "name": "sort", "schema": { "description": "Sort order (default: appearances)", "enum": [ "appearances", "recency" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagePodcastGuestCompact" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.03 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "List podcast guests", "tags": [ "Podcast Guests", "tier:standard" ], "x-cost-weight": 1, "x-payment-info": { "offers": [ { "amount": "30000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.030000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "standard" } }, "/v1/podcasts/guests/trends": { "get": { "description": "Surfaces guests who are currently making the podcast rounds — the kind of cross-show interview activity that signals a book launch, product unveil, news-cycle moment, or new-on-the-scene debut. Each row is a guest whose recent activity is materially elevated above their own historical baseline AND who has appeared on multiple distinct podcasts inside the window with substantive (5+ minute) interviews. Filter by recency window, topic, brand-safety tier, and an optional first-appearance cutoff to find people new to the scene. This is not a leaderboard of perennial podcast regulars, recurring co-hosts, or daily news-segment contributors — those are filtered out by design; use /v1/podcasts/guests for a steady-state directory. Statistics refresh hourly.", "operationId": "list-podcast-guest-trends", "parameters": [ { "description": "Results per page", "explode": false, "in": "query", "name": "limit", "schema": { "default": 25, "description": "Results per page", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque pagination cursor from previous response", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque pagination cursor from previous response", "type": "string" } }, { "description": "Inclusive lower bound of the trend window (default: 30 days ago)", "explode": false, "in": "query", "name": "since", "schema": { "description": "Inclusive lower bound of the trend window (default: 30 days ago)", "type": "string" } }, { "description": "Minimum number of distinct podcasts the guest must have appeared on inside the window (default 2)", "explode": false, "in": "query", "name": "min_distinct_podcasts", "schema": { "description": "Minimum number of distinct podcasts the guest must have appeared on inside the window (default 2)", "format": "int64", "minimum": 2, "type": "integer" } }, { "description": "Restrict to guests whose earliest-ever appearance is on or after this date (the \"new on the scene\" cut)", "explode": false, "in": "query", "name": "first_appearance_since", "schema": { "description": "Restrict to guests whose earliest-ever appearance is on or after this date (the \"new on the scene\" cut)", "type": "string" } }, { "description": "Restrict to guests with at least one in-window appearance on an episode classified under this topic", "explode": false, "in": "query", "name": "topic_id", "schema": { "description": "Restrict to guests with at least one in-window appearance on an episode classified under this topic", "type": "string" } }, { "description": "Restrict to in-window appearances on podcasts at or below this IAB Tech Lab brand-safety tier", "explode": false, "in": "query", "name": "suitability_tier_max", "schema": { "description": "Restrict to in-window appearances on podcasts at or below this IAB Tech Lab brand-safety tier", "enum": [ "SAFE", "LIMITED", "SENSITIVE", "UNSAFE" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagePodcastGuestTrend" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.04 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "List trending podcast guests", "tags": [ "Podcast Guests", "tier:standard" ], "x-cost-weight": 1, "x-payment-info": { "offers": [ { "amount": "40000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.040000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "standard" } }, "/v1/podcasts/guests/{id}": { "get": { "description": "Returns the lifetime profile for a podcast guest including their Person identity (name, slug, headshot, current title/company), total appearances, distinct podcasts, role mix, and the most-frequent shows they've appeared on. The {id} parameter accepts the Person slug (recommended), the person's knowledge-graph entity slug, or the encoded Person UUID.", "operationId": "get-podcast-guest", "parameters": [ { "description": "Person identifier. Accepts the Person slug (recommended; returned as 'slug' on every guest payload), the person's knowledge-graph entity slug, or the encoded Person UUID returned as 'id'.", "in": "path", "name": "id", "required": true, "schema": { "description": "Person identifier. Accepts the Person slug (recommended; returned as 'slug' on every guest payload), the person's knowledge-graph entity slug, or the encoded Person UUID returned as 'id'.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastGuest" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.03 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "Get a podcast guest profile", "tags": [ "Podcast Guests", "tier:standard" ], "x-cost-weight": 1, "x-payment-info": { "offers": [ { "amount": "30000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.030000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "standard" } }, "/v1/podcasts/guests/{id}/appearances": { "get": { "description": "Returns the chronological list of episodes a guest has appeared on, most recent first. Supports filtering by podcast, role, topic, date range, brand-safety tier, and minimum speaking duration.", "operationId": "list-podcast-guest-appearances", "parameters": [ { "description": "Results per page", "explode": false, "in": "query", "name": "limit", "schema": { "default": 25, "description": "Results per page", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque pagination cursor from previous response", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque pagination cursor from previous response", "type": "string" } }, { "description": "Person identifier — person slug (recommended), knowledge-graph entity slug, or encoded UUID", "in": "path", "name": "id", "required": true, "schema": { "description": "Person identifier — person slug (recommended), knowledge-graph entity slug, or encoded UUID", "type": "string" } }, { "description": "Restrict to appearances on a single podcast (slug or ID)", "explode": false, "in": "query", "name": "podcast_id", "schema": { "description": "Restrict to appearances on a single podcast (slug or ID)", "type": "string" } }, { "description": "Restrict to appearances on episodes classified under this topic", "explode": false, "in": "query", "name": "topic_id", "schema": { "description": "Restrict to appearances on episodes classified under this topic", "type": "string" } }, { "description": "Only appearances published after this ISO 8601 date", "explode": false, "in": "query", "name": "published_after", "schema": { "description": "Only appearances published after this ISO 8601 date", "type": "string" } }, { "description": "Only appearances published before this ISO 8601 date", "explode": false, "in": "query", "name": "published_before", "schema": { "description": "Only appearances published before this ISO 8601 date", "type": "string" } }, { "description": "Restrict to appearances on podcasts at or below this IAB Tech Lab brand-safety tier", "explode": false, "in": "query", "name": "suitability_tier_max", "schema": { "description": "Restrict to appearances on podcasts at or below this IAB Tech Lab brand-safety tier", "enum": [ "SAFE", "LIMITED", "SENSITIVE", "UNSAFE" ], "type": "string" } }, { "description": "Restrict to appearances with identified speaking time above this threshold", "explode": false, "in": "query", "name": "min_speaking_seconds", "schema": { "description": "Restrict to appearances with identified speaking time above this threshold", "format": "int64", "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagePodcastGuestAppearance" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.03 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "List appearances for a podcast guest", "tags": [ "Podcast Guests", "tier:standard" ], "x-cost-weight": 1, "x-payment-info": { "offers": [ { "amount": "30000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.030000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "standard" } }, "/v1/podcasts/guests/{id}/podcasts": { "get": { "description": "Returns the distinct set of podcasts a guest has appeared on, with per-podcast appearance counts, first/last appearance dates, and the podcast's brand-safety and bias attributes when evaluated.", "operationId": "list-podcast-guest-podcasts", "parameters": [ { "description": "Results per page", "explode": false, "in": "query", "name": "limit", "schema": { "default": 25, "description": "Results per page", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque pagination cursor from previous response", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque pagination cursor from previous response", "type": "string" } }, { "description": "Person identifier — person slug (recommended), knowledge-graph entity slug, or encoded UUID", "in": "path", "name": "id", "required": true, "schema": { "description": "Person identifier — person slug (recommended), knowledge-graph entity slug, or encoded UUID", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagePodcastGuestPodcast" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.04 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "List podcasts a guest has appeared on", "tags": [ "Podcast Guests", "tier:standard" ], "x-cost-weight": 1, "x-payment-info": { "offers": [ { "amount": "40000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.040000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "standard" } }, "/v1/podcasts/guests/{id}/recommendations/podcasts": { "get": { "description": "Returns shows the person has NOT appeared on, ranked by how related they are to the shows that booked the person as a guest — the pitch list. Seeds count once per publisher (an outlet's sibling feeds are one venue) and correspondent segments for the person's own newsroom do not seed it. Each row carries the podcast, a score in (0,1), a band (strong/moderate/weak), and with include=via the person's own shows that led to the recommendation, so a pitch can cite them ('hosts of X and Y book guests like you'). Circuit regulars are discounted upstream so the list is about fit, not fame. Recommendations are derived from each show's precomputed related set (GET /v1/podcasts/{id}/related); a person with no guest or panelist bookings on record (host and correspondent appearances do not seed the list), or whose shows have no computed related set yet, gets an empty page. For the shows a person has already been on, use GET /v1/podcasts/guests/{id}/podcasts.", "operationId": "list-podcast-guest-recommended-podcasts", "parameters": [ { "description": "Results per page", "explode": false, "in": "query", "name": "limit", "schema": { "default": 25, "description": "Results per page", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque pagination cursor from previous response", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque pagination cursor from previous response", "type": "string" } }, { "description": "Person identifier — person slug (recommended), knowledge-graph entity slug, or encoded UUID", "in": "path", "name": "id", "required": true, "schema": { "description": "Person identifier — person slug (recommended), knowledge-graph entity slug, or encoded UUID", "type": "string" } }, { "description": "Optional response sections. Pass include=via to attach, for each recommendation, the person's own shows that led to it — the venues to cite when pitching.", "explode": false, "in": "query", "name": "include", "schema": { "description": "Optional response sections. Pass include=via to attach, for each recommendation, the person's own shows that led to it — the venues to cite when pitching.", "items": { "enum": [ "via" ], "type": "string" }, "type": [ "array", "null" ] } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageRecommendedPodcast" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.03 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "List podcasts a guest could plausibly appear on next", "tags": [ "Podcast Guests", "tier:standard" ], "x-cost-weight": 1, "x-payment-info": { "offers": [ { "amount": "30000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.030000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "standard" } }, "/v1/podcasts/guests/{id}/suitability": { "get": { "description": "Returns the distribution of IAB Tech Lab brand-suitability tiers across the podcasts a guest has appeared on, plus the most-frequently flagged categories observed in those shows. This measures the guest's exposure across the shows they've appeared on — not a verdict on the guest themselves.", "operationId": "get-podcast-guest-suitability-exposure", "parameters": [ { "description": "Person identifier — person slug (recommended), knowledge-graph entity slug, or encoded UUID", "in": "path", "name": "id", "required": true, "schema": { "description": "Person identifier — person slug (recommended), knowledge-graph entity slug, or encoded UUID", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastGuestSuitabilityExposure" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.04 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "Get a guest's brand-suitability exposure profile", "tags": [ "Podcast Guests", "tier:standard" ], "x-cost-weight": 1, "x-payment-info": { "offers": [ { "amount": "40000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.040000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "standard" } }, "/v1/podcasts/lookup": { "get": { "description": "Resolves one or more external platform identifiers (Apple Podcasts collection IDs, Spotify show IDs, YouTube channel IDs, …) — or RSS feed URLs via `platform=rss` — to Particle podcasts. Pass `platform` once and a comma-separated list of identifiers (up to 100 per call). Each result echoes the input identifier alongside the matched podcast; unresolved identifiers omit the `podcast` field entirely so bulk callers can correlate inputs and outputs by key presence without doing a separate join. Use this when you already hold platform-native IDs and want a deterministic mapping; for fuzzy name search use GET /v1/podcasts/search.", "operationId": "lookup-podcasts", "parameters": [ { "description": "External platform slug (e.g. 'apple', 'spotify', 'youtube'), case-insensitive. Must be one of the slugs reported on /v1/podcasts/{id}/external-links responses, or one of the in-house aliases: 'itunes' (alias for 'apple'), 'x' (alias for 'twitter') and 'rss' (match against the canonical podcast feed URL).", "explode": false, "in": "query", "name": "platform", "required": true, "schema": { "description": "External platform slug (e.g. 'apple', 'spotify', 'youtube'), case-insensitive. Must be one of the slugs reported on /v1/podcasts/{id}/external-links responses, or one of the in-house aliases: 'itunes' (alias for 'apple'), 'x' (alias for 'twitter') and 'rss' (match against the canonical podcast feed URL).", "examples": [ "apple" ], "type": "string" } }, { "description": "One or more platform-native identifiers to resolve. Pass a comma-separated list to look up many at once (max 100 per call). Matching ignores case, so 'thepeelpod' finds the podcast whose X handle is 'ThePeelPod'; URLs ('rss', 'website') are the exception and match exactly.", "explode": false, "in": "query", "name": "identifier", "required": true, "schema": { "description": "One or more platform-native identifiers to resolve. Pass a comma-separated list to look up many at once (max 100 per call). Matching ignores case, so 'thepeelpod' finds the podcast whose X handle is 'ThePeelPod'; URLs ('rss', 'website') are the exception and match exactly.", "examples": [ [ "1535809341", "1200361736" ] ], "items": { "type": "string" }, "maxItems": 100, "minItems": 1, "type": [ "array", "null" ] } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastLookup" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.01 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "Look up podcasts by external platform identifier", "tags": [ "Podcasts", "tier:standard" ], "x-cost-weight": 1, "x-payment-info": { "offers": [ { "amount": "10000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.010000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "standard" } }, "/v1/podcasts/mentions": { "get": { "description": "Returns every line of dialogue that mentions a person or company, grouped by episode and ordered by recency. Each result is one episode plus all of that episode's mention windows — a window is a contiguous range of dialogue containing the mention with `context_lines` of surrounding context, and lines containing the mention have `is_mention=true`.\n\nMentions inside ad reads are excluded by default; pass `include_ads=true` to include them.\n\nSubjects with no knowledge graph entity (most podcast guests, smaller companies) are matched by scanning dialogue for their name verbatim instead of curated entity tags; such pages carry `matched_by: \"name\"` and echo the resolved `person` or `company` instead of `entity`.\n\nUse this endpoint for the \"every line about X\" use case. For finding dialogue by topic or exact phrase use `/v1/podcasts/episodes/search` instead.", "operationId": "search-podcast-mentions", "parameters": [ { "description": "Entity slug (e.g., 'sam-altman') or ID. A person slug or ID resolves via the person's linked knowledge graph entity; a person with no linked entity falls back to name matching (matched_by=name). Required when company_id is not set.", "explode": false, "in": "query", "name": "entity_id", "schema": { "description": "Entity slug (e.g., 'sam-altman') or ID. A person slug or ID resolves via the person's linked knowledge graph entity; a person with no linked entity falls back to name matching (matched_by=name). Required when company_id is not set.", "type": "string" } }, { "description": "Company slug, domain, or ID. Required when entity_id is not set. Resolves to the company's linked entity; a company with no linked entity falls back to name matching (matched_by=name).", "explode": false, "in": "query", "name": "company_id", "schema": { "description": "Company slug, domain, or ID. Required when entity_id is not set. Resolves to the company's linked entity; a company with no linked entity falls back to name matching (matched_by=name).", "type": "string" } }, { "description": "Restrict to mentions inside one podcast.", "explode": false, "in": "query", "name": "podcast_id", "schema": { "description": "Restrict to mentions inside one podcast.", "type": "string" } }, { "description": "Restrict to mentions on podcasts attributed to one publisher (network), by slug or ID.", "explode": false, "in": "query", "name": "publisher_id", "schema": { "description": "Restrict to mentions on podcasts attributed to one publisher (network), by slug or ID.", "type": "string" } }, { "description": "Restrict to mentions inside one episode by slug or ID (cross-corpus result still surfaces a single episode group).", "explode": false, "in": "query", "name": "episode_id", "schema": { "description": "Restrict to mentions inside one episode by slug or ID (cross-corpus result still surfaces a single episode group).", "type": "string" } }, { "description": "Constrain how the entity participates: guest, host, panelist, correspondent, or mention.", "explode": false, "in": "query", "name": "role", "schema": { "description": "Constrain how the entity participates: guest, host, panelist, correspondent, or mention.", "enum": [ "guest", "host", "panelist", "correspondent", "mention" ], "type": "string" } }, { "description": "Result ordering. recency (the default) returns the most recently published episodes first. popularity orders by the parent podcast's global popularity percentile — the biggest shows first, recency breaking ties within a show, non-charting podcasts last. favorites keeps the recency ordering but lifts the calling user's favorited shows to the top of each publication day; it requires an authenticated user session (401 for an API key or anonymous token) and falls back to plain recency for a user with no favorited podcasts. Pass the same sort alongside a cursor when paginating.", "explode": false, "in": "query", "name": "sort", "schema": { "description": "Result ordering. recency (the default) returns the most recently published episodes first. popularity orders by the parent podcast's global popularity percentile — the biggest shows first, recency breaking ties within a show, non-charting podcasts last. favorites keeps the recency ordering but lifts the calling user's favorited shows to the top of each publication day; it requires an authenticated user session (401 for an API key or anonymous token) and falls back to plain recency for a user with no favorited podcasts. Pass the same sort alongside a cursor when paginating.", "enum": [ "recency", "popularity", "favorites" ], "type": "string" } }, { "description": "Mentions inside ad reads (sponsor ad segments, or lines spoken by an advertiser) are excluded by default. Pass true to include them.", "explode": false, "in": "query", "name": "include_ads", "schema": { "description": "Mentions inside ad reads (sponsor ad segments, or lines spoken by an advertiser) are excluded by default. Pass true to include them.", "type": "boolean" } }, { "description": "Restrict to episodes of podcasts in this language (ISO 639-1 code, e.g. 'fr'). Matches the podcast's primary language subtag, so 'fr' covers 'fr-FR'.", "explode": false, "in": "query", "name": "language", "schema": { "description": "Restrict to episodes of podcasts in this language (ISO 639-1 code, e.g. 'fr'). Matches the podcast's primary language subtag, so 'fr' covers 'fr-FR'.", "examples": [ "fr" ], "type": "string" } }, { "description": "Only episodes published after this date.", "explode": false, "in": "query", "name": "since", "schema": { "description": "Only episodes published after this date.", "examples": [ "2024-01-01" ], "type": "string" } }, { "description": "Only episodes published before this date.", "explode": false, "in": "query", "name": "until", "schema": { "description": "Only episodes published before this date.", "examples": [ "2024-06-01" ], "type": "string" } }, { "description": "Surrounding dialogue lines around each mention.", "explode": false, "in": "query", "name": "context_lines", "schema": { "default": 2, "description": "Surrounding dialogue lines around each mention.", "format": "int64", "maximum": 20, "minimum": 0, "type": "integer" } }, { "description": "Episodes per page (1-100, default 25). Each episode's full set of mention windows is returned in a single page; episodes never split across pages.", "explode": false, "in": "query", "name": "limit", "schema": { "default": 25, "description": "Episodes per page (1-100, default 25). Each episode's full set of mention windows is returned in a single page; episodes never split across pages.", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque cursor from a previous response.", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque cursor from a previous response.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastMentionsPage" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.04 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "Search podcast dialogue for entity mentions", "tags": [ "Podcast Episode Search", "tier:standard" ], "x-cost-weight": 1, "x-payment-info": { "offers": [ { "amount": "40000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.040000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "standard" } }, "/v1/podcasts/mentions/timeseries": { "get": { "description": "Returns time-bucketed counts of episodes mentioning an entity, plus per-bucket mention line counts and range totals — the aggregate twin of `/v1/podcasts/mentions`. For windows the search can fully enumerate, bucket counts match what it returns: mentions inside ad reads are excluded by default (pass `include_ads=true` to count them), so use this for mention trend charts instead of paging the search once per period. Buckets are UTC-aligned, zero-filled, and Monday-aligned for weeks. Requires entity_id or company_id. Omitting published_after aggregates all time. Ranges are capped at 1000 buckets.\n\nFor appearance trends by speaker role across episode-level filters (language, duration, keyword_search) use `/v1/podcasts/episodes/timeseries` instead; its `role=mention` counts include ad reads.", "operationId": "get-mentions-timeseries", "parameters": [ { "description": "Entity slug (e.g., 'sam-altman') or ID. Required when company_id is not set.", "explode": false, "in": "query", "name": "entity_id", "schema": { "description": "Entity slug (e.g., 'sam-altman') or ID. Required when company_id is not set.", "type": "string" } }, { "description": "Company slug, domain, or ID. Required when entity_id is not set. Resolves to the company's linked entity.", "explode": false, "in": "query", "name": "company_id", "schema": { "description": "Company slug, domain, or ID. Required when entity_id is not set. Resolves to the company's linked entity.", "type": "string" } }, { "description": "Restrict to mentions inside one podcast.", "explode": false, "in": "query", "name": "podcast_id", "schema": { "description": "Restrict to mentions inside one podcast.", "type": "string" } }, { "description": "Restrict to mentions on podcasts attributed to one publisher (network), by slug or ID.", "explode": false, "in": "query", "name": "publisher_id", "schema": { "description": "Restrict to mentions on podcasts attributed to one publisher (network), by slug or ID.", "type": "string" } }, { "description": "Constrain how the entity participates: guest, host, panelist, correspondent, or mention.", "explode": false, "in": "query", "name": "role", "schema": { "description": "Constrain how the entity participates: guest, host, panelist, correspondent, or mention.", "enum": [ "guest", "host", "panelist", "correspondent", "mention" ], "type": "string" } }, { "description": "Mentions inside ad reads (sponsor ad segments, or lines spoken by an advertiser) are excluded by default. Pass true to include them.", "explode": false, "in": "query", "name": "include_ads", "schema": { "description": "Mentions inside ad reads (sponsor ad segments, or lines spoken by an advertiser) are excluded by default. Pass true to include them.", "type": "boolean" } }, { "description": "Restrict to episodes of podcasts in this language (ISO 639-1 code, e.g. 'fr'). Matches the podcast's primary language subtag, so 'fr' covers 'fr-FR'.", "explode": false, "in": "query", "name": "language", "schema": { "description": "Restrict to episodes of podcasts in this language (ISO 639-1 code, e.g. 'fr'). Matches the podcast's primary language subtag, so 'fr' covers 'fr-FR'.", "examples": [ "fr" ], "type": "string" } }, { "description": "Only episodes published on or after this date. Omit to aggregate all time.", "explode": false, "in": "query", "name": "published_after", "schema": { "description": "Only episodes published on or after this date. Omit to aggregate all time.", "examples": [ "2026-01-01" ], "type": "string" } }, { "description": "Only episodes published on or before this date. Defaults to now.", "explode": false, "in": "query", "name": "published_before", "schema": { "description": "Only episodes published on or before this date. Defaults to now.", "examples": [ "2026-06-01" ], "type": "string" } }, { "description": "Bucket width.", "explode": false, "in": "query", "name": "interval", "schema": { "default": "week", "description": "Bucket width.", "enum": [ "day", "week", "month" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MentionTimeseries" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.04 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "Get mention timeseries", "tags": [ "Podcast Episode Search", "tier:standard" ], "x-cost-weight": 1, "x-payment-info": { "offers": [ { "amount": "40000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.040000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "standard" } }, "/v1/podcasts/publishers": { "get": { "description": "Returns a paginated list of podcast publishers, ordered by catalog size (largest first, the default) or alphabetically by name. Filter with q (case-insensitive name/slug substring; exact name matches sort first). Each entry includes the publisher name, slug, and the number of podcasts attributed to the publisher.", "operationId": "list-podcast-publishers", "parameters": [ { "description": "Results per page", "explode": false, "in": "query", "name": "limit", "schema": { "default": 25, "description": "Results per page", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque pagination cursor from previous response", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque pagination cursor from previous response", "type": "string" } }, { "description": "Case-insensitive substring match against the publisher's name or slug. An exact name match sorts first.", "explode": false, "in": "query", "name": "q", "schema": { "description": "Case-insensitive substring match against the publisher's name or slug. An exact name match sorts first.", "type": "string" } }, { "description": "Sort order. podcast_count ranks publishers by catalog size (largest first); name sorts alphabetically.", "explode": false, "in": "query", "name": "sort", "schema": { "default": "podcast_count", "description": "Sort order. podcast_count ranks publishers by catalog size (largest first); name sorts alphabetically.", "enum": [ "podcast_count", "name" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagePodcastPublisher" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.03 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "List podcast publishers", "tags": [ "Podcast Publishers", "tier:standard" ], "x-cost-weight": 1, "x-payment-info": { "offers": [ { "amount": "30000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.030000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "standard" } }, "/v1/podcasts/publishers/{id}": { "get": { "description": "Returns a single podcast publisher by slug (e.g., 'goalhanger', 'iheartpodcasts', 'bbc-radio-4') or ID. Slugs are human-readable identifiers populated for the vast majority of publishers and are the recommended way to reference a publisher in URLs. The ID always works as a fallback for publishers whose name doesn't slugify.", "operationId": "get-podcast-publisher", "parameters": [ { "description": "Podcast publisher slug (e.g., 'goalhanger', 'iheartpodcasts', 'bbc-radio-4') or ID. Slugs are stable, human-readable identifiers returned on every publisher response and are the recommended way to reference a publisher in URLs.", "in": "path", "name": "id", "required": true, "schema": { "description": "Podcast publisher slug (e.g., 'goalhanger', 'iheartpodcasts', 'bbc-radio-4') or ID. Slugs are stable, human-readable identifiers returned on every publisher response and are the recommended way to reference a publisher in URLs.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastPublisher" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.03 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "Get a podcast publisher", "tags": [ "Podcast Publishers", "tier:standard" ], "x-cost-weight": 1, "x-payment-info": { "offers": [ { "amount": "30000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.030000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "standard" } }, "/v1/podcasts/publishers/{id}/advertising": { "get": { "description": "Returns advertising intelligence rolled up across every podcast attributed to the publisher: total ads, unique sponsors, episode reach, host-read vs pre-recorded mix, the top sponsors, and the count of network buyers (sponsors hitting at least 3 podcasts and at least 25% of the publisher's catalog).", "operationId": "get-publisher-advertising", "parameters": [ { "description": "Podcast publisher slug (e.g., 'iheartpodcasts', 'bbc-radio-4') or ID", "in": "path", "name": "id", "required": true, "schema": { "description": "Podcast publisher slug (e.g., 'iheartpodcasts', 'bbc-radio-4') or ID", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublisherAdvertisingProfile" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.03 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "Get publisher advertising profile", "tags": [ "Podcast Advertising", "tier:premium" ], "x-cost-weight": 2, "x-payment-info": { "offers": [ { "amount": "30000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.030000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "premium" } }, "/v1/podcasts/publishers/{id}/advertising/podcasts": { "get": { "description": "Returns a paginated list of the publisher's podcasts ordered by total ad count. Differs from /v1/podcasts/publishers/{id}/podcasts (popularity-ordered) by exposing monetization data instead of audience signals: ad_count, unique_sponsors, episodes_with_ads, avg_ads_per_episode, and the host-read/pre-recorded breakdown.", "operationId": "list-publisher-advertising-podcasts", "parameters": [ { "description": "Results per page", "explode": false, "in": "query", "name": "limit", "schema": { "default": 25, "description": "Results per page", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque pagination cursor from previous response", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque pagination cursor from previous response", "type": "string" } }, { "description": "Podcast publisher slug (e.g., 'iheartpodcasts', 'bbc-radio-4') or ID", "in": "path", "name": "id", "required": true, "schema": { "description": "Podcast publisher slug (e.g., 'iheartpodcasts', 'bbc-radio-4') or ID", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagePublisherAdvertisingPodcastEntry" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.03 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "List publisher's podcasts ranked by ad volume", "tags": [ "Podcast Advertising", "tier:premium" ], "x-cost-weight": 2, "x-payment-info": { "offers": [ { "amount": "30000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.030000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "premium" } }, "/v1/podcasts/publishers/{id}/advertising/sponsors": { "get": { "description": "Returns a paginated list of sponsors active across the publisher's catalog. Each entry includes the bundle-buy signal — podcast_coverage (distinct podcasts in the catalog where the sponsor appears) and coverage_share (the same as a 0..1 fraction of the publisher's catalog). Sort by podcast_coverage and combine with min_podcast_coverage to surface network buyers.", "operationId": "list-publisher-advertising-sponsors", "parameters": [ { "description": "Results per page", "explode": false, "in": "query", "name": "limit", "schema": { "default": 25, "description": "Results per page", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque pagination cursor from previous response", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque pagination cursor from previous response", "type": "string" } }, { "description": "Search by name (case-insensitive partial match)", "explode": false, "in": "query", "name": "q", "schema": { "description": "Search by name (case-insensitive partial match)", "examples": [ "Apple" ], "maxLength": 200, "type": "string" } }, { "description": "Podcast publisher slug (e.g., 'iheartpodcasts', 'bbc-radio-4') or ID", "in": "path", "name": "id", "required": true, "schema": { "description": "Podcast publisher slug (e.g., 'iheartpodcasts', 'bbc-radio-4') or ID", "type": "string" } }, { "description": "Sort order. ad_count ranks by ad volume on the publisher's catalog; podcast_coverage surfaces network buyers (sponsors hitting many shows); episode_reach prioritizes broad episode-level exposure.", "explode": false, "in": "query", "name": "sort", "schema": { "default": "ad_count", "description": "Sort order. ad_count ranks by ad volume on the publisher's catalog; podcast_coverage surfaces network buyers (sponsors hitting many shows); episode_reach prioritizes broad episode-level exposure.", "enum": [ "ad_count", "podcast_coverage", "episode_reach" ], "type": "string" } }, { "description": "Only return sponsors that appear on at least this many distinct podcasts in the publisher's catalog. Use to filter for bundle/network buyers.", "explode": false, "in": "query", "name": "min_podcast_coverage", "schema": { "description": "Only return sponsors that appear on at least this many distinct podcasts in the publisher's catalog. Use to filter for bundle/network buyers.", "format": "int64", "maximum": 500, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagePublisherSponsorEntry" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.04 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "List sponsors for a publisher", "tags": [ "Podcast Advertising", "tier:premium" ], "x-cost-weight": 3, "x-payment-info": { "offers": [ { "amount": "40000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.040000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "premium" } }, "/v1/podcasts/publishers/{id}/bias": { "get": { "description": "Returns political bias intelligence rolled up across every analyzed podcast attributed to the publisher: coverage stats, political share, average lean (on a -3..+3 ordinal scale), lean diversity, the bias-bucket and regional distributions, and the most recent evaluation timestamp. Score-based metrics are omitted when the publisher has no political podcasts.", "operationId": "get-podcast-publisher-bias", "parameters": [ { "description": "Podcast publisher slug (e.g., 'iheartpodcasts', 'npr', 'bbc-radio-4') or ID", "in": "path", "name": "id", "required": true, "schema": { "description": "Podcast publisher slug (e.g., 'iheartpodcasts', 'npr', 'bbc-radio-4') or ID", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastPublisherBiasProfile" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.03 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "Get publisher political bias profile", "tags": [ "Podcast Bias", "tier:premium" ], "x-cost-weight": 2, "x-payment-info": { "offers": [ { "amount": "30000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.030000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "premium" } }, "/v1/podcasts/publishers/{id}/bias/podcasts": { "get": { "description": "Returns a paginated list of the publisher's analyzed podcasts with their latest bias analysis attached. Supports filtering by bias bucket, political_context, and a toggle for excluding NOT_POLITICAL podcasts, plus sort by lean_score, evaluated_at, or name.", "operationId": "list-podcast-publisher-bias-podcasts", "parameters": [ { "description": "Results per page", "explode": false, "in": "query", "name": "limit", "schema": { "default": 25, "description": "Results per page", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque pagination cursor from previous response", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque pagination cursor from previous response", "type": "string" } }, { "description": "Podcast publisher slug (e.g., 'iheartpodcasts', 'npr', 'bbc-radio-4') or ID", "in": "path", "name": "id", "required": true, "schema": { "description": "Podcast publisher slug (e.g., 'iheartpodcasts', 'npr', 'bbc-radio-4') or ID", "type": "string" } }, { "description": "Filter to one or more bias buckets. Accepts NOT_POLITICAL, EXTREME_LEFT, LEFT, LEANS_LEFT, CENTER, LEANS_RIGHT, RIGHT, or EXTREME_RIGHT. To OR-filter multiple buckets, pass a comma-separated list (e.g. ?bias=LEFT,LEANS_LEFT).", "explode": false, "in": "query", "name": "bias", "schema": { "description": "Filter to one or more bias buckets. Accepts NOT_POLITICAL, EXTREME_LEFT, LEFT, LEANS_LEFT, CENTER, LEANS_RIGHT, RIGHT, or EXTREME_RIGHT. To OR-filter multiple buckets, pass a comma-separated list (e.g. ?bias=LEFT,LEANS_LEFT).", "items": { "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Restrict to podcasts whose latest analysis is calibrated against a single political framework.", "explode": false, "in": "query", "name": "political_context", "schema": { "description": "Restrict to podcasts whose latest analysis is calibrated against a single political framework.", "enum": [ "US", "UK", "EU", "CANADA", "AUSTRALIA", "INDIA", "OTHER", "UNKNOWN" ], "type": "string" } }, { "description": "When true (default), include podcasts whose latest result is NOT_POLITICAL. Set to false to restrict the response to podcasts the agent rated as political.", "explode": false, "in": "query", "name": "include_non_political", "schema": { "default": true, "description": "When true (default), include podcasts whose latest result is NOT_POLITICAL. Set to false to restrict the response to podcasts the agent rated as political.", "type": "boolean" } }, { "description": "Sort metric. lean_score orders on a -3 (extreme left) to +3 (extreme right) ordinal scale; evaluated_at by recency of analysis; name alphabetically.", "explode": false, "in": "query", "name": "sort", "schema": { "default": "lean_score", "description": "Sort metric. lean_score orders on a -3 (extreme left) to +3 (extreme right) ordinal scale; evaluated_at by recency of analysis; name alphabetically.", "enum": [ "lean_score", "evaluated_at", "name" ], "type": "string" } }, { "description": "Sort direction", "explode": false, "in": "query", "name": "order", "schema": { "default": "desc", "description": "Sort direction", "enum": [ "asc", "desc" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagePodcastBiasEntry" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.03 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "List analyzed podcasts for a publisher", "tags": [ "Podcast Bias", "tier:premium" ], "x-cost-weight": 2, "x-payment-info": { "offers": [ { "amount": "30000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.030000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "premium" } }, "/v1/podcasts/publishers/{id}/podcasts": { "get": { "description": "Returns a paginated list of podcasts attributed to a publisher, ordered by popularity. Identify the publisher by slug (e.g., 'goalhanger', 'iheartpodcasts', 'bbc-radio-4') or ID.", "operationId": "list-podcast-publisher-podcasts", "parameters": [ { "description": "Results per page", "explode": false, "in": "query", "name": "limit", "schema": { "default": 25, "description": "Results per page", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque pagination cursor from previous response", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque pagination cursor from previous response", "type": "string" } }, { "description": "Podcast publisher slug (e.g., 'goalhanger', 'iheartpodcasts', 'bbc-radio-4') or ID", "in": "path", "name": "id", "required": true, "schema": { "description": "Podcast publisher slug (e.g., 'goalhanger', 'iheartpodcasts', 'bbc-radio-4') or ID", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagePodcast" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.04 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "List podcasts for a publisher", "tags": [ "Podcast Publishers", "tier:standard" ], "x-cost-weight": 1, "x-payment-info": { "offers": [ { "amount": "40000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.040000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "standard" } }, "/v1/podcasts/publishers/{id}/suitability": { "get": { "description": "Returns a publisher-level rollup of IAB Tech Lab Brand Safety \u0026 Suitability Framework (formerly GARM) verdicts across the publisher's catalog: tier composition (SAFE / LIMITED / SENSITIVE / UNSAFE), confidence distribution, per-category exposure across all 12 GARM dimensions, and the top concerns surfaced from the category rollup. The coverage block (analyzed_coverage as a 0..1 share + a LOW/MEDIUM/HIGH quality enum) tells callers how representative the rollup is — analyses are still being backfilled across the long tail of the catalog. Identify the publisher by slug (e.g., 'iheartpodcasts', 'bbc-radio-4', 'bloomberg') or ID.", "operationId": "get-publisher-suitability", "parameters": [ { "description": "Podcast publisher slug (e.g., 'iheartpodcasts', 'bbc-radio-4', 'bloomberg') or ID. Slugs are the recommended identifier.", "in": "path", "name": "id", "required": true, "schema": { "description": "Podcast publisher slug (e.g., 'iheartpodcasts', 'bbc-radio-4', 'bloomberg') or ID. Slugs are the recommended identifier.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublisherSuitabilityProfile" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.04 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "Get a publisher's brand suitability profile", "tags": [ "Podcast Publishers", "tier:premium" ], "x-cost-weight": 3, "x-payment-info": { "offers": [ { "amount": "40000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.040000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "premium" } }, "/v1/podcasts/publishers/{id}/suitability/podcasts": { "get": { "description": "Returns a paginated list of the publisher's analyzed podcasts decorated with their latest IAB/GARM tier, confidence, evaluated-at timestamp, and any non-NONE category exposures (flagged categories). Filter by tier(s), by a specific GARM category (optionally constrained to a minimum prevalence and a particular treatment), and choose how to sort (most-risky first by default). Per-category reasoning and evidence excerpts are intentionally omitted — fetch GET /v1/podcasts/{id}/suitability for full per-category detail.", "operationId": "list-publisher-suitability-podcasts", "parameters": [ { "description": "Results per page", "explode": false, "in": "query", "name": "limit", "schema": { "default": 25, "description": "Results per page", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque pagination cursor from previous response", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque pagination cursor from previous response", "type": "string" } }, { "description": "Podcast publisher slug or ID.", "in": "path", "name": "id", "required": true, "schema": { "description": "Podcast publisher slug or ID.", "type": "string" } }, { "description": "Filter to podcasts whose latest verdict is in this tier set. To OR-filter multiple tiers, pass a comma-separated list (e.g. ?tier=UNSAFE,SENSITIVE).", "explode": false, "in": "query", "name": "tier", "schema": { "description": "Filter to podcasts whose latest verdict is in this tier set. To OR-filter multiple tiers, pass a comma-separated list (e.g. ?tier=UNSAFE,SENSITIVE).", "items": { "enum": [ "SAFE", "LIMITED", "SENSITIVE", "UNSAFE" ], "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Filter to podcasts whose latest assessment shows non-NONE exposure in this GARM category.", "explode": false, "in": "query", "name": "category", "schema": { "description": "Filter to podcasts whose latest assessment shows non-NONE exposure in this GARM category.", "enum": [ "adult_sexual", "arms_ammunition", "crime_harmful_acts", "death_injury_military_conflict", "online_piracy", "hate_speech_aggression", "obscenity_profanity", "illegal_drugs_alcohol_tobacco", "spam_harmful", "terrorism", "debated_social_issues", "misinformation" ], "type": "string" } }, { "description": "When combined with category, filter to podcasts whose prevalence in that category is at or above this threshold. Defaults to INCIDENTAL — any non-NONE prevalence. Ignored without category.", "explode": false, "in": "query", "name": "min_prevalence", "schema": { "default": "INCIDENTAL", "description": "When combined with category, filter to podcasts whose prevalence in that category is at or above this threshold. Defaults to INCIDENTAL — any non-NONE prevalence. Ignored without category.", "enum": [ "INCIDENTAL", "OCCASIONAL", "FREQUENT", "PERVASIVE" ], "type": "string" } }, { "description": "When combined with category, filter to podcasts whose treatment in that category equals this value. Ignored without category.", "explode": false, "in": "query", "name": "treatment", "schema": { "description": "When combined with category, filter to podcasts whose treatment in that category equals this value. Ignored without category.", "enum": [ "DOCUMENTARY", "EDITORIAL", "PROMOTIONAL", "GLAMORIZING" ], "type": "string" } }, { "description": "Sort order. risk_desc ranks the most-risky first (UNSAFE → SAFE); risk_asc inverts that; recently_evaluated sorts by most-recent assessment first.", "explode": false, "in": "query", "name": "sort", "schema": { "default": "risk_desc", "description": "Sort order. risk_desc ranks the most-risky first (UNSAFE → SAFE); risk_asc inverts that; recently_evaluated sorts by most-recent assessment first.", "enum": [ "risk_desc", "risk_asc", "recently_evaluated" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagePublisherSuitabilityPodcastEntry" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.03 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "List a publisher's podcasts with their suitability verdicts", "tags": [ "Podcast Publishers", "tier:premium" ], "x-cost-weight": 2, "x-payment-info": { "offers": [ { "amount": "30000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.030000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "premium" } }, "/v1/podcasts/rankings": { "get": { "description": "Returns chart entries from the live ranking snapshot. The most common call needs no parameters — it returns the first page (default 25, max 100 per request) of the US Apple Top Podcasts overall chart, ordered by rank ascending. Charts run to rank 200; paginate with `cursor` to fetch the rest. Narrow the result with `country`, `category_slug`, `source`, or `podcast_id`. When `podcast_id` is set, the response is the podcast's current chart appearances across the matching slots.", "operationId": "list-podcast-rankings", "parameters": [ { "description": "Results per page", "explode": false, "in": "query", "name": "limit", "schema": { "default": 25, "description": "Results per page", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque pagination cursor from previous response", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque pagination cursor from previous response", "type": "string" } }, { "description": "Ranking source platform. Use GET /v1/podcasts/rankings/sources to enumerate available sources.", "explode": false, "in": "query", "name": "source", "schema": { "default": "apple", "description": "Ranking source platform. Use GET /v1/podcasts/rankings/sources to enumerate available sources.", "enum": [ "apple", "spotify" ], "type": "string" } }, { "description": "Chart variant within the source. Currently only 'top_podcasts' is supported.", "explode": false, "in": "query", "name": "chart_type", "schema": { "default": "top_podcasts", "description": "Chart variant within the source. Currently only 'top_podcasts' is supported.", "enum": [ "top_podcasts" ], "type": "string" } }, { "description": "ISO 3166-1 alpha-2 country code (e.g. 'us', 'gb', 'jp'). Case-insensitive on input — normalized to lowercase server-side.", "explode": false, "in": "query", "name": "country", "schema": { "default": "us", "description": "ISO 3166-1 alpha-2 country code (e.g. 'us', 'gb', 'jp'). Case-insensitive on input — normalized to lowercase server-side.", "maxLength": 2, "minLength": 2, "type": "string" } }, { "description": "Category slug (e.g. 'comedy', 'business'). Omit for the overall chart.", "explode": false, "in": "query", "name": "category_slug", "schema": { "description": "Category slug (e.g. 'comedy', 'business'). Omit for the overall chart.", "type": "string" } }, { "description": "Restrict to chart appearances of a single podcast (slug, internal ID, or numeric iTunes ID). When set, the chart-slot filters narrow the result; without them every current chart appearance for the podcast is returned across slots.", "explode": false, "in": "query", "name": "podcast_id", "schema": { "description": "Restrict to chart appearances of a single podcast (slug, internal ID, or numeric iTunes ID). When set, the chart-slot filters narrow the result; without them every current chart appearance for the podcast is returned across slots.", "type": "string" } }, { "description": "Minimum rank (inclusive). Useful for slicing the chart (e.g. min_rank=11\u0026max_rank=20 for ranks 11–20).", "explode": false, "in": "query", "name": "min_rank", "schema": { "description": "Minimum rank (inclusive). Useful for slicing the chart (e.g. min_rank=11\u0026max_rank=20 for ranks 11–20).", "format": "int64", "maximum": 500, "minimum": 1, "type": "integer" } }, { "description": "Maximum rank (inclusive).", "explode": false, "in": "query", "name": "max_rank", "schema": { "description": "Maximum rank (inclusive).", "format": "int64", "maximum": 500, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagePodcastRanking" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.03 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "List podcast rankings", "tags": [ "Podcast Rankings", "tier:premium" ], "x-cost-weight": 2, "x-payment-info": { "offers": [ { "amount": "30000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.030000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "premium" } }, "/v1/podcasts/rankings/categories": { "get": { "description": "Returns every category currently represented in the rankings dataset, optionally restricted to a single source. For Apple sub-categories the response includes `parent_slug` so clients can render the category hierarchy.", "operationId": "list-podcast-ranking-categories", "parameters": [ { "description": "Results per page (default: all)", "explode": false, "in": "query", "name": "limit", "schema": { "description": "Results per page (default: all)", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque pagination cursor from previous response", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque pagination cursor from previous response", "type": "string" } }, { "description": "Restrict the listing to one source. Omit to return categories with current data from any source.", "explode": false, "in": "query", "name": "source", "schema": { "description": "Restrict the listing to one source. Omit to return categories with current data from any source.", "enum": [ "apple", "spotify" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagePodcastRankingCategory" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.01 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "List ranking categories", "tags": [ "Podcast Rankings", "tier:standard" ], "x-cost-weight": 1, "x-payment-info": { "offers": [ { "amount": "10000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.010000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "standard" } }, "/v1/podcasts/rankings/countries": { "get": { "description": "Returns every country currently represented in the rankings dataset, optionally restricted to a single source. Each entry carries the human-readable country name (when known) and a count of distinct chart slots.", "operationId": "list-podcast-ranking-countries", "parameters": [ { "description": "Results per page (default: all)", "explode": false, "in": "query", "name": "limit", "schema": { "description": "Results per page (default: all)", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque pagination cursor from previous response", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque pagination cursor from previous response", "type": "string" } }, { "description": "Restrict the listing to one source. Omit to return countries with current data from any source.", "explode": false, "in": "query", "name": "source", "schema": { "description": "Restrict the listing to one source. Omit to return countries with current data from any source.", "enum": [ "apple", "spotify" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagePodcastRankingCountry" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.01 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "List ranking countries", "tags": [ "Podcast Rankings", "tier:standard" ], "x-cost-weight": 1, "x-payment-info": { "offers": [ { "amount": "10000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.010000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "standard" } }, "/v1/podcasts/rankings/history": { "get": { "description": "Returns historical chart snapshots for a chart slot, ordered most-recent first. Set `since` / `until` to bound the time range; set `podcast_id` to filter to one podcast within the slot.", "operationId": "get-podcast-rankings-history", "parameters": [ { "description": "Results per page", "explode": false, "in": "query", "name": "limit", "schema": { "default": 25, "description": "Results per page", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque pagination cursor from previous response", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque pagination cursor from previous response", "type": "string" } }, { "description": "Ranking source platform.", "explode": false, "in": "query", "name": "source", "schema": { "default": "apple", "description": "Ranking source platform.", "enum": [ "apple", "spotify" ], "type": "string" } }, { "description": "Chart variant within the source.", "explode": false, "in": "query", "name": "chart_type", "schema": { "default": "top_podcasts", "description": "Chart variant within the source.", "enum": [ "top_podcasts" ], "type": "string" } }, { "description": "ISO 3166-1 alpha-2 country code; case-insensitive on input.", "explode": false, "in": "query", "name": "country", "schema": { "default": "us", "description": "ISO 3166-1 alpha-2 country code; case-insensitive on input.", "maxLength": 2, "minLength": 2, "type": "string" } }, { "description": "Category slug. Omit for the overall chart.", "explode": false, "in": "query", "name": "category_slug", "schema": { "description": "Category slug. Omit for the overall chart.", "type": "string" } }, { "description": "Restrict to one podcast across the chart slot's history.", "explode": false, "in": "query", "name": "podcast_id", "schema": { "description": "Restrict to one podcast across the chart slot's history.", "type": "string" } }, { "description": "Lower bound on captured_at (ISO 8601). Omit for no lower bound.", "explode": false, "in": "query", "name": "since", "schema": { "description": "Lower bound on captured_at (ISO 8601). Omit for no lower bound.", "examples": [ "2025-01-01T00:00:00Z" ], "type": "string" } }, { "description": "Upper bound on captured_at (ISO 8601). Omit for no upper bound.", "explode": false, "in": "query", "name": "until", "schema": { "description": "Upper bound on captured_at (ISO 8601). Omit for no upper bound.", "examples": [ "2026-01-01T00:00:00Z" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagePodcastRanking" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.04 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "Get chart slot history", "tags": [ "Podcast Rankings", "tier:premium" ], "x-cost-weight": 2, "x-payment-info": { "offers": [ { "amount": "40000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.040000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "premium" } }, "/v1/podcasts/rankings/movers": { "get": { "description": "Returns the chart entries whose rank changed between the live snapshot and the comparison snapshot `window_days` ago. Use the `change` filter to focus on debuts (`new`), departures (`exit`), or directional moves (`up` / `down`). Stable rows are excluded.", "operationId": "list-podcast-ranking-movers", "parameters": [ { "description": "Ranking source platform.", "explode": false, "in": "query", "name": "source", "schema": { "default": "apple", "description": "Ranking source platform.", "enum": [ "apple", "spotify" ], "type": "string" } }, { "description": "Chart variant within the source.", "explode": false, "in": "query", "name": "chart_type", "schema": { "default": "top_podcasts", "description": "Chart variant within the source.", "enum": [ "top_podcasts" ], "type": "string" } }, { "description": "ISO 3166-1 alpha-2 country code; case-insensitive on input.", "explode": false, "in": "query", "name": "country", "schema": { "default": "us", "description": "ISO 3166-1 alpha-2 country code; case-insensitive on input.", "maxLength": 2, "minLength": 2, "type": "string" } }, { "description": "Category slug. Omit for the overall chart.", "explode": false, "in": "query", "name": "category_slug", "schema": { "description": "Category slug. Omit for the overall chart.", "type": "string" } }, { "description": "Comparison window in days. The comparison snapshot is the most recent retired snapshot closest to (now - window_days). Default is 1 (vs. yesterday).", "explode": false, "in": "query", "name": "window_days", "schema": { "default": 1, "description": "Comparison window in days. The comparison snapshot is the most recent retired snapshot closest to (now - window_days). Default is 1 (vs. yesterday).", "format": "int64", "maximum": 30, "minimum": 1, "type": "integer" } }, { "description": "Filter by change type. 'up' / 'down' for podcasts whose rank moved, 'new' for chart debuts, 'exit' for podcasts that fell off, 'all' returns every change type.", "explode": false, "in": "query", "name": "change", "schema": { "default": "all", "description": "Filter by change type. 'up' / 'down' for podcasts whose rank moved, 'new' for chart debuts, 'exit' for podcasts that fell off, 'all' returns every change type.", "enum": [ "all", "up", "down", "new", "exit" ], "type": "string" } }, { "description": "Maximum number of movers to return.", "explode": false, "in": "query", "name": "limit", "schema": { "default": 25, "description": "Maximum number of movers to return.", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagePodcastRankingMover" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.04 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "List ranking movers", "tags": [ "Podcast Rankings", "tier:premium" ], "x-cost-weight": 2, "x-payment-info": { "offers": [ { "amount": "40000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.040000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "premium" } }, "/v1/podcasts/rankings/sources": { "get": { "description": "Returns each (source, chart_type) pair available on this API together with row counts and freshness for the live snapshot.", "operationId": "list-podcast-ranking-sources", "parameters": [ { "description": "Results per page (default: all)", "explode": false, "in": "query", "name": "limit", "schema": { "description": "Results per page (default: all)", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque pagination cursor from previous response", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque pagination cursor from previous response", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagePodcastRankingSource" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.01 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "List ranking sources", "tags": [ "Podcast Rankings", "tier:standard" ], "x-cost-weight": 1, "x-payment-info": { "offers": [ { "amount": "10000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.010000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "standard" } }, "/v1/podcasts/search": { "get": { "description": "Searches the podcast catalog by show name — the canonical podcast search. Functionally equivalent to `GET /v1/podcasts?q=…`: the same forgiving, typo-tolerant ranked search, the same filters (topic, language, suitability tier, popularity, format), and the same `match_quality` signal on each result. To search *inside* episode dialogue, use `/v1/podcasts/episodes/search` instead.", "operationId": "search-podcasts", "parameters": [ { "description": "Results per page", "explode": false, "in": "query", "name": "limit", "schema": { "default": 25, "description": "Results per page", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque pagination cursor from previous response", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque pagination cursor from previous response", "type": "string" } }, { "description": "Search the catalog by podcast name. GET /v1/podcasts/search is the canonical search endpoint and accepts the same parameters. The search is forgiving: it handles typos, missing or extra words ('offline jon favreau' finds Offline with Jon Favreau), a name plus qualifiers ('equity techcrunch'), and pasted episode titles ('Ferrari | Acquired' finds Acquired). The best matches come first, and each result's match_quality tells you how confident the match is — including when a show matched only through its description (match_quality=description) rather than its name.", "explode": false, "in": "query", "name": "q", "schema": { "description": "Search the catalog by podcast name. GET /v1/podcasts/search is the canonical search endpoint and accepts the same parameters. The search is forgiving: it handles typos, missing or extra words ('offline jon favreau' finds Offline with Jon Favreau), a name plus qualifiers ('equity techcrunch'), and pasted episode titles ('Ferrari | Acquired' finds Acquired). The best matches come first, and each result's match_quality tells you how confident the match is — including when a show matched only through its description (match_quality=description) rather than its name.", "maxLength": 200, "type": "string" } }, { "description": "Result ordering. relevance — the default whenever q is present — ranks by how well each podcast matches the query, breaking ties by popularity. popularity orders purely by the global popularity percentile (most popular first; podcasts not currently charting sort last), and also overrides topic_id's concentration ordering. Without q or topic_id, results are popularity-ordered either way.", "explode": false, "in": "query", "name": "sort", "schema": { "description": "Result ordering. relevance — the default whenever q is present — ranks by how well each podcast matches the query, breaking ties by popularity. popularity orders purely by the global popularity percentile (most popular first; podcasts not currently charting sort last), and also overrides topic_id's concentration ordering. Without q or topic_id, results are popularity-ordered either way.", "enum": [ "relevance", "popularity" ], "type": "string" } }, { "description": "Filter by exact podcast slug (e.g., 'all-in'). Slugs are stable, human-readable identifiers returned on every podcast object.", "explode": false, "in": "query", "name": "slug", "schema": { "description": "Filter by exact podcast slug (e.g., 'all-in'). Slugs are stable, human-readable identifiers returned on every podcast object.", "maxLength": 200, "type": "string" } }, { "description": "Filter by topic ID, ancestry slug (e.g., technology/artificial-intelligence), or ancestry path hash. Matches podcasts where the topic accounts for at least 20% of the show's episodes, ranked by topic concentration — not merely podcasts that mention it once.", "explode": false, "in": "query", "name": "topic_id", "schema": { "description": "Filter by topic ID, ancestry slug (e.g., technology/artificial-intelligence), or ancestry path hash. Matches podcasts where the topic accounts for at least 20% of the show's episodes, ranked by topic concentration — not merely podcasts that mention it once.", "type": "string" } }, { "description": "Filter by the podcast's language (ISO 639-1 code, e.g. 'en', 'fr'). Matches the primary language subtag, so 'fr' covers 'fr-FR'.", "explode": false, "in": "query", "name": "language", "schema": { "description": "Filter by the podcast's language (ISO 639-1 code, e.g. 'en', 'fr'). Matches the primary language subtag, so 'fr' covers 'fr-FR'.", "examples": [ "fr" ], "type": "string" } }, { "description": "Filter by brand-suitability tier (IAB Tech Lab Brand Safety \u0026 Suitability Framework, formerly GARM). Only returns podcasts whose most recent suitability analysis assigned this tier. Podcasts without a suitability analysis are excluded when this filter is set.", "explode": false, "in": "query", "name": "suitability_tier", "schema": { "description": "Filter by brand-suitability tier (IAB Tech Lab Brand Safety \u0026 Suitability Framework, formerly GARM). Only returns podcasts whose most recent suitability analysis assigned this tier. Podcasts without a suitability analysis are excluded when this filter is set.", "enum": [ "SAFE", "LIMITED", "SENSITIVE", "UNSAFE" ], "type": "string" } }, { "description": "Restrict results to podcasts whose global popularity percentile is at least this value (accepted range [0,1]). Omitting the parameter or passing 0 disables the filter; only a value greater than 0 activates it. Popularity is always global — a cume_dist ranking over all currently-charting podcasts (Apple Podcasts) — never scoped to topic_id or any other filter. When the filter is active (threshold \u003e 0), podcasts not currently charting have no percentile and are excluded, so a high threshold combined with a narrow topic_id may return zero results; lower or remove the threshold to widen the set.", "explode": false, "in": "query", "name": "popularity_threshold", "schema": { "description": "Restrict results to podcasts whose global popularity percentile is at least this value (accepted range [0,1]). Omitting the parameter or passing 0 disables the filter; only a value greater than 0 activates it. Popularity is always global — a cume_dist ranking over all currently-charting podcasts (Apple Podcasts) — never scoped to topic_id or any other filter. When the filter is active (threshold \u003e 0), podcasts not currently charting have no percentile and are excluded, so a high threshold combined with a narrow topic_id may return zero results; lower or remove the threshold to widen the set.", "format": "double", "maximum": 1, "minimum": 0, "type": "number" } }, { "description": "Filter by how often episodes feature a guest. Pass a comma-separated list to match any of several buckets — e.g. regular,always for interview-driven shows, or never for shows that don't host guests. Only matches podcasts with enough analyzed episodes to judge; values mirror the format.guest_frequency field on podcast responses.", "explode": false, "in": "query", "name": "guest_frequency", "schema": { "description": "Filter by how often episodes feature a guest. Pass a comma-separated list to match any of several buckets — e.g. regular,always for interview-driven shows, or never for shows that don't host guests. Only matches podcasts with enough analyzed episodes to judge; values mirror the format.guest_frequency field on podcast responses.", "examples": [ [ "regular", "always" ] ], "items": { "enum": [ "never", "rare", "occasional", "regular", "always" ], "type": "string" }, "maxItems": 5, "type": [ "array", "null" ] } }, { "description": "Filter by detected production format. Pass a comma-separated list to match any of several formats — e.g. panel,call_in. Values mirror the format.signals field on podcast responses; a show can carry several signals.", "explode": false, "in": "query", "name": "format_signal", "schema": { "description": "Filter by detected production format. Pass a comma-separated list to match any of several formats — e.g. panel,call_in. Values mirror the format.signals field on podcast responses; a show can carry several signals.", "examples": [ [ "interview" ] ], "items": { "enum": [ "interview", "panel", "call_in", "solo_narrated" ], "type": "string" }, "maxItems": 4, "type": [ "array", "null" ] } }, { "description": "Filter by advertiser presence. Pass false to find ad-free shows — an assertion that requires the show to have enough analyzed episodes, so sparsely-analyzed podcasts are excluded rather than presumed ad-free.", "explode": false, "in": "query", "name": "has_ads", "schema": { "description": "Filter by advertiser presence. Pass false to find ad-free shows — an assertion that requires the show to have enough analyzed episodes, so sparsely-analyzed podcasts are excluded rather than presumed ad-free.", "enum": [ "true", "false" ], "type": "string" } }, { "description": "Filter by whether episodes have discovered video versions (e.g. YouTube releases).", "explode": false, "in": "query", "name": "has_video", "schema": { "description": "Filter by whether episodes have discovered video versions (e.g. YouTube releases).", "enum": [ "true", "false" ], "type": "string" } }, { "description": "Only podcasts whose average episode runs at least this many minutes. Combine with max_avg_episode_minutes to target a length band (e.g. 20–40 minute commute shows).", "explode": false, "in": "query", "name": "min_avg_episode_minutes", "schema": { "description": "Only podcasts whose average episode runs at least this many minutes. Combine with max_avg_episode_minutes to target a length band (e.g. 20–40 minute commute shows).", "format": "int64", "maximum": 10080, "minimum": 0, "type": "integer" } }, { "description": "Only podcasts whose average episode runs at most this many minutes.", "explode": false, "in": "query", "name": "max_avg_episode_minutes", "schema": { "description": "Only podcasts whose average episode runs at most this many minutes.", "format": "int64", "maximum": 10080, "minimum": 0, "type": "integer" } }, { "description": "Only podcasts publishing at least this many episodes per week on average (e.g. 5 for weekday dailies). Cadence is measured over the trailing 90 days; podcasts tracked too briefly to measure are excluded.", "explode": false, "in": "query", "name": "min_episodes_per_week", "schema": { "description": "Only podcasts publishing at least this many episodes per week on average (e.g. 5 for weekday dailies). Cadence is measured over the trailing 90 days; podcasts tracked too briefly to measure are excluded.", "format": "double", "minimum": 0, "type": "number" } }, { "description": "Only podcasts publishing at most this many episodes per week on average (e.g. 0.5 for fortnightly-or-slower shows).", "explode": false, "in": "query", "name": "max_episodes_per_week", "schema": { "description": "Only podcasts publishing at most this many episodes per week on average (e.g. 0.5 for fortnightly-or-slower shows).", "format": "double", "minimum": 0, "type": "number" } }, { "description": "Filter by publishing activity: active shows have released an episode within the last 90 days; dormant shows have not.", "explode": false, "in": "query", "name": "publishing_status", "schema": { "description": "Filter by publishing activity: active shows have released an episode within the last 90 days; dormant shows have not.", "enum": [ "active", "dormant" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagePodcast" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.01 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "Search podcasts", "tags": [ "Podcasts", "tier:standard" ], "x-cost-weight": 1, "x-payment-info": { "offers": [ { "amount": "10000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.010000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "standard" } }, "/v1/podcasts/segments": { "get": { "description": "Returns AI-identified segments across podcast episodes. Segments represent structural sections like topic discussions, interviews, ads, etc. At least one of `episode_id`, `podcast_id`, or `type` is required — this endpoint does not return a global feed.", "operationId": "list-segments", "parameters": [ { "description": "Results per page", "explode": false, "in": "query", "name": "limit", "schema": { "default": 25, "description": "Results per page", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque pagination cursor from previous response", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque pagination cursor from previous response", "type": "string" } }, { "description": "Filter to a specific episode by slug or ID. At least one of episode_id, podcast_id, or type is required.", "explode": false, "in": "query", "name": "episode_id", "schema": { "description": "Filter to a specific episode by slug or ID. At least one of episode_id, podcast_id, or type is required.", "type": "string" } }, { "description": "Podcast slug (e.g., 'all-in'), internal ID, or numeric iTunes ID. At least one of episode_id, podcast_id, or type is required.", "explode": false, "in": "query", "name": "podcast_id", "schema": { "description": "Podcast slug (e.g., 'all-in'), internal ID, or numeric iTunes ID. At least one of episode_id, podcast_id, or type is required.", "type": "string" } }, { "description": "Segment type filter: INTRO, PERSONAL_BANTER, TOPIC_DISCUSSION, INTERVIEW, TRANSITION, AD, OUTRO. At least one of episode_id, podcast_id, or type is required.", "explode": false, "in": "query", "name": "type", "schema": { "description": "Segment type filter: INTRO, PERSONAL_BANTER, TOPIC_DISCUSSION, INTERVIEW, TRANSITION, AD, OUTRO. At least one of episode_id, podcast_id, or type is required.", "type": "string" } }, { "description": "Only include segments from episodes published on or after this ISO 8601 date or date-time", "explode": false, "in": "query", "name": "since", "schema": { "description": "Only include segments from episodes published on or after this ISO 8601 date or date-time", "examples": [ "2025-01-01T00:00:00Z" ], "type": "string" } }, { "description": "Only include segments from episodes published before this ISO 8601 date or date-time", "explode": false, "in": "query", "name": "until", "schema": { "description": "Only include segments from episodes published before this ISO 8601 date or date-time", "examples": [ "2026-01-01T00:00:00Z" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageSegment" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.01 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "List segments", "tags": [ "Podcast Segments", "tier:standard" ], "x-cost-weight": 1, "x-payment-info": { "offers": [ { "amount": "10000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.010000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "standard" } }, "/v1/podcasts/segments/{id}": { "get": { "description": "Returns a single segment by its unique identifier.", "operationId": "get-segment", "parameters": [ { "description": "Segment ID", "in": "path", "name": "id", "required": true, "schema": { "description": "Segment ID", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Segment" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.01 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "Get a segment", "tags": [ "Podcast Segments", "tier:standard" ], "x-cost-weight": 1, "x-payment-info": { "offers": [ { "amount": "10000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.010000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "standard" } }, "/v1/podcasts/segments/{id}/transcript": { "get": { "description": "Returns the diarized transcript for a specific segment.", "operationId": "get-segment-transcript", "parameters": [ { "description": "Segment ID", "in": "path", "name": "id", "required": true, "schema": { "description": "Segment ID", "type": "string" } }, { "description": "Output format", "explode": false, "in": "query", "name": "format", "schema": { "default": "dialogue", "description": "Output format", "enum": [ "dialogue", "text", "srt" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.03 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "Get segment transcript", "tags": [ "Podcast Transcripts", "tier:standard" ], "x-cost-weight": 1, "x-payment-info": { "offers": [ { "amount": "30000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.030000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "standard" } }, "/v1/podcasts/stats": { "get": { "description": "Returns live, catalog-wide statistics: how many podcasts the catalog covers, broken out by classification, how many episodes were added within recent trailing windows, and how many episodes are transcribed and how many more in podcasts' back catalogues are requestable. The podcast and added counts update as new podcasts and episodes are ingested and are cached for up to a minute, so they can drive live counters; the episode totals refresh hourly. This endpoint is free and requires no API key.", "operationId": "get-podcast-stats", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastStats" } } }, "description": "OK" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [], "summary": "Get podcast catalog statistics", "tags": [ "Podcasts", "tier:free" ], "x-cost-weight": 0, "x-tier": "free" } }, "/v1/podcasts/suitability/categories/{code}/publishers": { "get": { "description": "For one of the 12 GARM brand-safety categories, returns a paginated ranking of podcast publishers by exposure across their catalog. The killer view for regulated brands: an alcohol advertiser pivots on illegal_drugs_alcohol_tobacco and immediately sees which publishers carry the highest catalog-level exposure (and at what prevalence + treatment); a family brand pivots on adult_sexual or hate_speech_aggression to build an exclusion list. min_prevalence + treatment narrow what counts as 'exposed'. Each row includes prevalence + treatment breakdowns and up to three example podcasts in the publisher's catalog that exhibit the highest exposure.", "operationId": "get-category-publishers", "parameters": [ { "description": "Results per page", "explode": false, "in": "query", "name": "limit", "schema": { "default": 25, "description": "Results per page", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque pagination cursor from previous response", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque pagination cursor from previous response", "type": "string" } }, { "description": "The GARM brand-safety category code to pivot on (IAB Tech Lab Content Taxonomy 3.x). One of: adult_sexual, arms_ammunition, crime_harmful_acts, death_injury_military_conflict, online_piracy, hate_speech_aggression, obscenity_profanity, illegal_drugs_alcohol_tobacco, spam_harmful, terrorism, debated_social_issues, misinformation.", "in": "path", "name": "code", "required": true, "schema": { "description": "The GARM brand-safety category code to pivot on (IAB Tech Lab Content Taxonomy 3.x). One of: adult_sexual, arms_ammunition, crime_harmful_acts, death_injury_military_conflict, online_piracy, hate_speech_aggression, obscenity_profanity, illegal_drugs_alcohol_tobacco, spam_harmful, terrorism, debated_social_issues, misinformation.", "enum": [ "adult_sexual", "arms_ammunition", "crime_harmful_acts", "death_injury_military_conflict", "online_piracy", "hate_speech_aggression", "obscenity_profanity", "illegal_drugs_alcohol_tobacco", "spam_harmful", "terrorism", "debated_social_issues", "misinformation" ], "type": "string" } }, { "description": "Sort order. most_exposed ranks publishers whose analyzed catalog has the highest *share* of exposure to the category (exposure_share, desc), with absolute exposed_count and publisher_id as deterministic tiebreakers. least_exposed inverts the share ordering. Use min_analyzed_podcasts to guard against tiny catalogs dominating the share-based ranking.", "explode": false, "in": "query", "name": "direction", "schema": { "default": "most_exposed", "description": "Sort order. most_exposed ranks publishers whose analyzed catalog has the highest *share* of exposure to the category (exposure_share, desc), with absolute exposed_count and publisher_id as deterministic tiebreakers. least_exposed inverts the share ordering. Use min_analyzed_podcasts to guard against tiny catalogs dominating the share-based ranking.", "enum": [ "most_exposed", "least_exposed" ], "type": "string" } }, { "description": "Only count a podcast as 'exposed' when its prevalence in the category is at or above this threshold. Defaults to INCIDENTAL — any non-NONE prevalence.", "explode": false, "in": "query", "name": "min_prevalence", "schema": { "default": "INCIDENTAL", "description": "Only count a podcast as 'exposed' when its prevalence in the category is at or above this threshold. Defaults to INCIDENTAL — any non-NONE prevalence.", "enum": [ "INCIDENTAL", "OCCASIONAL", "FREQUENT", "PERVASIVE" ], "type": "string" } }, { "description": "When set, only count exposures whose treatment equals this value. Useful for surfacing publishers with PROMOTIONAL or GLAMORIZING treatment in a regulated category.", "explode": false, "in": "query", "name": "treatment", "schema": { "description": "When set, only count exposures whose treatment equals this value. Useful for surfacing publishers with PROMOTIONAL or GLAMORIZING treatment in a regulated category.", "enum": [ "DOCUMENTARY", "EDITORIAL", "PROMOTIONAL", "GLAMORIZING" ], "type": "string" } }, { "description": "Exclude publishers with fewer than this many analyzed podcasts.", "explode": false, "in": "query", "name": "min_analyzed_podcasts", "schema": { "default": 5, "description": "Exclude publishers with fewer than this many analyzed podcasts.", "format": "int64", "maximum": 1000, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagePublisherSuitabilityCategoryPublisherEntry" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.04 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "Get publishers ranked by exposure to a brand-safety category", "tags": [ "Podcast Brand Suitability", "tier:premium" ], "x-cost-weight": 3, "x-payment-info": { "offers": [ { "amount": "40000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.040000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "premium" } }, "/v1/podcasts/suitability/publishers/leaderboard": { "get": { "description": "Returns a paginated, ranked list of podcast publishers by IAB/GARM brand-suitability composition. Pick a metric (safest, riskiest, most_placeable, most_analyzed) to choose how the ranking is constructed. min_analyzed_podcasts guards against tiny catalogs dominating share-based metrics. The ranking reflects each publisher's current catalog composition; paginate the audit history per show via GET /v1/podcasts/{id}/suitability?include=history when you need point-in-time analysis. Each row carries the full tier_breakdown (counts + shares) plus the metric_value the row was ranked by.", "operationId": "get-publisher-suitability-leaderboard", "parameters": [ { "description": "Results per page", "explode": false, "in": "query", "name": "limit", "schema": { "default": 25, "description": "Results per page", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque pagination cursor from previous response", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque pagination cursor from previous response", "type": "string" } }, { "description": "How to rank publishers. safest sorts by SAFE share of the analyzed catalog (desc); riskiest sorts by UNSAFE share (desc); most_placeable sorts by combined SAFE + LIMITED share (desc) — the 'broadly buyable' slice; most_analyzed sorts by absolute analyzed_podcasts count (desc).", "explode": false, "in": "query", "name": "metric", "schema": { "default": "safest", "description": "How to rank publishers. safest sorts by SAFE share of the analyzed catalog (desc); riskiest sorts by UNSAFE share (desc); most_placeable sorts by combined SAFE + LIMITED share (desc) — the 'broadly buyable' slice; most_analyzed sorts by absolute analyzed_podcasts count (desc).", "enum": [ "safest", "riskiest", "most_placeable", "most_analyzed" ], "type": "string" } }, { "description": "Exclude publishers with fewer than this many analyzed podcasts. Guards against tiny catalogs dominating share-based metrics.", "explode": false, "in": "query", "name": "min_analyzed_podcasts", "schema": { "default": 5, "description": "Exclude publishers with fewer than this many analyzed podcasts. Guards against tiny catalogs dominating share-based metrics.", "format": "int64", "maximum": 1000, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagePublisherSuitabilityLeaderboardEntry" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.04 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "Get a cross-publisher suitability leaderboard", "tags": [ "Podcast Brand Suitability", "tier:premium" ], "x-cost-weight": 3, "x-payment-info": { "offers": [ { "amount": "40000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.040000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "premium" } }, "/v1/podcasts/topics": { "get": { "description": "Returns the top-level topics covered across all podcasts, sorted by the number of podcasts covering each topic.", "operationId": "list-podcast-topics", "parameters": [ { "description": "Results per page", "explode": false, "in": "query", "name": "limit", "schema": { "default": 25, "description": "Results per page", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque pagination cursor from previous response", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque pagination cursor from previous response", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagePodcastTopic" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.03 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "List podcast topics", "tags": [ "Podcasts", "tier:standard" ], "x-cost-weight": 1, "x-payment-info": { "offers": [ { "amount": "30000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.030000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "standard" } }, "/v1/podcasts/{id}": { "get": { "description": "Returns a single podcast by slug (e.g., 'all-in') or ID. Slugs are human-readable identifiers included in every podcast response.", "operationId": "get-podcast", "parameters": [ { "description": "Podcast slug (e.g., 'all-in', 'lex-fridman-podcast'), internal ID, or numeric iTunes ID", "in": "path", "name": "id", "required": true, "schema": { "description": "Podcast slug (e.g., 'all-in', 'lex-fridman-podcast'), internal ID, or numeric iTunes ID", "type": "string" } }, { "description": "Maximum number of aggregated topics to return (0 for none, max 1000)", "explode": false, "in": "query", "name": "topic_limit", "schema": { "default": 10, "description": "Maximum number of aggregated topics to return (0 for none, max 1000)", "format": "int64", "maximum": 1000, "minimum": 0, "type": "integer" } }, { "description": "Optional response sections. related attaches the five most related podcasts (lean form); recommended_guests the five guests the show could book next; recommended_sponsors (premium-grade, requires a plan with premium endpoints) the five advertisers active on shows like this one that do not buy it yet. Each has a paged endpoint for the full list: /related, /recommendations/guests, /recommendations/sponsors. coverage attaches how much of the show's history we know of and have transcribed, including its back catalogue.", "explode": false, "in": "query", "name": "include", "schema": { "description": "Optional response sections. related attaches the five most related podcasts (lean form); recommended_guests the five guests the show could book next; recommended_sponsors (premium-grade, requires a plan with premium endpoints) the five advertisers active on shows like this one that do not buy it yet. Each has a paged endpoint for the full list: /related, /recommendations/guests, /recommendations/sponsors. coverage attaches how much of the show's history we know of and have transcribed, including its back catalogue.", "items": { "enum": [ "related", "recommended_guests", "recommended_sponsors", "coverage" ], "type": "string" }, "type": [ "array", "null" ] } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Podcast" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.01 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "Get a podcast", "tags": [ "Podcasts", "tier:standard" ], "x-cost-weight": 1, "x-payment-info": { "offers": [ { "amount": "10000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.010000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "standard" } }, "/v1/podcasts/{id}/advertising": { "get": { "description": "Returns advertising intelligence for a specific podcast, including aggregate stats, read type breakdown, and top sponsors. Identify the podcast by slug (e.g., 'all-in') or ID.", "operationId": "get-podcast-advertising", "parameters": [ { "description": "Podcast slug (e.g., 'all-in'), internal ID, or numeric iTunes ID", "in": "path", "name": "id", "required": true, "schema": { "description": "Podcast slug (e.g., 'all-in'), internal ID, or numeric iTunes ID", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastAdvertisingProfile" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.03 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "Get podcast advertising profile", "tags": [ "Podcasts", "tier:premium" ], "x-cost-weight": 2, "x-payment-info": { "offers": [ { "amount": "30000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.030000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "premium" } }, "/v1/podcasts/{id}/advertising/sponsors": { "get": { "description": "Returns per-sponsor ad activity on a single podcast (ads, distinct episodes, most recent placement), ordered by ad count descending. Pass company_id to scope the list to every sponsor linked to one company — the direct lookup for a multi-brand advertiser's footprint on one show, replacing a paginated scan of each sponsor's full podcast list. Entries agree with the ad_count values from the sponsor podcasts endpoint for the same sponsor and podcast. Network promos are excluded.", "operationId": "list-podcast-advertising-sponsors", "parameters": [ { "description": "Results per page", "explode": false, "in": "query", "name": "limit", "schema": { "default": 25, "description": "Results per page", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque pagination cursor from previous response", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque pagination cursor from previous response", "type": "string" } }, { "description": "Podcast slug (e.g., 'all-in'), internal ID, or numeric iTunes ID", "in": "path", "name": "id", "required": true, "schema": { "description": "Podcast slug (e.g., 'all-in'), internal ID, or numeric iTunes ID", "type": "string" } }, { "description": "Scope to sponsors linked to this company (ID, domain, or entity slug) — e.g. every brand of one advertiser on this show", "explode": false, "in": "query", "name": "company_id", "schema": { "description": "Scope to sponsors linked to this company (ID, domain, or entity slug) — e.g. every brand of one advertiser on this show", "type": "string" } }, { "description": "Only include ads from episodes published on or after this ISO 8601 date or date-time", "explode": false, "in": "query", "name": "since", "schema": { "description": "Only include ads from episodes published on or after this ISO 8601 date or date-time", "examples": [ "2025-01-01T00:00:00Z" ], "type": "string" } }, { "description": "Only include ads from episodes published before this ISO 8601 date or date-time", "explode": false, "in": "query", "name": "until", "schema": { "description": "Only include ads from episodes published before this ISO 8601 date or date-time", "examples": [ "2026-01-01T00:00:00Z" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagePodcastSponsorEntry" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.04 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "List sponsors advertising on a podcast", "tags": [ "Podcast Advertising", "tier:premium" ], "x-cost-weight": 2, "x-payment-info": { "offers": [ { "amount": "40000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.040000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "premium" } }, "/v1/podcasts/{id}/bias": { "get": { "description": "Returns the most recent automated political bias analysis for a podcast, including the agent's reasoning, transcript evidence, web research evidence, and the sample episodes that informed the rating. Returns 404 when the podcast is not found or when it has not yet been analyzed.", "operationId": "get-podcast-bias", "parameters": [ { "description": "Podcast slug (e.g., 'all-in'), internal ID, or numeric iTunes ID", "in": "path", "name": "id", "required": true, "schema": { "description": "Podcast slug (e.g., 'all-in'), internal ID, or numeric iTunes ID", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastBiasAnalysis" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.03 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "Get a podcast's latest bias analysis", "tags": [ "Podcasts", "tier:standard" ], "x-cost-weight": 1, "x-payment-info": { "offers": [ { "amount": "30000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.030000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "standard" } }, "/v1/podcasts/{id}/episodes": { "get": { "description": "Returns a paginated list of episodes for a specific podcast, identified by slug (e.g., 'all-in') or ID.", "operationId": "list-podcast-episodes", "parameters": [ { "description": "Results per page", "explode": false, "in": "query", "name": "limit", "schema": { "default": 25, "description": "Results per page", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque pagination cursor from previous response", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque pagination cursor from previous response", "type": "string" } }, { "description": "Podcast slug (e.g., 'all-in'), internal ID, or numeric iTunes ID", "in": "path", "name": "id", "required": true, "schema": { "description": "Podcast slug (e.g., 'all-in'), internal ID, or numeric iTunes ID", "type": "string" } }, { "description": "Filter to episodes whose title contains this text, case-insensitively. Matches the episode TITLE only — to search what is said inside episodes, use /v1/podcasts/episodes/search with podcast_id.", "explode": false, "in": "query", "name": "q", "schema": { "description": "Filter to episodes whose title contains this text, case-insensitively. Matches the episode TITLE only — to search what is said inside episodes, use /v1/podcasts/episodes/search with podcast_id.", "maxLength": 200, "type": "string" } }, { "description": "Only episodes published after this ISO 8601 date or date-time (e.g. 2024-01-01 or 2024-01-01T00:00:00Z)", "explode": false, "in": "query", "name": "published_after", "schema": { "description": "Only episodes published after this ISO 8601 date or date-time (e.g. 2024-01-01 or 2024-01-01T00:00:00Z)", "type": "string" } }, { "description": "Only episodes published before this ISO 8601 date or date-time (e.g. 2024-01-01 or 2024-01-01T00:00:00Z)", "explode": false, "in": "query", "name": "published_before", "schema": { "description": "Only episodes published before this ISO 8601 date or date-time (e.g. 2024-01-01 or 2024-01-01T00:00:00Z)", "type": "string" } }, { "description": "Filter by where episodes stand on the way to a transcript. Omitted, the list holds the episodes we have ingested, as it always has. any, untranscribed and requestable also list the podcast's back catalogue — episodes we have discovered in its feed but not transcribed: any lists every discovered episode, untranscribed those without a transcript, requestable back-catalogue episodes whose transcript can be requested. transcribed lists episodes with a transcript.", "explode": false, "in": "query", "name": "transcript_status", "schema": { "description": "Filter by where episodes stand on the way to a transcript. Omitted, the list holds the episodes we have ingested, as it always has. any, untranscribed and requestable also list the podcast's back catalogue — episodes we have discovered in its feed but not transcribed: any lists every discovered episode, untranscribed those without a transcript, requestable back-catalogue episodes whose transcript can be requested. transcribed lists episodes with a transcript.", "enum": [ "any", "transcribed", "untranscribed", "requestable" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageEpisode" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.03 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "List episodes for a podcast", "tags": [ "Podcasts", "tier:standard" ], "x-cost-weight": 1, "x-payment-info": { "offers": [ { "amount": "30000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.030000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "standard" } }, "/v1/podcasts/{id}/external-links": { "get": { "description": "Returns every third-party platform on which the podcast has a known presence — podcast directories (Apple Podcasts, Spotify, Castbox, …), social profiles (X, Instagram, TikTok, …), video channels (YouTube), and the publisher's own website. Each entry includes the platform-native identifier, a resolved web URL, and a list of optional attributes (audience size, profile metadata, account status). The shape is uniform across platforms; new attributes may be added over time without breaking existing clients.", "operationId": "list-podcast-external-links", "parameters": [ { "description": "Results per page (default: all)", "explode": false, "in": "query", "name": "limit", "schema": { "description": "Results per page (default: all)", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque pagination cursor from previous response", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque pagination cursor from previous response", "type": "string" } }, { "description": "Podcast slug (e.g., 'all-in'), internal ID, or numeric iTunes ID", "in": "path", "name": "id", "required": true, "schema": { "description": "Podcast slug (e.g., 'all-in'), internal ID, or numeric iTunes ID", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageExternalLink" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.04 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "List a podcast's third-party platform presences", "tags": [ "Podcasts", "tier:standard" ], "x-cost-weight": 1, "x-payment-info": { "offers": [ { "amount": "40000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.040000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "standard" } }, "/v1/podcasts/{id}/format": { "get": { "description": "Returns the full format breakdown for a podcast: how often episodes feature guests, detected production formats (interview, panel, call_in, solo_narrated), advertiser and video presence, episode length distribution, publishing cadence, the publish-day histogram, and the sample sizes behind each attribute. The compact form of this data is embedded as the `format` field on podcast responses; use this endpoint for the exact rates and distributions. Returns 404 when the podcast is not found or its format profile has not been computed yet.", "operationId": "get-podcast-format", "parameters": [ { "description": "Podcast slug (e.g., 'all-in'), internal ID, or numeric iTunes ID", "in": "path", "name": "id", "required": true, "schema": { "description": "Podcast slug (e.g., 'all-in'), internal ID, or numeric iTunes ID", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastFormatProfile" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.03 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "Get a podcast's format profile", "tags": [ "Podcasts", "tier:standard" ], "x-cost-weight": 1, "x-payment-info": { "offers": [ { "amount": "30000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.030000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "standard" } }, "/v1/podcasts/{id}/guests": { "get": { "description": "Returns the paginated set of identified guests who have appeared on the podcast, grouped by Person. Each row carries the Person identity, the per-podcast appearance count, first/last appearance dates, and dominant listing role.", "operationId": "list-podcast-roster-guests", "parameters": [ { "description": "Results per page", "explode": false, "in": "query", "name": "limit", "schema": { "default": 25, "description": "Results per page", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque pagination cursor from previous response", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque pagination cursor from previous response", "type": "string" } }, { "description": "Podcast slug or ID", "in": "path", "name": "id", "required": true, "schema": { "description": "Podcast slug or ID", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagePodcastGuestCompact" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.03 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "List the guest roster for a podcast", "tags": [ "Podcast Guests", "tier:standard" ], "x-cost-weight": 1, "x-payment-info": { "offers": [ { "amount": "30000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.030000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "standard" } }, "/v1/podcasts/{id}/mentions": { "get": { "description": "Returns episodes where a specific entity appears within a podcast, ordered by most recent. Each result includes the episode, salience score, occurrence count, and speaker roles. Requires entity_id or company_id.", "operationId": "list-podcast-mentions", "parameters": [ { "description": "Results per page", "explode": false, "in": "query", "name": "limit", "schema": { "default": 25, "description": "Results per page", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque pagination cursor from previous response", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque pagination cursor from previous response", "type": "string" } }, { "description": "Podcast slug (e.g., 'all-in'), internal ID, or numeric iTunes ID", "in": "path", "name": "id", "required": true, "schema": { "description": "Podcast slug (e.g., 'all-in'), internal ID, or numeric iTunes ID", "type": "string" } }, { "description": "Entity slug (e.g., 'sam-altman', 'openai') or ID", "explode": false, "in": "query", "name": "entity_id", "schema": { "description": "Entity slug (e.g., 'sam-altman', 'openai') or ID", "type": "string" } }, { "description": "Company slug (e.g., 'nvidia'), domain (e.g., 'nvidia.com'), or ID. Resolves to the company's linked entity.", "explode": false, "in": "query", "name": "company_id", "schema": { "description": "Company slug (e.g., 'nvidia'), domain (e.g., 'nvidia.com'), or ID. Resolves to the company's linked entity.", "type": "string" } }, { "description": "Entity role filter. Constrains which episodes match.", "explode": false, "in": "query", "name": "role", "schema": { "description": "Entity role filter. Constrains which episodes match.", "enum": [ "guest", "host", "panelist", "correspondent", "mention" ], "type": "string" } }, { "description": "Only episodes published after this ISO 8601 date or date-time (e.g. 2024-01-01 or 2024-01-01T00:00:00Z)", "explode": false, "in": "query", "name": "published_after", "schema": { "description": "Only episodes published after this ISO 8601 date or date-time (e.g. 2024-01-01 or 2024-01-01T00:00:00Z)", "type": "string" } }, { "description": "Only episodes published before this ISO 8601 date or date-time (e.g. 2024-01-01 or 2024-01-01T00:00:00Z)", "explode": false, "in": "query", "name": "published_before", "schema": { "description": "Only episodes published before this ISO 8601 date or date-time (e.g. 2024-01-01 or 2024-01-01T00:00:00Z)", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagePodcastMention" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.03 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "List entity mentions in a podcast", "tags": [ "Podcasts", "tier:standard" ], "x-cost-weight": 1, "x-payment-info": { "offers": [ { "amount": "30000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.030000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "standard" } }, "/v1/podcasts/{id}/rankings": { "get": { "description": "Returns every live chart appearance of the given podcast — across sources, countries, and categories. Identify the podcast by slug (e.g., 'the-daily') or ID.", "operationId": "list-podcast-current-rankings", "parameters": [ { "description": "Results per page (default: all)", "explode": false, "in": "query", "name": "limit", "schema": { "description": "Results per page (default: all)", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque pagination cursor from previous response", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque pagination cursor from previous response", "type": "string" } }, { "description": "Podcast slug (e.g. 'the-daily', 'lex-fridman-podcast'), internal ID, or numeric iTunes ID.", "in": "path", "name": "id", "required": true, "schema": { "description": "Podcast slug (e.g. 'the-daily', 'lex-fridman-podcast'), internal ID, or numeric iTunes ID.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagePodcastRanking" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.03 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "List current rankings for a podcast", "tags": [ "Podcast Rankings", "tier:premium" ], "x-cost-weight": 2, "x-payment-info": { "offers": [ { "amount": "30000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.030000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "premium" } }, "/v1/podcasts/{id}/rankings/history": { "get": { "description": "Returns the historical rank entries for a podcast across one or more chart slots. Optional filters narrow the scope (single source, single country, single category, or a date range).", "operationId": "get-podcast-rankings-history-for-podcast", "parameters": [ { "description": "Results per page", "explode": false, "in": "query", "name": "limit", "schema": { "default": 25, "description": "Results per page", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque pagination cursor from previous response", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque pagination cursor from previous response", "type": "string" } }, { "description": "Podcast slug, internal ID, or numeric iTunes ID.", "in": "path", "name": "id", "required": true, "schema": { "description": "Podcast slug, internal ID, or numeric iTunes ID.", "type": "string" } }, { "description": "Restrict to one source.", "explode": false, "in": "query", "name": "source", "schema": { "description": "Restrict to one source.", "enum": [ "apple", "spotify" ], "type": "string" } }, { "description": "Restrict to one chart type.", "explode": false, "in": "query", "name": "chart_type", "schema": { "description": "Restrict to one chart type.", "enum": [ "top_podcasts" ], "type": "string" } }, { "description": "Restrict to one country (ISO 3166-1 alpha-2; case-insensitive on input).", "explode": false, "in": "query", "name": "country", "schema": { "description": "Restrict to one country (ISO 3166-1 alpha-2; case-insensitive on input).", "maxLength": 2, "minLength": 2, "type": "string" } }, { "description": "Restrict to one category slug. Omit to include every category.", "explode": false, "in": "query", "name": "category_slug", "schema": { "description": "Restrict to one category slug. Omit to include every category.", "type": "string" } }, { "description": "Lower bound on captured_at (ISO 8601).", "explode": false, "in": "query", "name": "since", "schema": { "description": "Lower bound on captured_at (ISO 8601).", "examples": [ "2025-01-01T00:00:00Z" ], "type": "string" } }, { "description": "Upper bound on captured_at (ISO 8601).", "explode": false, "in": "query", "name": "until", "schema": { "description": "Upper bound on captured_at (ISO 8601).", "examples": [ "2026-01-01T00:00:00Z" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagePodcastRanking" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.04 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "Get historical rankings for a podcast", "tags": [ "Podcast Rankings", "tier:premium" ], "x-cost-weight": 2, "x-payment-info": { "offers": [ { "amount": "40000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.040000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "premium" } }, "/v1/podcasts/{id}/rankings/summary": { "get": { "description": "Returns a one-call aggregate of the podcast's current chart presence: the number of distinct chart slots, sources, countries, and categories it appears on, plus the single best (lowest-numbered) rank it currently holds and a per-source breakdown.", "operationId": "get-podcast-rankings-summary", "parameters": [ { "description": "Podcast slug, internal ID, or numeric iTunes ID.", "in": "path", "name": "id", "required": true, "schema": { "description": "Podcast slug, internal ID, or numeric iTunes ID.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastRankingsSummary" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.03 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "Summarize a podcast's chart presence", "tags": [ "Podcast Rankings", "tier:premium" ], "x-cost-weight": 2, "x-payment-info": { "offers": [ { "amount": "30000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.030000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "premium" } }, "/v1/podcasts/{id}/ratings": { "get": { "description": "Returns user-generated ratings (1-5 stars plus optional review text) captured from third-party platforms. Today's source is Apple Podcasts, walked across the Anglophone storefronts (us, gb, ca, au, nz, ie). Newest ratings first; paginate with `cursor`. Filter by `platform_slug`, `locale`, `min_stars`, or a date window on `since`/`until`.", "operationId": "list-podcast-ratings", "parameters": [ { "description": "Results per page", "explode": false, "in": "query", "name": "limit", "schema": { "default": 25, "description": "Results per page", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque pagination cursor from previous response", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque pagination cursor from previous response", "type": "string" } }, { "description": "Podcast slug (e.g. 'the-daily', 'lex-fridman-podcast'), internal ID, or numeric iTunes ID.", "in": "path", "name": "id", "required": true, "schema": { "description": "Podcast slug (e.g. 'the-daily', 'lex-fridman-podcast'), internal ID, or numeric iTunes ID.", "type": "string" } }, { "description": "Restrict to ratings from one platform (e.g. 'apple'). Omit to return ratings from every platform.", "explode": false, "in": "query", "name": "platform_slug", "schema": { "description": "Restrict to ratings from one platform (e.g. 'apple'). Omit to return ratings from every platform.", "type": "string" } }, { "description": "Restrict to one platform-specific locale (e.g. Apple storefront 'us'). Omit to return ratings across every locale.", "explode": false, "in": "query", "name": "locale", "schema": { "description": "Restrict to one platform-specific locale (e.g. Apple storefront 'us'). Omit to return ratings across every locale.", "type": "string" } }, { "description": "Lower bound on the star rating (inclusive).", "explode": false, "in": "query", "name": "min_stars", "schema": { "description": "Lower bound on the star rating (inclusive).", "format": "int64", "maximum": 5, "minimum": 1, "type": "integer" } }, { "description": "Lower bound on posted_at (ISO 8601).", "explode": false, "in": "query", "name": "since", "schema": { "description": "Lower bound on posted_at (ISO 8601).", "examples": [ "2026-01-01T00:00:00Z" ], "type": "string" } }, { "description": "Upper bound on posted_at (ISO 8601).", "explode": false, "in": "query", "name": "until", "schema": { "description": "Upper bound on posted_at (ISO 8601).", "examples": [ "2026-06-01T00:00:00Z" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PagePodcastRating" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.01 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "List ratings for a podcast", "tags": [ "Podcast Ratings", "tier:standard" ], "x-cost-weight": 1, "x-payment-info": { "offers": [ { "amount": "10000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.010000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "standard" } }, "/v1/podcasts/{id}/ratings/summary": { "get": { "description": "Returns the numeric aggregate of a podcast's ratings — one entry per (platform, locale) it has been rated on, a combined cross-source roll-up, and the latest LLM-generated narrative summary of recent review text when one has been generated.", "operationId": "get-podcast-ratings-summary", "parameters": [ { "description": "Podcast slug, internal ID, or numeric iTunes ID.", "in": "path", "name": "id", "required": true, "schema": { "description": "Podcast slug, internal ID, or numeric iTunes ID.", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastRatingsSummary" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.03 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "Summarize a podcast's ratings", "tags": [ "Podcast Ratings", "tier:standard" ], "x-cost-weight": 1, "x-payment-info": { "offers": [ { "amount": "30000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.030000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "standard" } }, "/v1/podcasts/{id}/recommendations/guests": { "get": { "description": "Returns people who have guested on the podcast's related shows but never on this one, ranked by how related those venues are and how many distinct publishers among them chose the person — a booking pipeline, not a prediction. Recurring on any one show does not count, and a publisher's sibling feeds count once, so an outlet's own correspondents do not outrank guests several independent shows chose. Guests who appear everywhere (circuit regulars) are excluded, since recommending them says nothing about this show. Each row carries the person, a score, a band, how many related shows booked them, and with include=via which shows. For the show's existing roster use GET /v1/podcasts/{id}/guests; for shows like this one use GET /v1/podcasts/{id}/related.", "operationId": "list-podcast-recommended-guests", "parameters": [ { "description": "Results per page", "explode": false, "in": "query", "name": "limit", "schema": { "default": 25, "description": "Results per page", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque pagination cursor from previous response", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque pagination cursor from previous response", "type": "string" } }, { "description": "Podcast slug (e.g., 'all-in'), internal ID, or numeric iTunes ID", "in": "path", "name": "id", "required": true, "schema": { "description": "Podcast slug (e.g., 'all-in'), internal ID, or numeric iTunes ID", "type": "string" } }, { "description": "Optional response sections. Pass include=via to attach, for each recommended guest, the related shows that booked them.", "explode": false, "in": "query", "name": "include", "schema": { "description": "Optional response sections. Pass include=via to attach, for each recommended guest, the related shows that booked them.", "items": { "enum": [ "via" ], "type": "string" }, "type": [ "array", "null" ] } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageRecommendedGuest" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.03 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "List guests a podcast could plausibly book", "tags": [ "Podcast Guests", "tier:standard" ], "x-cost-weight": 1, "x-payment-info": { "offers": [ { "amount": "30000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.030000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "standard" } }, "/v1/podcasts/{id}/recommendations/sponsors": { "get": { "description": "Returns advertisers that run on the podcast's related shows but not on this one, ranked by how related those venues are, how much the sponsor buys there, and how recently — a prospecting list for a show selling its own inventory ('who buys shows like mine'), not a prediction. Each row carries the sponsor (with its linked company, the path to people to contact via GET /v1/companies/{id}/people), a score, a band, how many related shows run it, its ad count across them, the date of its most recent ad, and with include=via which shows. active_since keeps only sponsors still buying after a date. Related sets are precomputed (GET /v1/podcasts/{id}/related); a show whose set has not been computed yet gets an empty page. For who sponsors THIS show use GET /v1/podcasts/{id}/advertising; for a sponsor's full footprint use GET /v1/podcasts/advertising/sponsors/{id}/podcasts.", "operationId": "list-podcast-recommended-sponsors", "parameters": [ { "description": "Results per page", "explode": false, "in": "query", "name": "limit", "schema": { "default": 25, "description": "Results per page", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque pagination cursor from previous response", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque pagination cursor from previous response", "type": "string" } }, { "description": "Podcast slug (e.g., 'all-in'), internal ID, or numeric iTunes ID", "in": "path", "name": "id", "required": true, "schema": { "description": "Podcast slug (e.g., 'all-in'), internal ID, or numeric iTunes ID", "type": "string" } }, { "description": "Optional response sections. Pass include=via to attach, for each recommended sponsor, the related shows that run it (the peer set to cite in a pitch). Pass include=contacts to attach up to three people at the sponsor's company most likely to own a sponsorship decision, with their role class and LinkedIn URL.", "explode": false, "in": "query", "name": "include", "schema": { "description": "Optional response sections. Pass include=via to attach, for each recommended sponsor, the related shows that run it (the peer set to cite in a pitch). Pass include=contacts to attach up to three people at the sponsor's company most likely to own a sponsorship decision, with their role class and LinkedIn URL.", "items": { "enum": [ "via", "contacts" ], "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Only recommendations with a score at or above this value. Omit (or 0) for every recommendation; the band field is the recommended way to filter by strength.", "explode": false, "in": "query", "name": "min_score", "schema": { "description": "Only recommendations with a score at or above this value. Omit (or 0) for every recommendation; the band field is the recommended way to filter by strength.", "format": "double", "maximum": 1, "minimum": 0, "type": "number" } }, { "description": "Only sponsors whose most recent ad across the related shows was published on or after this ISO 8601 date or date-time — the 'still buying' filter.", "explode": false, "in": "query", "name": "active_since", "schema": { "description": "Only sponsors whose most recent ad across the related shows was published on or after this ISO 8601 date or date-time — the 'still buying' filter.", "examples": [ "2026-01-01T00:00:00Z" ], "type": "string" } }, { "description": "Drop the N most active advertisers corpus-wide from the list. An advertiser is every sponsor record that resolves to the same company or name, ranked by summed lifetime ad count. The list is strongest beyond the largest programmatic advertisers, which every list already names; 50 removes the head, 200 keeps only the long tail.", "explode": false, "in": "query", "name": "exclude_top_advertisers", "schema": { "description": "Drop the N most active advertisers corpus-wide from the list. An advertiser is every sponsor record that resolves to the same company or name, ranked by summed lifetime ad count. The list is strongest beyond the largest programmatic advertisers, which every list already names; 50 removes the head, 200 keeps only the long tail.", "format": "int64", "maximum": 500, "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageRecommendedSponsor" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.03 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "List sponsors a podcast could pitch", "tags": [ "Podcasts", "tier:premium" ], "x-cost-weight": 2, "x-payment-info": { "offers": [ { "amount": "30000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.030000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "premium" } }, "/v1/podcasts/{id}/related": { "get": { "description": "Returns the shows most related to a podcast, best first, each with a calibrated `score`, a coarse `band` (strong, moderate, weak) to branch on, and — with `include=basis` — the signals behind the pairing: content similarity of recent episodes, shared topics, shared guests (named), same publisher, and shared sponsors. Related sets are precomputed per show from its embedded transcripts, topic profile, guest roster, network, and advertisers, restricted to the show's language, and refreshed as new episodes land; the endpoint is a fast page read. Only shows above a relatedness floor are listed, machine-generated and farmed feeds are never listed, and a publisher's duplicate feeds of one show appear once (sets computed before that rule are collapsed on read, best-effort). An empty first page is 200 with a `coverage` note saying whether the set is not computed yet, nothing cleared the floor, or the filters removed everything — never 404. Use this for \"shows like this show\" — media planning around a known show, PR pitch lists, and agent traversal from one resolved slug to its neighbours. It is not a topic browser (use `GET /v1/podcasts?topic_id=…` for shows that cover a topic), not a guest lookup (`GET /v1/podcasts/guests/{id}/podcasts` lists where a guest has appeared), and not advertiser co-occurrence (`GET /v1/podcasts/advertising/co-occurrence`). Every result carries the related show's `slug`, which every other podcast endpoint accepts as `{id}`; person slugs in the basis feed the guest endpoints and topic slugs feed `topic_id`. Identify the podcast by slug (e.g., 'all-in'), internal ID, or numeric iTunes ID.", "operationId": "list-related-podcasts", "parameters": [ { "description": "Results per page", "explode": false, "in": "query", "name": "limit", "schema": { "default": 25, "description": "Results per page", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque pagination cursor from previous response", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque pagination cursor from previous response", "type": "string" } }, { "description": "Podcast slug (e.g., 'all-in'), internal ID, or numeric iTunes ID", "in": "path", "name": "id", "required": true, "schema": { "description": "Podcast slug (e.g., 'all-in'), internal ID, or numeric iTunes ID", "type": "string" } }, { "description": "Optional response sections. Pass include=basis to attach, for every result, the signals that make the two shows related: content similarity, shared topics, shared guests (with names), same publisher, shared sponsors.", "explode": false, "in": "query", "name": "include", "schema": { "description": "Optional response sections. Pass include=basis to attach, for every result, the signals that make the two shows related: content similarity, shared topics, shared guests (with names), same publisher, shared sponsors.", "items": { "enum": [ "basis" ], "type": "string" }, "type": [ "array", "null" ] } }, { "description": "Only results with a fused score at or above this value. Omit (or 0) to return every stored neighbour; the band field is the recommended way to filter by strength.", "explode": false, "in": "query", "name": "min_score", "schema": { "description": "Only results with a fused score at or above this value. Omit (or 0) to return every stored neighbour; the band field is the recommended way to filter by strength.", "format": "double", "maximum": 1, "minimum": 0, "type": "number" } }, { "description": "Only shows in this language (ISO 639-1 code, e.g. 'en', 'es'; a region suffix such as 'fr-CA' is reduced to the language). Related sets are built within the source show's language, so this mostly matters for shows with a mixed catalogue.", "explode": false, "in": "query", "name": "language", "schema": { "description": "Only shows in this language (ISO 639-1 code, e.g. 'en', 'es'; a region suffix such as 'fr-CA' is reduced to the language). Related sets are built within the source show's language, so this mostly matters for shows with a mixed catalogue.", "type": "string" } }, { "description": "Only shows that have released an episode in the last 90 days (active) or have not (dormant). Shows with no known episode date match neither.", "explode": false, "in": "query", "name": "publishing_status", "schema": { "description": "Only shows that have released an episode in the last 90 days (active) or have not (dormant). Shows with no known episode date match neither.", "enum": [ "active", "dormant" ], "type": "string" } }, { "description": "Only shows whose latest brand-suitability assessment is this tier. Shows never assessed are excluded when this is set.", "explode": false, "in": "query", "name": "suitability_tier", "schema": { "description": "Only shows whose latest brand-suitability assessment is this tier. Shows never assessed are excluded when this is set.", "enum": [ "SAFE", "LIMITED", "SENSITIVE", "UNSAFE" ], "type": "string" } }, { "description": "Only shows at or above this popularity percentile (0-1]. A floor above 0 excludes shows that do not chart; 0 (or omitting it) applies no floor.", "explode": false, "in": "query", "name": "min_popularity", "schema": { "description": "Only shows at or above this popularity percentile (0-1]. A floor above 0 excludes shows that do not chart; 0 (or omitting it) applies no floor.", "format": "double", "maximum": 1, "minimum": 0, "type": "number" } }, { "description": "Drop shows from the source show's own publisher — 'shows like mine that I do not already own'.", "explode": false, "in": "query", "name": "exclude_same_publisher", "schema": { "description": "Drop shows from the source show's own publisher — 'shows like mine that I do not already own'.", "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelatedPodcastsPage" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.03 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "List related podcasts", "tags": [ "Podcasts", "tier:standard" ], "x-cost-weight": 1, "x-payment-info": { "offers": [ { "amount": "30000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.030000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "standard" } }, "/v1/podcasts/{id}/suitability": { "get": { "description": "Returns the most recent brand suitability assessment for a podcast against the IAB Tech Lab Content Taxonomy 3.x Brand Safety \u0026 Suitability Framework (the industry-standard 12-category taxonomy formerly stewarded by GARM): overall tier, per-category prevalence and treatment, evidence excerpts from sampled episodes, and the methodology that produced the rating. Pass include=trend for a deterministically-derived comparison against the prior assessment, or include=history for the list of prior assessments. Returns 404 when the podcast is not found or has not yet been analyzed.", "operationId": "get-podcast-suitability", "parameters": [ { "description": "Podcast slug (e.g., 'all-in'), internal ID, or numeric iTunes ID", "in": "path", "name": "id", "required": true, "schema": { "description": "Podcast slug (e.g., 'all-in'), internal ID, or numeric iTunes ID", "type": "string" } }, { "description": "Optional response sections. Pass include=trend for a deterministically-derived comparison against the prior assessment, include=history for the list of prior assessments, or include=trend,history for both.", "explode": false, "in": "query", "name": "include", "schema": { "description": "Optional response sections. Pass include=trend for a deterministically-derived comparison against the prior assessment, include=history for the list of prior assessments, or include=trend,history for both.", "items": { "enum": [ "trend", "history" ], "type": "string" }, "type": [ "array", "null" ] } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastSuitabilityAnalysis" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.04 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "Get a podcast's latest brand suitability assessment", "tags": [ "Podcasts", "tier:premium" ], "x-cost-weight": 2, "x-payment-info": { "offers": [ { "amount": "40000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.040000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "premium" } }, "/v1/projects/{projectId}/alerts": { "get": { "description": "List alerts owned by the given project, newest first.", "operationId": "list-alerts", "parameters": [ { "description": "Project ID.", "in": "path", "name": "projectId", "required": true, "schema": { "description": "Project ID.", "type": "string" } }, { "description": "Results per page", "explode": false, "in": "query", "name": "limit", "schema": { "default": 25, "description": "Results per page", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque pagination cursor from previous response", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque pagination cursor from previous response", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageAlert" } } }, "description": "OK" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "summary": "List alerts", "tags": [ "Alerts", "tier:standard" ], "x-cost-weight": 1, "x-entitlement-priced": true, "x-tier": "standard" }, "post": { "description": "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.", "operationId": "create-alert", "parameters": [ { "description": "Project ID.", "in": "path", "name": "projectId", "required": true, "schema": { "description": "Project ID.", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAlertBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Alert" } } }, "description": "OK" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "summary": "Create an alert", "tags": [ "Alerts", "tier:standard" ], "x-cost-weight": 1, "x-entitlement-priced": true, "x-tier": "standard" } }, "/v1/projects/{projectId}/alerts/preview": { "post": { "description": "Kicks off an asynchronous sweep over the past N days (default 7, max 30) and returns a preview_id. Poll GET /v1/alerts/preview/{previewId} until status is completed (or failed). The result includes the total match count, a per-day breakdown, and a small sample of the most-recent matches with full payload so the UI can show \"if you create this alert, here's what it would have caught.\"", "operationId": "preview-alert", "parameters": [ { "description": "Project ID.", "in": "path", "name": "projectId", "required": true, "schema": { "description": "Project ID.", "type": "string" } }, { "description": "Number of days back to sweep. Defaults to 7; capped at 30.", "explode": false, "in": "query", "name": "window_days", "schema": { "description": "Number of days back to sweep. Defaults to 7; capped at 30.", "examples": [ 7 ], "format": "int64", "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewAlertBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewAlertResponseBody" } } }, "description": "OK" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "summary": "Preview match frequency for an alert before creating it", "tags": [ "Alerts", "tier:standard" ], "x-cost-weight": 1, "x-entitlement-priced": true, "x-tier": "standard" } }, "/v1/projects/{projectId}/slack/connections": { "get": { "description": "Returns the active (non-revoked, non-deleted) Slack workspace installs for the project, whichever surface installed them. Each connection reports its own surface so callers can label provenance; an alert may deliver through a workspace installed from the other app.", "operationId": "list-slack-connections", "parameters": [ { "description": "Project ID (base62-encoded).", "in": "path", "name": "projectId", "required": true, "schema": { "description": "Project ID (base62-encoded).", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSlackConnectionsResponseBody" } } }, "description": "OK" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "summary": "List Slack connections for a project", "tags": [ "Slack Connections", "tier:standard" ], "x-cost-weight": 1, "x-entitlement-priced": true, "x-tier": "standard" } }, "/v1/projects/{projectId}/slack/connections/initiate": { "post": { "description": "Returns the Slack /oauth/v2/authorize URL the user's browser should be redirected to. The surface (Particle Slack app vs Radar Slack app) is inferred from the calling request — Radar-issuer JWTs install the Radar app; everything else installs the Particle app. JWT auth required; API keys cannot install OAuth on behalf of a user.", "operationId": "initiate-slack-connection", "parameters": [ { "description": "Project ID (base62-encoded).", "in": "path", "name": "projectId", "required": true, "schema": { "description": "Project ID (base62-encoded).", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InitiateSlackConnectionBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InitiateSlackConnectionResponseBody" } } }, "description": "OK" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "summary": "Initiate a Slack workspace OAuth install", "tags": [ "Slack Connections", "tier:standard" ], "x-cost-weight": 1, "x-entitlement-priced": true, "x-tier": "standard" } }, "/v1/projects/{projectId}/slack/connections/{id}": { "delete": { "description": "Soft-deletes the slack_teams row. Alert channels referencing this connection remain in place; the delivery subscriber detects the soft-deleted install at delivery time and skips that channel (logged, not posted, no chat-message row enqueued). The alert's overall delivery audit row still commits as SENT for a zero-fanout delivery rather than leaving the match permanently 'undelivered.'", "operationId": "delete-slack-connection", "parameters": [ { "description": "Project ID (base62-encoded).", "in": "path", "name": "projectId", "required": true, "schema": { "description": "Project ID (base62-encoded).", "type": "string" } }, { "description": "Slack connection ID (base62-encoded).", "in": "path", "name": "id", "required": true, "schema": { "description": "Slack connection ID (base62-encoded).", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteSlackConnectionResponseBody" } } }, "description": "OK" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "summary": "Delete a Slack connection", "tags": [ "Slack Connections", "tier:standard" ], "x-cost-weight": 1, "x-entitlement-priced": true, "x-tier": "standard" } }, "/v1/projects/{projectId}/slack/connections/{id}/channels": { "get": { "description": "Refreshes the channel cache via Slack conversations.list and returns the channels the bot can see. Includes public and private channels; DMs are excluded.", "operationId": "list-slack-connection-channels", "parameters": [ { "description": "Project ID (base62-encoded).", "in": "path", "name": "projectId", "required": true, "schema": { "description": "Project ID (base62-encoded).", "type": "string" } }, { "description": "Slack connection ID (base62-encoded).", "in": "path", "name": "id", "required": true, "schema": { "description": "Slack connection ID (base62-encoded).", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListSlackConnectionChannelsResponseBody" } } }, "description": "OK" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "summary": "List channels for a Slack connection", "tags": [ "Slack Connections", "tier:standard" ], "x-cost-weight": 1, "x-entitlement-priced": true, "x-tier": "standard" } }, "/v1/projects/{projectId}/webhooks/connections": { "get": { "description": "Returns the active (non-revoked) webhook connections for the project, whichever surface created them. Each connection reports its own surface so callers can label provenance. The signing secret is never returned — only its masked prefix.", "operationId": "list-webhook-connections", "parameters": [ { "description": "Project ID (base62-encoded).", "in": "path", "name": "projectId", "required": true, "schema": { "description": "Project ID (base62-encoded).", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListWebhookConnectionsResponseBody" } } }, "description": "OK" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "summary": "List webhook connections for a project", "tags": [ "Webhook Connections", "tier:standard" ], "x-cost-weight": 1, "x-entitlement-priced": true, "x-tier": "standard" }, "post": { "description": "Creates a webhook connection (a destination URL plus a generated HMAC signing secret) that alerts can target as a WEBHOOK notification channel. The signing secret is returned only in this response — store it securely; it cannot be retrieved again. The URL must be https and must resolve to a public address.", "operationId": "create-webhook-connection", "parameters": [ { "description": "Project ID (base62-encoded).", "in": "path", "name": "projectId", "required": true, "schema": { "description": "Project ID (base62-encoded).", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookConnectionBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookConnectionCreated" } } }, "description": "OK" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "summary": "Create a webhook connection", "tags": [ "Webhook Connections", "tier:standard" ], "x-cost-weight": 1, "x-entitlement-priced": true, "x-tier": "standard" } }, "/v1/projects/{projectId}/webhooks/connections/{id}": { "delete": { "description": "Soft-deletes the connection. Alert channels referencing it remain in place; the delivery subscriber detects the deleted connection at delivery time and skips that channel (logged, not posted). The alert's overall delivery audit row still commits as SENT for a zero-fanout delivery rather than leaving the match permanently undelivered.", "operationId": "delete-webhook-connection", "parameters": [ { "description": "Project ID (base62-encoded).", "in": "path", "name": "projectId", "required": true, "schema": { "description": "Project ID (base62-encoded).", "type": "string" } }, { "description": "Webhook connection ID (base62-encoded).", "in": "path", "name": "id", "required": true, "schema": { "description": "Webhook connection ID (base62-encoded).", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteWebhookConnectionResponseBody" } } }, "description": "OK" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "summary": "Delete a webhook connection", "tags": [ "Webhook Connections", "tier:standard" ], "x-cost-weight": 1, "x-entitlement-priced": true, "x-tier": "standard" }, "get": { "description": "Returns a single webhook connection. The signing secret is never returned — only its masked prefix.", "operationId": "get-webhook-connection", "parameters": [ { "description": "Project ID (base62-encoded).", "in": "path", "name": "projectId", "required": true, "schema": { "description": "Project ID (base62-encoded).", "type": "string" } }, { "description": "Webhook connection ID (base62-encoded).", "in": "path", "name": "id", "required": true, "schema": { "description": "Webhook connection ID (base62-encoded).", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformWebhookConnection" } } }, "description": "OK" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "summary": "Get a webhook connection", "tags": [ "Webhook Connections", "tier:standard" ], "x-cost-weight": 1, "x-entitlement-priced": true, "x-tier": "standard" } }, "/v1/projects/{projectId}/webhooks/connections/{id}/secret/rotate": { "post": { "description": "Generates a new signing secret for the connection and returns it once. The previous secret stops validating immediately, so update the receiver before rotating in production.", "operationId": "rotate-webhook-connection-secret", "parameters": [ { "description": "Project ID (base62-encoded).", "in": "path", "name": "projectId", "required": true, "schema": { "description": "Project ID (base62-encoded).", "type": "string" } }, { "description": "Webhook connection ID (base62-encoded).", "in": "path", "name": "id", "required": true, "schema": { "description": "Webhook connection ID (base62-encoded).", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookConnectionCreated" } } }, "description": "OK" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "summary": "Rotate a webhook connection's signing secret", "tags": [ "Webhook Connections", "tier:standard" ], "x-cost-weight": 1, "x-entitlement-priced": true, "x-tier": "standard" } }, "/v1/slack/connections/callback": { "get": { "description": "Slack redirects the user's browser here with code+state. Exchanges the code for a bot token, persists the connection, and 302s back to the originating surface's UI with connection_id and status query params.", "operationId": "complete-slack-connection", "parameters": [ { "description": "Authorization code from Slack.", "explode": false, "in": "query", "name": "code", "schema": { "description": "Authorization code from Slack.", "type": "string" } }, { "description": "State token issued by /initiate, HMAC-signed and TTL-bounded.", "explode": false, "in": "query", "name": "state", "schema": { "description": "State token issued by /initiate, HMAC-signed and TTL-bounded.", "type": "string" } }, { "description": "Set by Slack when the user denied or the OAuth flow errored.", "explode": false, "in": "query", "name": "error", "schema": { "description": "Set by Slack when the user denied or the OAuth flow errored.", "type": "string" } } ], "responses": { "302": { "description": "Found", "headers": { "Location": { "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [], "summary": "Complete a Slack workspace OAuth install", "tags": [ "Slack Connections", "tier:free" ], "x-cost-weight": 0, "x-tier": "free" } }, "/v1/topics": { "get": { "description": "Returns the hierarchical topic taxonomy. Use parent_id to navigate the tree.", "operationId": "list-topics", "parameters": [ { "description": "Results per page", "explode": false, "in": "query", "name": "limit", "schema": { "default": 25, "description": "Results per page", "format": "int64", "maximum": 100, "minimum": 1, "type": "integer" } }, { "description": "Opaque pagination cursor from previous response", "explode": false, "in": "query", "name": "cursor", "schema": { "description": "Opaque pagination cursor from previous response", "type": "string" } }, { "description": "Get children of this topic. Accepts topic ID, ancestry slug, or ancestry path hash. Omit for top-level roots.", "explode": false, "in": "query", "name": "parent_id", "schema": { "description": "Get children of this topic. Accepts topic ID, ancestry slug, or ancestry path hash. Omit for top-level roots.", "type": "string" } }, { "description": "Filter by exact ancestry path hash.", "explode": false, "in": "query", "name": "ancestry_path", "schema": { "description": "Filter by exact ancestry path hash.", "maxLength": 50, "type": "string" } }, { "description": "Filter by ancestry path prefix (all descendants).", "explode": false, "in": "query", "name": "ancestry_path_prefix", "schema": { "description": "Filter by ancestry path prefix (all descendants).", "maxLength": 50, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageTopic" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.01 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "List topics", "tags": [ "Topics", "tier:standard" ], "x-cost-weight": 1, "x-payment-info": { "offers": [ { "amount": "10000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.010000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "standard" } }, "/v1/topics/{id}": { "get": { "description": "Returns a single topic with breadcrumb ancestors and the top direct children by prominence. Children are capped — use /v1/topics?parent_id={id} to paginate beyond the cap.", "operationId": "get-topic", "parameters": [ { "description": "Topic ID, ancestry slug (e.g., technology/artificial-intelligence), or ancestry path hash", "in": "path", "name": "id", "required": true, "schema": { "description": "Topic ID, ancestry slug (e.g., technology/artificial-intelligence), or ancestry path hash", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TopicDetail" } } }, "description": "OK", "headers": { "Payment-Receipt": { "description": "Base64url-encoded MPP receipt for a successful settlement. Absent for free or failed requests.", "schema": { "type": "string" } } } }, "402": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Payment Required. Read error_code. payment_required is the x402 path: either a keyless request being challenged — pay $0.01 in USDC per request (requirements in the PAYMENT-REQUIRED header) or send a pp_ API key — or a supplied payment that failed settlement (details in the PAYMENT-RESPONSE header; retry the same signature before signing a new one). See https://docs.particle.pro/x402. Any other code means the credential was accepted but does not cover this request (a plan or session gate such as premium_required or paid_plan_confirmation_required); its resolve says how to obtain access, and no payment header is sent. MPP is also accepted: follow WWW-Authenticate: Payment and retry with Authorization: Payment; successful MPP payments return Payment-Receipt.", "headers": { "WWW-Authenticate": { "description": "MPP Payment challenge. MCP responses may also advertise OAuth Bearer authentication.", "schema": { "type": "string" } } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/PlatformError" } } }, "description": "Error" } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] }, { "MPP": [] } ], "summary": "Get a topic", "tags": [ "Topics", "tier:standard" ], "x-cost-weight": 1, "x-payment-info": { "offers": [ { "amount": "10000", "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } ], "price": { "amount": "0.010000", "currency": "USD", "mode": "fixed" }, "protocols": [ { "x402": {} }, { "mpp": { "currency": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "intent": "charge", "method": "evm" } } ] }, "x-tier": "standard" } } }, "security": [ { "ApiKeyHeader": [] }, { "BearerAuth": [] } ], "servers": [ { "url": "https://api.particle.pro" } ], "x-service-info": { "categories": [ "data", "podcasts", "people", "companies" ], "docs": { "apiReference": "https://docs.particle.pro", "homepage": "https://platform.particle.pro", "llms": "/llms.txt" } } }