{"openapi":"3.0.0","paths":{"/health/live":{"get":{"description":"Returns 200 as long as the Node process is up. Does **not** check dependencies — a failed liveness probe should trigger a pod restart, and we do not want a flaky dependency to restart-loop the pod. Returns Terminus shape, **not** the V1 envelope.","operationId":"getHealthLive","parameters":[],"responses":{"200":{"description":"The Health Check is successful","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"ok"},"info":{"type":"object","example":{"database":{"status":"up"}},"additionalProperties":{"type":"object","required":["status"],"properties":{"status":{"type":"string"}},"additionalProperties":true},"nullable":true},"error":{"type":"object","example":{},"additionalProperties":{"type":"object","required":["status"],"properties":{"status":{"type":"string"}},"additionalProperties":true},"nullable":true},"details":{"type":"object","example":{"database":{"status":"up"}},"additionalProperties":{"type":"object","required":["status"],"properties":{"status":{"type":"string"}},"additionalProperties":true}}}}}}},"503":{"description":"The Health Check is not successful","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"error"},"info":{"type":"object","example":{"database":{"status":"up"}},"additionalProperties":{"type":"object","required":["status"],"properties":{"status":{"type":"string"}},"additionalProperties":true},"nullable":true},"error":{"type":"object","example":{"redis":{"status":"down","message":"Could not connect"}},"additionalProperties":{"type":"object","required":["status"],"properties":{"status":{"type":"string"}},"additionalProperties":true},"nullable":true},"details":{"type":"object","example":{"database":{"status":"up"},"redis":{"status":"down","message":"Could not connect"}},"additionalProperties":{"type":"object","required":["status"],"properties":{"status":{"type":"string"}},"additionalProperties":true}}}}}}}},"summary":"Liveness probe","tags":["System"]}},"/health/ready":{"get":{"description":"Returns 200 only when every downstream dependency the request path touches is healthy. A failed readiness probe should pull the pod out of the LB pool without restarting it. Returns Terminus shape, **not** the V1 envelope.","operationId":"getHealthReady","parameters":[],"responses":{"200":{"description":"The Health Check is successful","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"ok"},"info":{"type":"object","example":{"database":{"status":"up"}},"additionalProperties":{"type":"object","required":["status"],"properties":{"status":{"type":"string"}},"additionalProperties":true},"nullable":true},"error":{"type":"object","example":{},"additionalProperties":{"type":"object","required":["status"],"properties":{"status":{"type":"string"}},"additionalProperties":true},"nullable":true},"details":{"type":"object","example":{"database":{"status":"up"}},"additionalProperties":{"type":"object","required":["status"],"properties":{"status":{"type":"string"}},"additionalProperties":true}}}}}}},"503":{"description":"The Health Check is not successful","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"error"},"info":{"type":"object","example":{"database":{"status":"up"}},"additionalProperties":{"type":"object","required":["status"],"properties":{"status":{"type":"string"}},"additionalProperties":true},"nullable":true},"error":{"type":"object","example":{"redis":{"status":"down","message":"Could not connect"}},"additionalProperties":{"type":"object","required":["status"],"properties":{"status":{"type":"string"}},"additionalProperties":true},"nullable":true},"details":{"type":"object","example":{"database":{"status":"up"},"redis":{"status":"down","message":"Could not connect"}},"additionalProperties":{"type":"object","required":["status"],"properties":{"status":{"type":"string"}},"additionalProperties":true}}}}}}}},"summary":"Readiness probe","tags":["System"]}},"/health":{"get":{"description":"Backwards-compatible alias for `/health/ready`. Prefer the explicit `/health/ready` or `/health/live` endpoints for new integrations. Returns Terminus shape.","operationId":"getHealth","parameters":[],"responses":{"200":{"description":"The Health Check is successful","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"ok"},"info":{"type":"object","example":{"database":{"status":"up"}},"additionalProperties":{"type":"object","required":["status"],"properties":{"status":{"type":"string"}},"additionalProperties":true},"nullable":true},"error":{"type":"object","example":{},"additionalProperties":{"type":"object","required":["status"],"properties":{"status":{"type":"string"}},"additionalProperties":true},"nullable":true},"details":{"type":"object","example":{"database":{"status":"up"}},"additionalProperties":{"type":"object","required":["status"],"properties":{"status":{"type":"string"}},"additionalProperties":true}}}}}}},"503":{"description":"The Health Check is not successful","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"error"},"info":{"type":"object","example":{"database":{"status":"up"}},"additionalProperties":{"type":"object","required":["status"],"properties":{"status":{"type":"string"}},"additionalProperties":true},"nullable":true},"error":{"type":"object","example":{"redis":{"status":"down","message":"Could not connect"}},"additionalProperties":{"type":"object","required":["status"],"properties":{"status":{"type":"string"}},"additionalProperties":true},"nullable":true},"details":{"type":"object","example":{"database":{"status":"up"},"redis":{"status":"down","message":"Could not connect"}},"additionalProperties":{"type":"object","required":["status"],"properties":{"status":{"type":"string"}},"additionalProperties":true}}}}}}}},"summary":"Health (backwards-compatible alias)","tags":["System"]}},"/api/rest/v1/podcasts/{id}":{"get":{"description":"<div class=\"tier-pill-row\"><span class=\"tier-pill tier-pill--starter-plus\">Starter+</span></div>\n\nReturns the podcast envelope (`{ data, restricted_fields, meta }`). Tier-restricted fields are omitted from `data` and listed in `restricted_fields`. Accepts external identifiers via the `id_type` query param (`podchaser` default, or `apple_podcasts` / `spotify` / `rss`).","operationId":"getPodcastById","parameters":[{"name":"id","required":true,"in":"path","description":"Podcast identifier. Defaults to a Podchaser id (e.g. `1576373`); set `id_type` to resolve Apple Podcasts, Spotify, or RSS identifiers instead.","schema":{"example":"1576373","type":"string"}},{"name":"id_type","required":false,"in":"query","description":"Identifier type used in the path: `podchaser` (default), `apple_podcasts`, `spotify`, or `rss`.","schema":{"default":"podchaser","type":"string","enum":["podchaser","apple_podcasts","spotify","rss"]}}],"responses":{"200":{"description":"The podcast was found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PodcastResponseDto"},"examples":{"professional":{"summary":"Professional tier — full response","value":{"data":{"id":"1576373","applePodcastsId":"1545953110","spotifyId":"79CkJF3UJTHFV8Dse3Oy0P","rssUrl":"https://feeds.megaphone.fm/hubermanlab","title":"Huberman Lab","description":"The Huberman Lab podcast is hosted by Andrew Huberman, Ph.D., a neuroscientist and tenured professor in the department of neurobiology, and by courtesy, psychiatry and behavioral sciences at Stanford School of Medicine. The podcast discusses neuroscience and science-based tools, including how our brain and its connections with the organs of our body control our perceptions, our behaviors, and our health, as well as existing and emerging tools for measuring and changing how our nervous system works.","webUrl":"https://www.hubermanlab.com","imageUrl":"https://example.podchaser.com/podcast/1576373/cover.jpg","language":"en","numberOfEpisodes":411,"avgEpisodeLength":7053,"episodeFrequency":3,"startDate":"2020-12-21 05:22:00","latestEpisodeDate":"2026-05-14 08:00:00","categories":[{"title":"Health","slug":"health"},{"title":"Fitness","slug":"fitness"},{"title":"Science","slug":"science"}],"hasGuests":true,"explicit":false,"status":"active","author":{"name":"Scicomm Media","email":"podcast-verification@scicommedia.com"},"modifiedDate":"2026-05-15 10:52:11","hostingProvider":"Megaphone"},"restricted_fields":[],"meta":{"request_id":"01J9KX5Q8H3M0Z6Y7Q1F2A4N6P","tier":"professional","requests_remaining":4998}}}}}}},"400":{"description":"Validation error — malformed query parameters or path variables.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"401":{"description":"Missing or invalid API key (header `x-api-key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"403":{"description":"Caller tier does not have access to this endpoint or field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"404":{"description":"Podcast not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"429":{"description":"Rate limit exceeded. The `Retry-After` header carries the seconds to wait; `error.details.bucket` identifies which limit fired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"500":{"description":"Unexpected server error. Report `error.requestId` to support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"503":{"description":"A dependency is temporarily unavailable (`error.code = EXTERNAL_SERVICE_ERROR`). Retry with exponential back-off.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}}},"summary":"Get a podcast by ID","tags":["Podcasts"],"x-required-tier":"Starter+","x-tier-docs-only":true}},"/api/rest/v1/podcasts/{id}/reach":{"get":{"description":"<div class=\"tier-pill-row\"><span class=\"tier-pill tier-pill--starter-plus\">Starter+</span><span class=\"tier-pill tier-pill--aux tier-pill--professional\">+ Professional for full data</span></div><p class=\"tier-pill-prose\">Callers below **Starter+** receive `HTTP 403` with error code `TIER_RESTRICTED`. Some response fields require **Professional** — see the `(Starter+)` / `(Professional)` annotations on each field, and `restricted_fields` on the response envelope.</p>\n\nAggregated reach metrics (downloads, audience size).","operationId":"getPodcastReach","parameters":[{"name":"id","required":true,"in":"path","description":"Podchaser podcast id.","schema":{"example":"1576373","type":"string"}}],"responses":{"200":{"description":"Podcast reach data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PodcastReachResponseDto"}}}},"400":{"description":"Validation error — malformed query parameters or path variables.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"401":{"description":"Missing or invalid API key (header `x-api-key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"403":{"description":"Requires **Starter+** tier. Callers on a lower tier receive HTTP 403 with error code `TIER_RESTRICTED`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"404":{"description":"Podcast not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"429":{"description":"Rate limit exceeded. The `Retry-After` header carries the seconds to wait; `error.details.bucket` identifies which limit fired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"500":{"description":"Unexpected server error. Report `error.requestId` to support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"503":{"description":"A dependency is temporarily unavailable (`error.code = EXTERNAL_SERVICE_ERROR`). Retry with exponential back-off.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}}},"summary":"Get podcast reach data","tags":["Podcasts"],"x-required-tier":"Starter+"}},"/api/rest/v1/podcasts/{id}/episodes":{"get":{"description":"<div class=\"tier-pill-row\"><span class=\"tier-pill tier-pill--starter-plus\">Starter+</span></div>\n\nPaginated episode catalogue scoped to a single podcast. Use `sort=air_date` with `sort_direction=desc` and `per_page=1` to resolve the latest episode id before calling L3 enrichment tools (`get_episode_reach`, `get_episode_transcript`).","operationId":"getPodcastEpisodes","parameters":[{"name":"id","required":true,"in":"path","description":"Podcast identifier. Defaults to a Podchaser id; set `id_type` to resolve Apple Podcasts, Spotify, or RSS identifiers instead.","schema":{"example":"1576373","type":"string"}},{"name":"page","required":false,"in":"query","description":"Page number (1-indexed)","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"per_page","required":false,"in":"query","description":"Results per page. Optional — when omitted, defaults to the caller tier default (FREE=10, STARTER=25, PROFESSIONAL=25). Requesting a higher value is silently capped to the tier maximum (FREE=10, STARTER=25, PROFESSIONAL=100; no 400).","schema":{"type":"number"}},{"name":"id_type","required":false,"in":"query","description":"Identifier type used in the path: `podchaser` (default), `apple_podcasts`, `spotify`, or `rss`.","schema":{"default":"podchaser","type":"string","enum":["podchaser","apple_podcasts","spotify","rss"]}},{"name":"sort","required":false,"in":"query","description":"Sort field","schema":{"default":"air_date","type":"string","enum":["air_date"]}},{"name":"sort_direction","required":false,"in":"query","description":"Sort direction","schema":{"default":"desc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"Paginated episodes belonging to the podcast","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedEpisodeResponseDto"}}}},"400":{"description":"Validation error — malformed query parameters or path variables.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"401":{"description":"Missing or invalid API key (header `x-api-key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"403":{"description":"Caller tier does not have access to this endpoint or field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"404":{"description":"Podcast not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"429":{"description":"Rate limit exceeded. The `Retry-After` header carries the seconds to wait; `error.details.bucket` identifies which limit fired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"500":{"description":"Unexpected server error. Report `error.requestId` to support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"503":{"description":"A dependency is temporarily unavailable (`error.code = EXTERNAL_SERVICE_ERROR`). Retry with exponential back-off.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}}},"summary":"List episodes for a podcast","tags":["Podcasts"],"x-required-tier":"Starter+","x-tier-docs-only":true}},"/api/rest/v1/podcasts/{id}/charts":{"get":{"description":"<div class=\"tier-pill-row\"><span class=\"tier-pill tier-pill--professional\">Professional</span></div><p class=\"tier-pill-prose\">Callers below **Professional** receive `HTTP 403` with error code `TIER_RESTRICTED`.</p>\n\nChart positions for the podcast, scoped to the most recent day a chart is available in Podchaser's system. Omit 'platform' to get rankings across all platforms; pass 'platform' to filter. The `as_of_date` field on the response envelope indicates which day the response is anchored to (empty `data` with an `as_of_date` set means the podcast does not appear on that day's chart).","operationId":"getPodcastCharts","parameters":[{"name":"id","required":true,"in":"path","description":"Podchaser podcast id.","schema":{"example":"1576373","type":"string"}},{"name":"page","required":false,"in":"query","description":"Page number (1-indexed)","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"per_page","required":false,"in":"query","description":"Results per page. Optional — when omitted, defaults to the caller tier default (FREE=10, STARTER=25, PROFESSIONAL=25). Requesting a higher value is silently capped to the tier maximum (FREE=10, STARTER=25, PROFESSIONAL=100; no 400).","schema":{"type":"number"}},{"name":"platform","required":false,"in":"query","description":"Filter by platform. Omit to return current-day rankings across all platforms.","schema":{"type":"string","enum":["apple_podcasts","spotify"]}},{"name":"country","required":true,"in":"query","description":"Country code filter (lowercase ISO 3166-1 alpha-2). Defaults to `us` when omitted. Apple Podcasts: all 173 listed codes are supported. Spotify: only the following codes have chart data — ar, at, au, br, ca, cl, co, de, dk, es, fi, fr, gb, id, ie, in, it, jp, mx, nl, no, nz, ph, pl, se, us. Selecting an unsupported (platform, country) pair returns `400 VALIDATION_ERROR`.","schema":{"default":"us","example":"us","type":"string","enum":["ae","af","ag","ai","al","am","ao","ar","at","au","az","ba","bb","be","bf","bg","bh","bj","bn","bo","br","bs","bt","bw","by","bz","ca","cd","cg","ch","ci","cl","cm","cn","co","cr","cv","cy","cz","de","dk","dm","do","dz","ec","ee","eg","es","fi","fj","fm","fr","ga","gb","gd","ge","gh","gm","gr","gt","gw","gy","hk","hn","hr","hu","id","ie","il","in","iq","is","it","jm","jo","jp","ke","kg","kh","kn","kr","kw","ky","kz","la","lb","lc","lk","lr","lt","lu","lv","ly","ma","md","me","mg","mk","ml","mm","mn","mo","mr","ms","mt","mu","mv","mw","mx","my","mz","na","ne","ng","ni","nl","no","np","nr","nz","om","pa","pe","pg","ph","pk","pl","pt","pw","py","qa","ro","rs","ru","rw","sa","sb","sc","se","sg","si","sk","sl","sn","sr","st","sv","sz","tc","td","th","tj","tm","tn","to","tr","tt","tw","tz","ua","ug","us","uy","uz","vc","ve","vg","vn","vu","ye","za","zm","zw"]}},{"name":"category","required":true,"in":"query","description":"Category slug filter. Apple Podcasts: all 111 listed slugs are supported. Spotify: only the following 18 slugs have chart data — arts, business, comedy, education, fiction, health-and-fitness, history, leisure, music, news, religion-and-spirituality, science, society-and-culture, sports, technology, top-podcasts, true-crime, tv-and-film. Note: Apple and Spotify use different hyphenation for a handful of shared categories — Spotify spells them `tv-and-film`, `society-and-culture`, `religion-and-spirituality`, `health-and-fitness`; Apple spells them `tv-film`, `society-culture`, `religion-spirituality`, `health-fitness`. Selecting an unsupported (platform, category) pair returns `400 VALIDATION_ERROR` with the supported list for that platform.","schema":{"type":"string","enum":["allcategories","after-shows","alternative-health","animation-manga","arts","astronomy","automotive","aviation","baseball","basketball","books","buddhism","business","business-news","careers","chemistry","christianity","comedy","comedy-fiction","comedy-interviews","courses","crafts","cricket","daily-news","design","documentary","drama","earth-sciences","education","education-for-kids","entertainment-news","entrepreneurship","fantasy-sports","fashion-beauty","fiction","film-history","film-interviews","film-reviews","fitness","food","football","games","golf","government","health-and-fitness","health-fitness","hinduism","history","hobbies","hockey","home-garden","how-to","improv","investing","islam","judaism","kids-family","language-learning","leisure","life-sciences","management","marketing","mathematics","medicine","mental-health","music","music-commentary","music-history","music-interviews","natural-sciences","nature","news","news-commentary","non-profit","nutrition","parenting","performing-arts","personal-journals","pets-animals","philosophy","physics","places-travel","politics","relationships","religion","religion-and-spirituality","religion-spirituality","rugby","running","science","science-fiction","self-improvement","sexuality","soccer","social-sciences","society-and-culture","society-culture","spirituality","sports","sports-news","stand-up","stories-for-kids","swimming","tv-and-film","tv-film","tv-reviews","tech-news","technology","tennis","top-podcasts","true-crime","video-games","visual-arts","volleyball","wrestling"]}},{"name":"sort","required":false,"in":"query","description":"Sort field","schema":{"default":"position","type":"string","enum":["position","category","country"]}},{"name":"sort_direction","required":false,"in":"query","description":"Sort direction","schema":{"default":"asc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"Paginated podcast chart positions with as-of-date envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedPodcastChartResponseDto"}}}},"400":{"description":"Validation error — malformed query parameters or path variables.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"401":{"description":"Missing or invalid API key (header `x-api-key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"403":{"description":"Requires **Professional** tier. Callers on a lower tier receive HTTP 403 with error code `TIER_RESTRICTED`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"404":{"description":"Podcast not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"429":{"description":"Rate limit exceeded. The `Retry-After` header carries the seconds to wait; `error.details.bucket` identifies which limit fired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"500":{"description":"Unexpected server error. Report `error.requestId` to support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"503":{"description":"A dependency is temporarily unavailable (`error.code = EXTERNAL_SERVICE_ERROR`). Retry with exponential back-off.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}}},"summary":"Get podcast chart positions","tags":["Podcasts"],"x-required-tier":"Professional"}},"/api/rest/v1/podcasts/{id}/credits":{"get":{"description":"<div class=\"tier-pill-row\"><span class=\"tier-pill tier-pill--starter-plus\">Starter+</span></div><p class=\"tier-pill-prose\">Callers below **Starter+** receive `HTTP 403` with error code `TIER_RESTRICTED`.</p>\n\nPaginated cast / crew credits attached to the podcast.","operationId":"getPodcastCredits","parameters":[{"name":"id","required":true,"in":"path","description":"Podchaser podcast id.","schema":{"example":"1576373","type":"string"}},{"name":"page","required":false,"in":"query","description":"Page number (1-indexed)","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"per_page","required":false,"in":"query","description":"Results per page. Optional — when omitted, defaults to the caller tier default (FREE=10, STARTER=25, PROFESSIONAL=25). Requesting a higher value is silently capped to the tier maximum (FREE=10, STARTER=25, PROFESSIONAL=100; no 400).","schema":{"type":"number"}},{"name":"q","required":false,"in":"query","description":"Free-text search filtering credits by creator name. Forwarded to upstream `searchTerm`.","schema":{"type":"string"}},{"name":"role","required":false,"in":"query","description":"Comma-separated role codes (e.g., host, guest)","schema":{"type":"string"}},{"name":"episode_count_min","required":false,"in":"query","description":"Minimum episodes credited on","schema":{"type":"number"}},{"name":"sort","required":false,"in":"query","description":"Sort field","schema":{"default":"relevance","type":"string","enum":["relevance","date"]}},{"name":"sort_direction","required":false,"in":"query","description":"Sort direction","schema":{"default":"desc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"Paginated podcast credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedPodcastCreditResponseDto"},"examples":{"professional":{"summary":"Professional tier — full response","value":{"data":[{"creator":{"pcid":"452446","name":"Dr. Andrew Huberman","bio":"Dr. Andrew Huberman is a Neuroscientist and Professor in the Department of Neurobiology at the Stanford University School of Medicine.","imageUrl":"https://example.podchaser.com/creator/452446/avatar.jpg","url":"https://www.podchaser.com/creators/dr-andrew-huberman-107a4PnNz6"},"role":{"code":"host","title":"Host"},"episodeCount":410,"episodeCreditsModifiedDate":"2026-05-11 09:12:03","lastEpisode":{"id":"294698997","title":"Master Self Control & Overcome Procrastination | Dr. Kentaro Fujita","airDate":"2026-05-11 08:00:00","role":"host"}},{"creator":{"pcid":"976550","name":"Dr. Casey Halpern","bio":"Dr. Casey Halpern is a leading neurosurgeon and the Chief of Stereotactic and Functional Neurosurgery at Penn Medicine.","imageUrl":"https://example.podchaser.com/creator/976550/avatar.jpg","url":"https://www.podchaser.com/creators/dr-casey-halpern-108Ci4poLn"},"role":{"code":"guest","title":"Guest"},"episodeCount":1,"episodeCreditsModifiedDate":"2026-05-07 09:05:42","lastEpisode":{"id":"294242119","title":"Essentials: Compulsive Behaviors & Deep Brain Stimulation | Dr. Casey Halpern","airDate":"2026-05-07 08:00:00","role":"guest"}},{"creator":{"pcid":"939042","name":"Dr. Paul Conti","bio":"Dr. Paul Conti is a graduate of Stanford University School of Medicine.","imageUrl":"https://example.podchaser.com/creator/939042/avatar.jpg","url":"https://www.podchaser.com/creators/dr-paul-conti-107afwEMYI"},"role":{"code":"guest","title":"Guest"},"episodeCount":6,"episodeCreditsModifiedDate":"2026-05-04 09:18:11","lastEpisode":{"id":"293747848","title":"Tools to Bolster Your Mental Health & Confidence | Dr. Paul Conti","airDate":"2026-05-04 08:00:00","role":"guest"}}],"pagination":{"page":1,"per_page":25,"total_results":142,"total_pages":6,"has_more":true},"restricted_fields":[],"meta":{"request_id":"01J9KX5Q8H3M0Z6Y7Q1F2A4N6P","tier":"professional","requests_remaining":4998}}}}}}},"400":{"description":"Validation error — malformed query parameters or path variables.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"401":{"description":"Missing or invalid API key (header `x-api-key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"403":{"description":"Requires **Starter+** tier. Callers on a lower tier receive HTTP 403 with error code `TIER_RESTRICTED`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"404":{"description":"Podcast not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"429":{"description":"Rate limit exceeded. The `Retry-After` header carries the seconds to wait; `error.details.bucket` identifies which limit fired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"500":{"description":"Unexpected server error. Report `error.requestId` to support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"503":{"description":"A dependency is temporarily unavailable (`error.code = EXTERNAL_SERVICE_ERROR`). Retry with exponential back-off.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}}},"summary":"Get podcast credits","tags":["Podcasts"],"x-required-tier":"Starter+"}},"/api/rest/v1/podcasts/{id}/demographics":{"get":{"description":"<div class=\"tier-pill-row\"><span class=\"tier-pill tier-pill--starter-plus\">Starter+</span></div><p class=\"tier-pill-prose\">Callers below **Starter+** receive `HTTP 403` with error code `TIER_RESTRICTED`.</p>\n\nAudience demographics (age / gender breakdowns).","operationId":"getPodcastDemographics","parameters":[{"name":"id","required":true,"in":"path","description":"Podchaser podcast id.","schema":{"example":"1576373","type":"string"}}],"responses":{"200":{"description":"Podcast demographics","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PodcastDemographicsResponseDto"}}}},"400":{"description":"Validation error — malformed query parameters or path variables.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"401":{"description":"Missing or invalid API key (header `x-api-key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"403":{"description":"Requires **Starter+** tier. Callers on a lower tier receive HTTP 403 with error code `TIER_RESTRICTED`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"404":{"description":"Podcast not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"429":{"description":"Rate limit exceeded. The `Retry-After` header carries the seconds to wait; `error.details.bucket` identifies which limit fired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"500":{"description":"Unexpected server error. Report `error.requestId` to support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"503":{"description":"A dependency is temporarily unavailable (`error.code = EXTERNAL_SERVICE_ERROR`). Retry with exponential back-off.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}}},"summary":"Get podcast demographics","tags":["Podcasts"],"x-required-tier":"Starter+"}},"/api/rest/v1/podcasts/{id}/brandsafety":{"get":{"description":"<div class=\"tier-pill-row\"><span class=\"tier-pill tier-pill--professional\">Professional</span></div><p class=\"tier-pill-prose\">Callers below **Professional** receive `HTTP 403` with error code `TIER_RESTRICTED`.</p>\n\nBrand-safety risk assessments (category codes, severity levels).","operationId":"getPodcastBrandSafety","parameters":[{"name":"id","required":true,"in":"path","description":"Podchaser podcast id.","schema":{"example":"1576373","type":"string"}}],"responses":{"200":{"description":"Podcast brand safety risk assessments","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PodcastBrandSafetyResponseDto"}}}}},"400":{"description":"Validation error — malformed query parameters or path variables.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"401":{"description":"Missing or invalid API key (header `x-api-key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"403":{"description":"Requires **Professional** tier. Callers on a lower tier receive HTTP 403 with error code `TIER_RESTRICTED`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"404":{"description":"Podcast not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"429":{"description":"Rate limit exceeded. The `Retry-After` header carries the seconds to wait; `error.details.bucket` identifies which limit fired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"500":{"description":"Unexpected server error. Report `error.requestId` to support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"503":{"description":"A dependency is temporarily unavailable (`error.code = EXTERNAL_SERVICE_ERROR`). Retry with exponential back-off.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}}},"summary":"Get podcast brand safety","tags":["Podcasts"],"x-required-tier":"Professional"}},"/api/rest/v1/podcasts/{id}/network":{"get":{"description":"<div class=\"tier-pill-row\"><span class=\"tier-pill tier-pill--starter-plus\">Starter+</span></div><p class=\"tier-pill-prose\">Callers below **Starter+** receive `HTTP 403` with error code `TIER_RESTRICTED`.</p>\n\nNetworks the podcast belongs to (empty array for independent podcasts).","operationId":"getPodcastNetwork","parameters":[{"name":"id","required":true,"in":"path","description":"Podchaser podcast id.","schema":{"example":"1576373","type":"string"}}],"responses":{"200":{"description":"Networks the podcast belongs to (empty array for independent podcasts)","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/NetworkResponseDto"}}}}},"400":{"description":"Validation error — malformed query parameters or path variables.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"401":{"description":"Missing or invalid API key (header `x-api-key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"403":{"description":"Requires **Starter+** tier. Callers on a lower tier receive HTTP 403 with error code `TIER_RESTRICTED`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"404":{"description":"Podcast not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"429":{"description":"Rate limit exceeded. The `Retry-After` header carries the seconds to wait; `error.details.bucket` identifies which limit fired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"500":{"description":"Unexpected server error. Report `error.requestId` to support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"503":{"description":"A dependency is temporarily unavailable (`error.code = EXTERNAL_SERVICE_ERROR`). Retry with exponential back-off.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}}},"summary":"Get podcast network(s)","tags":["Podcasts"],"x-required-tier":"Starter+"}},"/api/rest/v1/podcasts/{id}/similar":{"get":{"description":"<div class=\"tier-pill-row\"><span class=\"tier-pill tier-pill--starter-plus\">Starter+</span></div>\n\nPaginated list of podcasts similar to the given podcast, ranked by Podchaser similarity score.","operationId":"getPodcastSimilar","parameters":[{"name":"id","required":true,"in":"path","description":"Podchaser podcast id.","schema":{"example":"1576373","type":"string"}},{"name":"page","required":false,"in":"query","description":"Page number (1-indexed)","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"per_page","required":false,"in":"query","description":"Results per page. Optional — when omitted, defaults to the caller tier default (FREE=10, STARTER=25, PROFESSIONAL=25). Requesting a higher value is silently capped to the tier maximum (FREE=10, STARTER=25, PROFESSIONAL=100; no 400).","schema":{"type":"number"}}],"responses":{"200":{"description":"Paginated similar podcasts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedPodcastResponseDto"}}}},"400":{"description":"Validation error — malformed query parameters or path variables.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"401":{"description":"Missing or invalid API key (header `x-api-key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"403":{"description":"Caller tier does not have access to this endpoint or field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"404":{"description":"Podcast not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"429":{"description":"Rate limit exceeded. The `Retry-After` header carries the seconds to wait; `error.details.bucket` identifies which limit fired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"500":{"description":"Unexpected server error. Report `error.requestId` to support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"503":{"description":"A dependency is temporarily unavailable (`error.code = EXTERNAL_SERVICE_ERROR`). Retry with exponential back-off.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}}},"summary":"Get similar podcasts","tags":["Podcasts"],"x-required-tier":"Starter+","x-tier-docs-only":true}},"/api/rest/v1/podcasts/{id}/contacts":{"get":{"description":"<div class=\"tier-pill-row\"><span class=\"tier-pill tier-pill--starter-plus\">Starter+</span><span class=\"tier-pill tier-pill--aux tier-pill--professional\">+ Professional for full data</span></div><p class=\"tier-pill-prose\">Callers below **Starter+** receive `HTTP 403` with error code `TIER_RESTRICTED`. Some response fields require **Professional** — see the `(Starter+)` / `(Professional)` annotations on each field, and `restricted_fields` on the response envelope.</p>\n\nPaginated podcast contacts. Field availability is tier-driven — see the `(Starter+)` / `(Professional)` annotations on each response field.","operationId":"getPodcastContacts","parameters":[{"name":"id","required":true,"in":"path","description":"Podchaser podcast id.","schema":{"example":"1576373","type":"string"}},{"name":"page","required":false,"in":"query","description":"Page number (1-indexed)","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"per_page","required":false,"in":"query","description":"Results per page. Optional — when omitted, defaults to the caller tier default (FREE=10, STARTER=25, PROFESSIONAL=25). Requesting a higher value is silently capped to the tier maximum (FREE=10, STARTER=25, PROFESSIONAL=100; no 400).","schema":{"type":"number"}},{"name":"sort","required":false,"in":"query","description":"Sort order. `relevance` (default) ranks by role priority, URL/name presence, flagged-last. `alphabetical` orders by full name with role as the tiebreaker. Professional+ only — at Starter the response is at most one row.","schema":{"default":"relevance","type":"string","enum":["relevance","alphabetical"]}},{"name":"sort_direction","required":false,"in":"query","description":"Sort direction. `asc` (default) preserves the upstream order for the chosen `sort`; `desc` reverses the upstream contact list before pagination. Professional+ only — no effect at Starter (single-row result).","schema":{"default":"asc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"Paginated podcast contacts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedPodcastContactResponseDto"}}}},"400":{"description":"Validation error — malformed query parameters or path variables.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"401":{"description":"Missing or invalid API key (header `x-api-key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"403":{"description":"Requires **Starter+** tier. Callers on a lower tier receive HTTP 403 with error code `TIER_RESTRICTED`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"404":{"description":"Podcast not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"429":{"description":"Rate limit exceeded. The `Retry-After` header carries the seconds to wait; `error.details.bucket` identifies which limit fired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"500":{"description":"Unexpected server error. Report `error.requestId` to support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"503":{"description":"A dependency is temporarily unavailable (`error.code = EXTERNAL_SERVICE_ERROR`). Retry with exponential back-off.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}}},"summary":"Get podcast contacts","tags":["Podcasts"],"x-required-tier":"Starter+"}},"/api/rest/v1/podcasts/{id}/socials":{"get":{"description":"<div class=\"tier-pill-row\"><span class=\"tier-pill tier-pill--starter-plus\">Starter+</span><span class=\"tier-pill tier-pill--aux tier-pill--professional\">+ Professional for full data</span></div><p class=\"tier-pill-prose\">Callers below **Starter+** receive `HTTP 403` with error code `TIER_RESTRICTED`. Some response fields require **Professional** — see the `(Starter+)` / `(Professional)` annotations on each field, and `restricted_fields` on the response envelope.</p>\n\nPodcast social presence: per-platform URLs and follower counts, plus host creator socials. Field availability is tier-driven — see the `(Starter+)` / `(Professional)` annotations on each response field.","operationId":"getPodcastSocials","parameters":[{"name":"id","required":true,"in":"path","description":"Podchaser podcast id.","schema":{"example":"1576373","type":"string"}}],"responses":{"200":{"description":"Podcast social presence","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PodcastSocialsResponseDto"}}}},"400":{"description":"Validation error — malformed query parameters or path variables.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"401":{"description":"Missing or invalid API key (header `x-api-key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"403":{"description":"Requires **Starter+** tier. Callers on a lower tier receive HTTP 403 with error code `TIER_RESTRICTED`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"404":{"description":"Podcast not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"429":{"description":"Rate limit exceeded. The `Retry-After` header carries the seconds to wait; `error.details.bucket` identifies which limit fired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"500":{"description":"Unexpected server error. Report `error.requestId` to support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"503":{"description":"A dependency is temporarily unavailable (`error.code = EXTERNAL_SERVICE_ERROR`). Retry with exponential back-off.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}}},"summary":"Get podcast socials","tags":["Podcasts"],"x-required-tier":"Starter+"}},"/api/rest/v1/podcasts/{id}/sponsors/{brand_id}/episodes":{"get":{"description":"<div class=\"tier-pill-row\"><span class=\"tier-pill tier-pill--professional\">Professional</span></div><p class=\"tier-pill-prose\">Callers below **Professional** receive `HTTP 403` with error code `TIER_RESTRICTED`.</p>\n\nPaginated list of episodes where the given brand sponsors this podcast, with ad placement details (start/end time, estimated spend).","operationId":"getPodcastSponsorEpisodes","parameters":[{"name":"id","required":true,"in":"path","description":"Podchaser podcast id.","schema":{"example":"1576373","type":"string"}},{"name":"brand_id","required":true,"in":"path","description":"Podchaser brand id.","schema":{"example":"236","type":"string"}},{"name":"page","required":false,"in":"query","description":"Page number","schema":{"default":1,"type":"number"}},{"name":"per_page","required":false,"in":"query","description":"Results per page","schema":{"default":25,"type":"number"}},{"name":"sort","required":false,"in":"query","description":"Sort field","schema":{"default":"air_date","type":"string","enum":["air_date"]}},{"name":"sort_direction","required":false,"in":"query","description":"Sort direction","schema":{"default":"desc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"Paginated episode-level sponsorship placements for the brand","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedPodcastSponsorEpisodeResponseDto"}}}},"400":{"description":"Validation error — malformed query parameters or path variables.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"401":{"description":"Missing or invalid API key (header `x-api-key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"403":{"description":"Requires **Professional** tier. Callers on a lower tier receive HTTP 403 with error code `TIER_RESTRICTED`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"404":{"description":"Podcast or brand not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"429":{"description":"Rate limit exceeded. The `Retry-After` header carries the seconds to wait; `error.details.bucket` identifies which limit fired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"500":{"description":"Unexpected server error. Report `error.requestId` to support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"503":{"description":"A dependency is temporarily unavailable (`error.code = EXTERNAL_SERVICE_ERROR`). Retry with exponential back-off.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}}},"summary":"Get episodes sponsored by a specific brand on this podcast","tags":["Podcasts"],"x-required-tier":"Professional"}},"/api/rest/v1/podcasts/{id}/sponsors":{"get":{"description":"<div class=\"tier-pill-row\"><span class=\"tier-pill tier-pill--professional\">Professional</span></div><p class=\"tier-pill-prose\">Callers below **Professional** receive `HTTP 403` with error code `TIER_RESTRICTED`.</p>\n\nPaginated brand-level sponsor summaries for this podcast (episode count, latest episode date, estimated total ad spend).","operationId":"getPodcastSponsors","parameters":[{"name":"id","required":true,"in":"path","description":"Podchaser podcast id.","schema":{"example":"1576373","type":"string"}},{"name":"q","required":false,"in":"query","description":"Search term to filter brand names","schema":{"type":"string"}},{"name":"page","required":false,"in":"query","description":"Page number","schema":{"default":1,"type":"number"}},{"name":"per_page","required":false,"in":"query","description":"Results per page","schema":{"default":25,"type":"number"}},{"name":"sort","required":false,"in":"query","description":"Sort field.","schema":{"default":"latest_episode","type":"string","enum":["latest_episode"]}},{"name":"sort_direction","required":false,"in":"query","description":"Sort direction","schema":{"default":"desc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"Paginated brand-level sponsor summaries for this podcast","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedPodcastSponsorResponseDto"}}}},"400":{"description":"Validation error — malformed query parameters or path variables.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"401":{"description":"Missing or invalid API key (header `x-api-key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"403":{"description":"Requires **Professional** tier. Callers on a lower tier receive HTTP 403 with error code `TIER_RESTRICTED`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"404":{"description":"Podcast not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"429":{"description":"Rate limit exceeded. The `Retry-After` header carries the seconds to wait; `error.details.bucket` identifies which limit fired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"500":{"description":"Unexpected server error. Report `error.requestId` to support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"503":{"description":"A dependency is temporarily unavailable (`error.code = EXTERNAL_SERVICE_ERROR`). Retry with exponential back-off.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}}},"summary":"Get podcast sponsors","tags":["Podcasts"],"x-required-tier":"Professional"}},"/api/rest/v1/episodes/{id}":{"get":{"description":"<div class=\"tier-pill-row\"><span class=\"tier-pill tier-pill--starter-plus\">Starter+</span></div>\n\nReturns the episode envelope (`{ data, restricted_fields, meta }`). Tier-restricted fields are omitted from `data` and listed in `restricted_fields`.","operationId":"getEpisodeById","parameters":[{"name":"id","required":true,"in":"path","description":"Podchaser episode id (e.g. `987654`).","schema":{"example":"987654","type":"string"}}],"responses":{"200":{"description":"The episode was found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EpisodeResponseDto"},"examples":{"professional":{"summary":"Professional tier — full response","value":{"data":{"id":"293747848","title":"Tools to Bolster Your Mental Health & Confidence | Dr. Paul Conti","description":"Dr. Paul Conti, MD, is a board-certified psychiatrist and an expert in how to improve mental health and increase your sense of agency and wellbeing. We discuss practical tools you can use to gain insight into your natural strengths and to make better life choices on your own behalf, and explore how to balance internal reflection and external action to move your life forward.","airDate":"2026-05-04 08:00:00","imageUrl":"https://example.podchaser.com/episode/293747848/cover.jpg","audioUrl":"https://traffic.megaphone.fm/SCIM9301011958.mp3","webUrl":"https://www.podchaser.com/podcasts/huberman-lab-1576373/episodes/tools-to-bolster-your-mental-h-293747848","length":7817,"explicit":false,"episodeType":"full","guid":"c3a2dab6-475a-11f1-9ec4-4ff354be9c5e","fileSize":125072000,"modifiedDate":"2026-05-14 17:22:09","podcast":{"id":"1576373","title":"Huberman Lab","rss":"https://feeds.megaphone.fm/hubermanlab","imageUrl":"https://example.podchaser.com/podcast/1576373/cover.jpg"}},"restricted_fields":[],"meta":{"request_id":"01J9KX5Q8H3M0Z6Y7Q1F2A4N6P","tier":"professional","requests_remaining":4998}}}}}}},"400":{"description":"Validation error — malformed query parameters or path variables.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"401":{"description":"Missing or invalid API key (header `x-api-key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"403":{"description":"Caller tier does not have access to this endpoint or field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"404":{"description":"Episode not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"429":{"description":"Rate limit exceeded. The `Retry-After` header carries the seconds to wait; `error.details.bucket` identifies which limit fired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"500":{"description":"Unexpected server error. Report `error.requestId` to support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"503":{"description":"A dependency is temporarily unavailable (`error.code = EXTERNAL_SERVICE_ERROR`). Retry with exponential back-off.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}}},"summary":"Get an episode by ID","tags":["Episodes"],"x-required-tier":"Starter+","x-tier-docs-only":true}},"/api/rest/v1/episodes/{id}/reach":{"get":{"description":"<div class=\"tier-pill-row\"><span class=\"tier-pill tier-pill--starter-plus\">Starter+</span><span class=\"tier-pill tier-pill--aux tier-pill--professional\">+ Professional for full data</span></div><p class=\"tier-pill-prose\">Callers below **Starter+** receive `HTTP 403` with error code `TIER_RESTRICTED`. Some response fields require **Professional** — see the `(Starter+)` / `(Professional)` annotations on each field, and `restricted_fields` on the response envelope.</p>\n\nReach metrics for a single episode (downloads, audience power score).","operationId":"getEpisodeReach","parameters":[{"name":"id","required":true,"in":"path","description":"Podchaser episode id.","schema":{"example":"296613276","type":"string"}}],"responses":{"200":{"description":"Episode reach data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EpisodeReachResponseDto"}}}},"400":{"description":"Validation error — malformed query parameters or path variables.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"401":{"description":"Missing or invalid API key (header `x-api-key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"403":{"description":"Requires **Starter+** tier. Callers on a lower tier receive HTTP 403 with error code `TIER_RESTRICTED`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"404":{"description":"Episode not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"429":{"description":"Rate limit exceeded. The `Retry-After` header carries the seconds to wait; `error.details.bucket` identifies which limit fired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"500":{"description":"Unexpected server error. Report `error.requestId` to support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"503":{"description":"A dependency is temporarily unavailable (`error.code = EXTERNAL_SERVICE_ERROR`). Retry with exponential back-off.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}}},"summary":"Get episode reach data","tags":["Episodes"],"x-required-tier":"Starter+"}},"/api/rest/v1/episodes/{id}/credits":{"get":{"description":"<div class=\"tier-pill-row\"><span class=\"tier-pill tier-pill--starter-plus\">Starter+</span></div><p class=\"tier-pill-prose\">Callers below **Starter+** receive `HTTP 403` with error code `TIER_RESTRICTED`.</p>\n\nPaginated cast / crew credits attached to the episode.","operationId":"getEpisodeCredits","parameters":[{"name":"id","required":true,"in":"path","description":"Podchaser episode id.","schema":{"example":"987654","type":"string"}},{"name":"page","required":false,"in":"query","description":"Page number (1-indexed)","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"per_page","required":false,"in":"query","description":"Results per page. Optional — when omitted, defaults to the caller tier default (FREE=10, STARTER=25, PROFESSIONAL=25). Requesting a higher value is silently capped to the tier maximum (FREE=10, STARTER=25, PROFESSIONAL=100; no 400).","schema":{"type":"number"}},{"name":"q","required":false,"in":"query","description":"Search term to filter credits","schema":{"type":"string"}},{"name":"role","required":false,"in":"query","description":"Comma-separated role codes (e.g., host, guest)","schema":{"type":"string"}},{"name":"sort","required":false,"in":"query","description":"Sort field","schema":{"default":"relevance","type":"string","enum":["relevance","date"]}},{"name":"sort_direction","required":false,"in":"query","description":"Sort direction","schema":{"default":"desc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"Paginated episode credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedEpisodeCreditResponseDto"},"examples":{"professional":{"summary":"Professional tier — full response","value":{"data":[{"id":"46388410","creator":{"pcid":"452446","name":"Dr. Andrew Huberman","imageUrl":"https://example.podchaser.com/creator/452446/avatar.jpg"},"role":{"code":"host","title":"Host"},"characters":[]},{"id":"46388748","creator":{"pcid":"939042","name":"Dr. Paul Conti","imageUrl":"https://example.podchaser.com/creator/939042/avatar.jpg"},"role":{"code":"guest","title":"Guest"},"characters":[]}],"pagination":{"page":1,"per_page":2,"total_results":2,"total_pages":1,"has_more":false},"restricted_fields":[],"meta":{"request_id":"01J9KX5Q8H3M0Z6Y7Q1F2A4N6P","tier":"professional","requests_remaining":4998}}}}}}},"400":{"description":"Validation error — malformed query parameters or path variables.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"401":{"description":"Missing or invalid API key (header `x-api-key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"403":{"description":"Requires **Starter+** tier. Callers on a lower tier receive HTTP 403 with error code `TIER_RESTRICTED`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"404":{"description":"Episode not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"429":{"description":"Rate limit exceeded. The `Retry-After` header carries the seconds to wait; `error.details.bucket` identifies which limit fired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"500":{"description":"Unexpected server error. Report `error.requestId` to support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"503":{"description":"A dependency is temporarily unavailable (`error.code = EXTERNAL_SERVICE_ERROR`). Retry with exponential back-off.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}}},"summary":"Get episode credits","tags":["Episodes"],"x-required-tier":"Starter+"}},"/api/rest/v1/episodes/{id}/brandsafety":{"get":{"description":"<div class=\"tier-pill-row\"><span class=\"tier-pill tier-pill--professional\">Professional</span></div><p class=\"tier-pill-prose\">Callers below **Professional** receive `HTTP 403` with error code `TIER_RESTRICTED`.</p>\n\nBrand-safety scores (profanity, sensitive topics) for the episode.","operationId":"getEpisodeBrandSafety","parameters":[{"name":"id","required":true,"in":"path","description":"Podchaser episode id.","schema":{"example":"987654","type":"string"}}],"responses":{"200":{"description":"Episode brand safety data","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/EpisodeBrandSafetyResponseDto"}}}}},"400":{"description":"Validation error — malformed query parameters or path variables.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"401":{"description":"Missing or invalid API key (header `x-api-key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"403":{"description":"Requires **Professional** tier. Callers on a lower tier receive HTTP 403 with error code `TIER_RESTRICTED`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"404":{"description":"Episode not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"429":{"description":"Rate limit exceeded. The `Retry-After` header carries the seconds to wait; `error.details.bucket` identifies which limit fired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"500":{"description":"Unexpected server error. Report `error.requestId` to support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"503":{"description":"A dependency is temporarily unavailable (`error.code = EXTERNAL_SERVICE_ERROR`). Retry with exponential back-off.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}}},"summary":"Get episode brand safety","tags":["Episodes"],"x-required-tier":"Professional"}},"/api/rest/v1/episodes/{id}/transcript":{"get":{"description":"<div class=\"tier-pill-row\"><span class=\"tier-pill tier-pill--starter-plus\">Starter+</span></div>\n\nTranscript content for the episode when available. Open to all tiers; transcript availability depends on Podchaser data.","operationId":"getEpisodeTranscript","parameters":[{"name":"id","required":true,"in":"path","description":"Podchaser episode id.","schema":{"example":"987654","type":"string"}}],"responses":{"200":{"description":"Episode transcript data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EpisodeTranscriptResponseDto"}}}},"400":{"description":"Validation error — malformed query parameters or path variables.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"401":{"description":"Missing or invalid API key (header `x-api-key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"403":{"description":"Caller tier does not have access to this endpoint or field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"404":{"description":"Episode not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"429":{"description":"Rate limit exceeded. The `Retry-After` header carries the seconds to wait; `error.details.bucket` identifies which limit fired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"500":{"description":"Unexpected server error. Report `error.requestId` to support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"503":{"description":"A dependency is temporarily unavailable (`error.code = EXTERNAL_SERVICE_ERROR`). Retry with exponential back-off.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}}},"summary":"Get episode transcript","tags":["Episodes"],"x-required-tier":"Starter+","x-tier-docs-only":true}},"/api/rest/v1/search/podcasts":{"get":{"description":"<div class=\"tier-pill-row\"><span class=\"tier-pill tier-pill--starter-plus\">Starter+</span></div>\n\nPaginated full-text + filter search over the Podchaser podcast catalogue. Supports `q`, category and language filters, and tier-driven sort options. Per-page caps follow the standard tier table (Starter 25 / Professional 100); requests that exceed the cap are silently capped and the effective value is reflected in `pagination.per_page`.","operationId":"searchPodcasts","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (1-indexed)","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"per_page","required":false,"in":"query","description":"Results per page. Optional — when omitted, defaults to the caller tier default (FREE=10, STARTER=25, PROFESSIONAL=25). Requesting a higher value is silently capped to the tier maximum (FREE=10, STARTER=25, PROFESSIONAL=100; no 400).","schema":{"type":"number"}},{"name":"q","required":false,"in":"query","description":"Free-text search query. When `bool_search=true`, parsed as a boolean expression supporting AND, OR, NOT, and parentheses (validated by `validateBooleanExpression`).","schema":{"type":"string"}},{"name":"bool_search","required":false,"in":"query","description":"When true, `q` is parsed as a boolean expression. When false / omitted, `q` is treated as free text. Accepts the strings `true`/`false`/`1`/`0`.","schema":{"default":false,"type":"boolean"}},{"name":"sort","required":false,"in":"query","description":"Sort field","schema":{"default":"relevance","type":"string","enum":["relevance","power_score","date_of_first_episode","alphabetical"]}},{"name":"sort_direction","required":false,"in":"query","description":"Sort direction (`asc` or `desc`). Default varies per endpoint — each `/search/*` resource declares its own `<Resource>SortPolicy` whose `directionByField` table is the source of truth. When the caller omits this field, the use case resolves the default from that policy; the base class deliberately ships NO default so a subclass field initializer can never accidentally mask the per-endpoint policy (under `useDefineForClassFields: true` a parent initializer runs unless the subclass explicitly resets the property — rather than hand-waving that override on every subclass, the base simply leaves the field undefined).","schema":{"type":"string","enum":["asc","desc"]}},{"name":"categories","required":false,"in":"query","description":"Comma-separated category slugs","schema":{"type":"string"}},{"name":"language","required":false,"in":"query","description":"Language code (e.g., en, es). See GET /reference/languages for the full catalogue.","schema":{"example":"en","type":"string","enum":["en","ab","aa","af","ag","ai","ak","al","sq","am","ar","an","hy","as","au","av","ay","az","bm","bn","ba","eu","be","bf","bh","bi","bs","br","bu","bg","my","ca","cc","cd","cg","ch","ce","zh","cu","cv","ck","cl","cm","cn","kw","co","cr","hr","cz","cs","da","di","dv","dj","dk","do","ds","du","nl","dy","dz","eb","eo","et","ew","ee","fo","fj","fi","fr","fu","ff","gl","lg","ge","ka","de","gh","gr","el","gs","gt","gn","gu","ht","ha","he","iw","hz","hi","ho","hm","hs","hu","is","io","ig","il","im","id","in","ia","ie","iu","ik","ga","it","iv","ja","jv","jw","jg","jm","jo","jp","ju","kl","kn","kr","ks","kk","ke","kh","km","ki","rw","kg","ko","ku","ky","lo","la","lv","le","li","ln","lt","lk","lr","lu","lb","ma","mk","mg","ms","ml","mt","gv","mi","mr","md","me","mf","mn","mu","mx","mz","na","nv","ne","ni","nm","nd","se","no","nb","nn","nu","ny","oc","or","om","os","ps","pc","fa","pg","po","pl","pt","pr","pa","qu","rh","mo","ro","rm","rs","rn","ru","sm","sg","sa","sc","sb","gd","sr","sh","sn","ii","sd","si","sk","sl","so","nr","st","sp","es","su","sw","ss","sv","tl","ty","tg","ta","tt","tc","te","th","bo","ti","to","ts","tn","tr","tk","tw","tz","ua","uk","un","ur","us","ug","uz","va","ve","vi","vn","vu","wa","cy","fy","wo","xh","xo","ya","ye","ji","yi","yo","yu","zg","za","zu","zx","zz"]}},{"name":"status","required":false,"in":"query","description":"Comma-separated: active, idle, complete","schema":{"type":"string"}},{"name":"has_guests","required":false,"in":"query","description":"Filter by guest presence","schema":{"type":"boolean"}},{"name":"hosting_providers","required":false,"in":"query","description":"Comma-separated hosting provider names (e.g. Acast,Libsyn). Values are case-sensitive and combined with OR. Use GET /reference/hosting-providers for the catalogue.","schema":{"type":"string"}},{"name":"start_date_from","required":false,"in":"query","description":"Podcast start date from (ISO 8601)","schema":{"type":"string"}},{"name":"start_date_to","required":false,"in":"query","description":"Podcast start date to (ISO 8601)","schema":{"type":"string"}},{"name":"latest_episode_from","required":false,"in":"query","description":"Date of last episode from (ISO 8601)","schema":{"type":"string"}},{"name":"latest_episode_to","required":false,"in":"query","description":"Date of last episode to (ISO 8601)","schema":{"type":"string"}},{"name":"added_date_from","required":false,"in":"query","description":"Date added to Podchaser from (ISO 8601)","schema":{"type":"string"}},{"name":"added_date_to","required":false,"in":"query","description":"Date added to Podchaser to (ISO 8601)","schema":{"type":"string"}},{"name":"modified_date_from","required":false,"in":"query","description":"Date last modified from (ISO 8601)","schema":{"type":"string"}},{"name":"modified_date_to","required":false,"in":"query","description":"Date last modified to (ISO 8601)","schema":{"type":"string"}},{"name":"include_removed","required":false,"in":"query","description":"Include removed podcasts in results","schema":{"default":false,"type":"boolean"}},{"name":"power_score_min","required":false,"in":"query","description":"Power Score min (0-100). Starter+","schema":{"type":"number"}},{"name":"power_score_max","required":false,"in":"query","description":"Power Score max (0-100). Starter+","schema":{"type":"number"}},{"name":"network_id","required":false,"in":"query","description":"Network Podchaser ID. Starter+","schema":{"minimum":1,"type":"number"}},{"name":"network_title","required":false,"in":"query","description":"Network title. Starter+","schema":{"type":"string"}},{"name":"political_skew","required":false,"in":"query","description":"Comma-separated political skew: high_left, medium_left, low_left, neutral, low_right, medium_right, high_right. Starter+","schema":{"type":"string"}},{"name":"gender_bias","required":false,"in":"query","description":"Comma-separated gender bias: high_male, moderate_male, mixed, moderate_female, high_female. Starter+","schema":{"type":"string"}},{"name":"age_range","required":false,"in":"query","description":"Comma-separated age range keys. Starter+","schema":{"type":"string"}},{"name":"income_tier","required":false,"in":"query","description":"Comma-separated income tier: income_tier_0 through income_tier_4. Starter+","schema":{"type":"array","items":{"type":"string","enum":["income_tier_0","income_tier_1","income_tier_2","income_tier_3","income_tier_4"]}}},{"name":"parental_status","required":false,"in":"query","description":"Comma-separated parental status: parent, non_parent, mixed, high_parent, high_non_parent. Starter+","schema":{"type":"array","items":{"type":"string","enum":["mixed","non_parent","parent","high_parent","high_non_parent"]}}},{"name":"education_level","required":false,"in":"query","description":"Comma-separated education level: higher_education, mixed, no_higher_education. Starter+","schema":{"type":"array","items":{"type":"string","enum":["higher_education","mixed","no_higher_education"]}}},{"name":"marital_status","required":false,"in":"query","description":"Comma-separated marital status: married, mixed, not_married. Starter+","schema":{"type":"array","items":{"type":"string","enum":["married","mixed","not_married"]}}},{"name":"country","required":false,"in":"query","description":"Demographic country filter. Starter+","schema":{"type":"string"}},{"name":"monthly_reach_min","required":false,"in":"query","description":"Monthly audience estimate min. Pro+","schema":{"type":"number"}},{"name":"monthly_reach_max","required":false,"in":"query","description":"Monthly audience estimate max. Pro+","schema":{"type":"number"}},{"name":"episode_reach_min","required":false,"in":"query","description":"Per-episode audience estimate min. Pro+","schema":{"type":"number"}},{"name":"episode_reach_max","required":false,"in":"query","description":"Per-episode audience estimate max. Pro+","schema":{"type":"number"}},{"name":"brand_safety_exclude","required":false,"in":"query","description":"Comma-separated brand safety risk codes to exclude. Pro+. Required when `brand_safety_max_level` is set — exclusions are applied per risk code, so a max level on its own has no code to scope to.","schema":{"type":"string"}},{"name":"brand_safety_max_level","required":false,"in":"query","description":"Max risk level: clean, low, medium, high. Pro+. Must be combined with `brand_safety_exclude` — see that field.","schema":{"type":"string","enum":["clean","low","medium","high"]}}],"responses":{"200":{"description":"Paginated podcasts matching the search and filter criteria","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PodcastResponseDto"}},"examples":{"professional":{"summary":"Professional tier — full response","value":{"data":[{"id":"1576373","applePodcastsId":"1545953110","spotifyId":"79CkJF3UJTHFV8Dse3Oy0P","rssUrl":"https://feeds.megaphone.fm/hubermanlab","title":"Huberman Lab","description":"The Huberman Lab podcast is hosted by Andrew Huberman, Ph.D., a neuroscientist and tenured professor in the department of neurobiology, and by courtesy, psychiatry and behavioral sciences at Stanford School of Medicine. The podcast discusses neuroscience and science-based tools, including how our brain and its connections with the organs of our body control our perceptions, our behaviors, and our health, as well as existing and emerging tools for measuring and changing how our nervous system works.","webUrl":"https://www.hubermanlab.com","imageUrl":"https://example.podchaser.com/podcast/1576373/cover.jpg","language":"en","numberOfEpisodes":411,"avgEpisodeLength":7053,"episodeFrequency":3,"startDate":"2020-12-21 05:22:00","latestEpisodeDate":"2026-05-14 08:00:00","categories":[{"title":"Health","slug":"health"},{"title":"Fitness","slug":"fitness"},{"title":"Science","slug":"science"}],"hasGuests":true,"explicit":false,"status":"active","author":{"name":"Scicomm Media","email":"podcast-verification@scicommedia.com"},"modifiedDate":"2026-05-15 10:52:11","hostingProvider":"Megaphone"}],"pagination":{"page":1,"per_page":25,"total_results":312,"total_pages":13,"has_more":true},"restricted_fields":[],"meta":{"request_id":"01J9KX5Q8H3M0Z6Y7Q1F2A4N6P","tier":"professional","requests_remaining":4998}}}}}}},"400":{"description":"Validation error — malformed query parameters or path variables.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"401":{"description":"Missing or invalid API key (header `x-api-key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"403":{"description":"Caller tier does not have access to this endpoint or field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"404":{"description":"The requested resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"429":{"description":"Rate limit exceeded. The `Retry-After` header carries the seconds to wait; `error.details.bucket` identifies which limit fired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"500":{"description":"Unexpected server error. Report `error.requestId` to support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"503":{"description":"A dependency is temporarily unavailable (`error.code = EXTERNAL_SERVICE_ERROR`). Retry with exponential back-off.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}}},"summary":"Search podcasts","tags":["Search"],"x-required-tier":"Starter+","x-tier-docs-only":true}},"/api/rest/v1/search/episodes":{"get":{"description":"<div class=\"tier-pill-row\"><span class=\"tier-pill tier-pill--starter-plus\">Starter+</span></div>\n\nPaginated full-text + filter search over the Podchaser episode catalogue. Filters include `q`, podcast id, air-date range and explicit flag. Per-page caps are tier-driven (Starter 25 / Professional 100); over-cap requests are silently capped and the effective value is reflected in `pagination.per_page`.","operationId":"searchEpisodes","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (1-indexed)","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"per_page","required":false,"in":"query","description":"Results per page. Optional — when omitted, defaults to the caller tier default (FREE=10, STARTER=25, PROFESSIONAL=25). Requesting a higher value is silently capped to the tier maximum (FREE=10, STARTER=25, PROFESSIONAL=100; no 400).","schema":{"type":"number"}},{"name":"q","required":false,"in":"query","description":"Free-text search query. When `bool_search=true`, parsed as a boolean expression supporting AND, OR, NOT, and parentheses (validated by `validateBooleanExpression`).","schema":{"type":"string"}},{"name":"bool_search","required":false,"in":"query","description":"When true, `q` is parsed as a boolean expression. When false / omitted, `q` is treated as free text. Accepts the strings `true`/`false`/`1`/`0`.","schema":{"default":false,"type":"boolean"}},{"name":"sort","required":false,"in":"query","description":"Sort field","schema":{"default":"relevance","type":"string","enum":["relevance","alphabetical","air_date"]}},{"name":"sort_direction","required":false,"in":"query","description":"Sort direction (`asc` or `desc`). Default varies per endpoint — each `/search/*` resource declares its own `<Resource>SortPolicy` whose `directionByField` table is the source of truth. When the caller omits this field, the use case resolves the default from that policy; the base class deliberately ships NO default so a subclass field initializer can never accidentally mask the per-endpoint policy (under `useDefineForClassFields: true` a parent initializer runs unless the subclass explicitly resets the property — rather than hand-waving that override on every subclass, the base simply leaves the field undefined).","schema":{"type":"string","enum":["asc","desc"]}},{"name":"air_date_from","required":false,"in":"query","description":"Episode air date from (ISO 8601)","schema":{"type":"string"}},{"name":"air_date_to","required":false,"in":"query","description":"Episode air date to (ISO 8601)","schema":{"type":"string"}},{"name":"length_min","required":false,"in":"query","description":"Episode length min (seconds)","schema":{"type":"number"}},{"name":"length_max","required":false,"in":"query","description":"Episode length max (seconds)","schema":{"type":"number"}},{"name":"categories","required":false,"in":"query","description":"Comma-separated category slugs (matched against the episode's podcast)","schema":{"type":"string"}},{"name":"categories_operator","required":false,"in":"query","description":"How to combine multiple `categories` terms: `or` returns episodes whose podcast is in ANY of the categories, `and` requires ALL. Default: `or`.","schema":{"default":"or","type":"string","enum":["and","or"]}},{"name":"episode_type","required":false,"in":"query","description":"Comma-separated episode types: full, bonus, trailer","schema":{"type":"string"}},{"name":"explicit","required":false,"in":"query","description":"Filter by whether the episode is flagged explicit by the publisher","schema":{"type":"boolean"}},{"name":"language","required":false,"in":"query","description":"Podcast language code (e.g., en, es) — matches the episode's podcast. See GET /reference/languages for the full catalogue.","schema":{"example":"en","type":"string","enum":["en","ab","aa","af","ag","ai","ak","al","sq","am","ar","an","hy","as","au","av","ay","az","bm","bn","ba","eu","be","bf","bh","bi","bs","br","bu","bg","my","ca","cc","cd","cg","ch","ce","zh","cu","cv","ck","cl","cm","cn","kw","co","cr","hr","cz","cs","da","di","dv","dj","dk","do","ds","du","nl","dy","dz","eb","eo","et","ew","ee","fo","fj","fi","fr","fu","ff","gl","lg","ge","ka","de","gh","gr","el","gs","gt","gn","gu","ht","ha","he","iw","hz","hi","ho","hm","hs","hu","is","io","ig","il","im","id","in","ia","ie","iu","ik","ga","it","iv","ja","jv","jw","jg","jm","jo","jp","ju","kl","kn","kr","ks","kk","ke","kh","km","ki","rw","kg","ko","ku","ky","lo","la","lv","le","li","ln","lt","lk","lr","lu","lb","ma","mk","mg","ms","ml","mt","gv","mi","mr","md","me","mf","mn","mu","mx","mz","na","nv","ne","ni","nm","nd","se","no","nb","nn","nu","ny","oc","or","om","os","ps","pc","fa","pg","po","pl","pt","pr","pa","qu","rh","mo","ro","rm","rs","rn","ru","sm","sg","sa","sc","sb","gd","sr","sh","sn","ii","sd","si","sk","sl","so","nr","st","sp","es","su","sw","ss","sv","tl","ty","tg","ta","tt","tc","te","th","bo","ti","to","ts","tn","tr","tk","tw","tz","ua","uk","un","ur","us","ug","uz","va","ve","vi","vn","vu","wa","cy","fy","wo","xh","xo","ya","ye","ji","yi","yo","yu","zg","za","zu","zx","zz"]}},{"name":"hosting_providers","required":false,"in":"query","description":"Comma-separated hosting provider names (e.g. Acast,Libsyn). Matches the episode's podcast. Values are case-sensitive and combined with OR. Use GET /reference/hosting-providers for the catalogue.","schema":{"type":"string"}},{"name":"added_date_from","required":false,"in":"query","description":"Date added to Podchaser from (ISO 8601)","schema":{"type":"string"}},{"name":"added_date_to","required":false,"in":"query","description":"Date added to Podchaser to (ISO 8601)","schema":{"type":"string"}},{"name":"modified_date_from","required":false,"in":"query","description":"Date last modified from (ISO 8601)","schema":{"type":"string"}},{"name":"modified_date_to","required":false,"in":"query","description":"Date last modified to (ISO 8601)","schema":{"type":"string"}},{"name":"podcast_power_score_min","required":false,"in":"query","description":"Podcast Power Score min (0-100) — matches the episode's podcast. Starter+","schema":{"type":"number"}},{"name":"podcast_power_score_max","required":false,"in":"query","description":"Podcast Power Score max (0-100) — matches the episode's podcast. Starter+","schema":{"type":"number"}},{"name":"has_transcript","required":false,"in":"query","description":"Only episodes that have at least one transcript available. Starter+","schema":{"type":"boolean"}},{"name":"transcript_created_from","required":false,"in":"query","description":"Transcript most-recently-created date from (ISO 8601). Starter+","schema":{"type":"string"}},{"name":"transcript_created_to","required":false,"in":"query","description":"Transcript most-recently-created date to (ISO 8601). Starter+","schema":{"type":"string"}},{"name":"education_level","required":false,"in":"query","description":"Comma-separated education level: higher_education, mixed, no_higher_education. Filters by parent podcast audience. Starter+","schema":{"type":"array","items":{"type":"string","enum":["higher_education","mixed","no_higher_education"]}}},{"name":"marital_status","required":false,"in":"query","description":"Comma-separated marital status: married, mixed, not_married. Filters by parent podcast audience. Starter+","schema":{"type":"array","items":{"type":"string","enum":["married","mixed","not_married"]}}},{"name":"episode_reach_min","required":false,"in":"query","description":"Per-episode audience estimate min. Pro+","schema":{"type":"number"}},{"name":"episode_reach_max","required":false,"in":"query","description":"Per-episode audience estimate max. Pro+","schema":{"type":"number"}}],"responses":{"200":{"description":"Paginated episodes matching the search and filter criteria","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/EpisodeResponseDto"}},"examples":{"professional":{"summary":"Professional tier — full response","value":{"data":[{"id":"293747848","title":"Tools to Bolster Your Mental Health & Confidence | Dr. Paul Conti","description":"Dr. Paul Conti, MD, is a board-certified psychiatrist and an expert in how to improve mental health and increase your sense of agency and wellbeing. We discuss practical tools you can use to gain insight into your natural strengths and to make better life choices on your own behalf, and explore how to balance internal reflection and external action to move your life forward.","airDate":"2026-05-04 08:00:00","imageUrl":"https://example.podchaser.com/episode/293747848/cover.jpg","audioUrl":"https://traffic.megaphone.fm/SCIM9301011958.mp3","webUrl":"https://www.podchaser.com/podcasts/huberman-lab-1576373/episodes/tools-to-bolster-your-mental-h-293747848","length":7817,"explicit":false,"episodeType":"full","guid":"c3a2dab6-475a-11f1-9ec4-4ff354be9c5e","fileSize":125072000,"modifiedDate":"2026-05-14 17:22:09","podcast":{"id":"1576373","title":"Huberman Lab","rss":"https://feeds.megaphone.fm/hubermanlab","imageUrl":"https://example.podchaser.com/podcast/1576373/cover.jpg"}}],"pagination":{"page":1,"per_page":25,"total_results":1284,"total_pages":52,"has_more":true},"restricted_fields":[],"meta":{"request_id":"01J9KX5Q8H3M0Z6Y7Q1F2A4N6P","tier":"professional","requests_remaining":4998}}}}}}},"400":{"description":"Validation error — malformed query parameters or path variables.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"401":{"description":"Missing or invalid API key (header `x-api-key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"403":{"description":"Caller tier does not have access to this endpoint or field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"404":{"description":"The requested resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"429":{"description":"Rate limit exceeded. The `Retry-After` header carries the seconds to wait; `error.details.bucket` identifies which limit fired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"500":{"description":"Unexpected server error. Report `error.requestId` to support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"503":{"description":"A dependency is temporarily unavailable (`error.code = EXTERNAL_SERVICE_ERROR`). Retry with exponential back-off.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}}},"summary":"Search episodes","tags":["Search"],"x-required-tier":"Starter+","x-tier-docs-only":true}},"/api/rest/v1/search/transcripts":{"get":{"description":"<div class=\"tier-pill-row\"><span class=\"tier-pill tier-pill--starter-plus\">Starter+</span></div>\n\nPaginated transcript search: returns the episodes whose transcripts contain `q`, with the matched mention snippets surfaced inline so callers can preview context without a follow-up `/episodes/{id}/transcript` fetch. Per-page caps are tier-driven (Starter 25 / Professional 100); transcript availability depends on Podchaser data.","operationId":"searchTranscripts","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (1-indexed)","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"per_page","required":false,"in":"query","description":"Results per page. Optional — when omitted, defaults to the caller tier default (FREE=10, STARTER=25, PROFESSIONAL=25). Requesting a higher value is silently capped to the tier maximum (FREE=10, STARTER=25, PROFESSIONAL=100; no 400).","schema":{"type":"number"}},{"name":"q","required":false,"in":"query","description":"Free-text search query. When `bool_search=true`, parsed as a boolean expression supporting AND, OR, NOT, and parentheses (validated by `validateBooleanExpression`).","schema":{"type":"string"}},{"name":"bool_search","required":false,"in":"query","description":"When true, `q` is parsed as a boolean expression. When false / omitted, `q` is treated as free text. Accepts the strings `true`/`false`/`1`/`0`.","schema":{"default":false,"type":"boolean"}},{"name":"sort","required":false,"in":"query","description":"Sort field. Concrete DTOs override this with `@IsEnum(<ResourceSortField>)` so each endpoint declares its own allow-list.","schema":{"type":"string"}},{"name":"sort_direction","required":false,"in":"query","description":"Sort direction (`asc` or `desc`). Default varies per endpoint — each `/search/*` resource declares its own `<Resource>SortPolicy` whose `directionByField` table is the source of truth. When the caller omits this field, the use case resolves the default from that policy; the base class deliberately ships NO default so a subclass field initializer can never accidentally mask the per-endpoint policy (under `useDefineForClassFields: true` a parent initializer runs unless the subclass explicitly resets the property — rather than hand-waving that override on every subclass, the base simply leaves the field undefined).","schema":{"type":"string","enum":["asc","desc"]}},{"name":"mentions_per_episode","required":false,"in":"query","description":"Max mentions returned per episode (default: 10, `0` = all mentions). Large values can cause the request to time out.","schema":{"minimum":0,"type":"number"}},{"name":"podcast_id","required":false,"in":"query","description":"Podcast identifier to scope search to. Must be combined with `id_type`. For Podchaser IDs this is a numeric string.","schema":{"type":"string"}},{"name":"id_type","required":false,"in":"query","description":"Interprets `podcast_id`: `podchaser`, `apple_podcasts`, `spotify`, or `rss`. Required when `podcast_id` is set.","schema":{"type":"string","enum":["podchaser","apple_podcasts","spotify","rss"]}},{"name":"air_date_from","required":false,"in":"query","description":"Episode air date from (ISO 8601)","schema":{"type":"string"}},{"name":"air_date_to","required":false,"in":"query","description":"Episode air date to (ISO 8601)","schema":{"type":"string"}},{"name":"categories","required":false,"in":"query","description":"Comma-separated category slugs","schema":{"type":"string"}},{"name":"transcript_created_from","required":false,"in":"query","description":"Transcript creation date from (ISO 8601)","schema":{"type":"string"}},{"name":"transcript_created_to","required":false,"in":"query","description":"Transcript creation date to (ISO 8601)","schema":{"type":"string"}},{"name":"language","required":false,"in":"query","description":"Language code (e.g., en, es). See GET /reference/languages for the full catalogue.","schema":{"example":"en","type":"string","enum":["en","ab","aa","af","ag","ai","ak","al","sq","am","ar","an","hy","as","au","av","ay","az","bm","bn","ba","eu","be","bf","bh","bi","bs","br","bu","bg","my","ca","cc","cd","cg","ch","ce","zh","cu","cv","ck","cl","cm","cn","kw","co","cr","hr","cz","cs","da","di","dv","dj","dk","do","ds","du","nl","dy","dz","eb","eo","et","ew","ee","fo","fj","fi","fr","fu","ff","gl","lg","ge","ka","de","gh","gr","el","gs","gt","gn","gu","ht","ha","he","iw","hz","hi","ho","hm","hs","hu","is","io","ig","il","im","id","in","ia","ie","iu","ik","ga","it","iv","ja","jv","jw","jg","jm","jo","jp","ju","kl","kn","kr","ks","kk","ke","kh","km","ki","rw","kg","ko","ku","ky","lo","la","lv","le","li","ln","lt","lk","lr","lu","lb","ma","mk","mg","ms","ml","mt","gv","mi","mr","md","me","mf","mn","mu","mx","mz","na","nv","ne","ni","nm","nd","se","no","nb","nn","nu","ny","oc","or","om","os","ps","pc","fa","pg","po","pl","pt","pr","pa","qu","rh","mo","ro","rm","rs","rn","ru","sm","sg","sa","sc","sb","gd","sr","sh","sn","ii","sd","si","sk","sl","so","nr","st","sp","es","su","sw","ss","sv","tl","ty","tg","ta","tt","tc","te","th","bo","ti","to","ts","tn","tr","tk","tw","tz","ua","uk","un","ur","us","ug","uz","va","ve","vi","vn","vu","wa","cy","fy","wo","xh","xo","ya","ye","ji","yi","yo","yu","zg","za","zu","zx","zz"]}},{"name":"power_score_min","required":false,"in":"query","description":"Power Score min (0-100). Starter+","schema":{"type":"number"}},{"name":"power_score_max","required":false,"in":"query","description":"Power Score max (0-100). Starter+","schema":{"type":"number"}}],"responses":{"200":{"description":"Paginated episodes whose transcripts match the search term, with matched mention snippets","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/TranscriptSearchResultDto"}},"examples":{"professional":{"summary":"Professional tier — full response","value":{"data":[{"mentionCount":3,"episode":{"id":"293747848","title":"Tools to Bolster Your Mental Health & Confidence | Dr. Paul Conti","description":"Dr. Paul Conti, MD, is a board-certified psychiatrist and an expert in how to improve mental health and increase your sense of agency and wellbeing. We discuss practical tools you can use to gain insight into your natural strengths and to make better life choices on your own behalf, and explore how to balance internal reflection and external action to move your life forward.","airDate":"2026-05-04 08:00:00","imageUrl":"https://example.podchaser.com/episode/293747848/cover.jpg","audioUrl":"https://traffic.megaphone.fm/SCIM9301011958.mp3","webUrl":"https://www.podchaser.com/podcasts/huberman-lab-1576373/episodes/tools-to-bolster-your-mental-h-293747848","length":7817,"explicit":false,"episodeType":"full","guid":"c3a2dab6-475a-11f1-9ec4-4ff354be9c5e","fileSize":125072000,"modifiedDate":"2026-05-14 17:22:09","podcast":{"id":"1576373","title":"Huberman Lab","rss":"https://feeds.megaphone.fm/hubermanlab","imageUrl":"https://example.podchaser.com/podcast/1576373/cover.jpg"}},"mentions":[{"startTime":"00:14:22","endTime":"00:14:38","snippet":"And the dopaminergic system, which is what we keep coming back to, ultimately governs motivation more than reward."},{"startTime":"00:31:07","endTime":"00:31:21","snippet":"So when you think about dopamine, think about it as the molecule of pursuit, not the molecule of pleasure."},{"startTime":"01:02:55","endTime":"01:03:09","snippet":"Tools that increase baseline dopamine — sleep, sunlight, cold exposure — without spiking it artificially."}]}],"pagination":{"page":1,"per_page":25,"total_results":47,"total_pages":2,"has_more":true},"restricted_fields":[],"meta":{"request_id":"01J9KX5Q8H3M0Z6Y7Q1F2A4N6P","tier":"professional","requests_remaining":4998}}}}}}},"400":{"description":"Validation error — malformed query parameters or path variables.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"401":{"description":"Missing or invalid API key (header `x-api-key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"403":{"description":"Caller tier does not have access to this endpoint or field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"404":{"description":"The requested resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"429":{"description":"Rate limit exceeded. The `Retry-After` header carries the seconds to wait; `error.details.bucket` identifies which limit fired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"500":{"description":"Unexpected server error. Report `error.requestId` to support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"503":{"description":"A dependency is temporarily unavailable (`error.code = EXTERNAL_SERVICE_ERROR`). Retry with exponential back-off.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}}},"summary":"Search transcripts","tags":["Search"],"x-required-tier":"Starter+","x-tier-docs-only":true}},"/api/rest/v1/search/networks":{"get":{"description":"<div class=\"tier-pill-row\"><span class=\"tier-pill tier-pill--starter-plus\">Starter+</span></div><p class=\"tier-pill-prose\">Callers below **Starter+** receive `HTTP 403` with error code `TIER_RESTRICTED`.</p>\n\nPaginated list of networks matching the search term.","operationId":"searchNetworks","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (1-indexed)","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"per_page","required":false,"in":"query","description":"Results per page. Optional — when omitted, defaults to the caller tier default (FREE=10, STARTER=25, PROFESSIONAL=25). Requesting a higher value is silently capped to the tier maximum (FREE=10, STARTER=25, PROFESSIONAL=100; no 400).","schema":{"type":"number"}},{"name":"q","required":false,"in":"query","description":"Free-text search query. When `bool_search=true`, parsed as a boolean expression supporting AND, OR, NOT, and parentheses (validated by `validateBooleanExpression`).","schema":{"type":"string"}},{"name":"bool_search","required":false,"in":"query","description":"When true, `q` is parsed as a boolean expression. When false / omitted, `q` is treated as free text. Accepts the strings `true`/`false`/`1`/`0`.","schema":{"default":false,"type":"boolean"}},{"name":"sort","required":false,"in":"query","description":"Sort field","schema":{"default":"podcast_count","type":"string","enum":["alphabetical","podcast_count"]}},{"name":"sort_direction","required":false,"in":"query","description":"Sort direction (`asc` or `desc`). Default varies per endpoint — each `/search/*` resource declares its own `<Resource>SortPolicy` whose `directionByField` table is the source of truth. When the caller omits this field, the use case resolves the default from that policy; the base class deliberately ships NO default so a subclass field initializer can never accidentally mask the per-endpoint policy (under `useDefineForClassFields: true` a parent initializer runs unless the subclass explicitly resets the property — rather than hand-waving that override on every subclass, the base simply leaves the field undefined).","schema":{"type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"Paginated networks matching the search term","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/NetworkResponseDto"}}}}},"400":{"description":"Validation error — malformed query parameters or path variables.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"401":{"description":"Missing or invalid API key (header `x-api-key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"403":{"description":"Requires **Starter+** tier. Callers on a lower tier receive HTTP 403 with error code `TIER_RESTRICTED`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"404":{"description":"The requested resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"429":{"description":"Rate limit exceeded. The `Retry-After` header carries the seconds to wait; `error.details.bucket` identifies which limit fired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"500":{"description":"Unexpected server error. Report `error.requestId` to support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"503":{"description":"A dependency is temporarily unavailable (`error.code = EXTERNAL_SERVICE_ERROR`). Retry with exponential back-off.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}}},"summary":"Search networks","tags":["Search"],"x-required-tier":"Starter+"}},"/api/rest/v1/search/creators":{"get":{"description":"<div class=\"tier-pill-row\"><span class=\"tier-pill tier-pill--starter-plus\">Starter+</span></div><p class=\"tier-pill-prose\">Callers below **Starter+** receive `HTTP 403` with error code `TIER_RESTRICTED`.</p>\n\nPaginated list of creators matching `q` and the `modified_date_*` filter. The response body follows the same `{ data, pagination }` shape as `/search/podcasts`.","operationId":"searchCreators","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (1-indexed)","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"per_page","required":false,"in":"query","description":"Results per page. Optional — when omitted, defaults to the caller tier default (FREE=10, STARTER=25, PROFESSIONAL=25). Requesting a higher value is silently capped to the tier maximum (FREE=10, STARTER=25, PROFESSIONAL=100; no 400).","schema":{"type":"number"}},{"name":"q","required":false,"in":"query","description":"Free-text search query. Forwarded to upstream `searchTerm`.","schema":{"type":"string"}},{"name":"sort","required":false,"in":"query","description":"Sort field","schema":{"default":"relevance","type":"string","enum":["relevance","alphabetical","recent_episode","appearance_count"]}},{"name":"sort_direction","required":false,"in":"query","description":"Sort direction (`asc` or `desc`). Default varies per sort field — resolved by `CreatorSortPolicy.directionByField[sort]`.","schema":{"type":"string","enum":["asc","desc"]}},{"name":"modified_date_from","required":false,"in":"query","description":"Date last modified from (ISO 8601)","schema":{"type":"string"}},{"name":"modified_date_to","required":false,"in":"query","description":"Date last modified to (ISO 8601)","schema":{"type":"string"}}],"responses":{"200":{"description":"Paginated creators matching the search and filter criteria","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CreatorResponseDto"}}}}},"400":{"description":"Validation error — malformed query parameters or path variables.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"401":{"description":"Missing or invalid API key (header `x-api-key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"403":{"description":"Requires **Starter+** tier. Callers on a lower tier receive HTTP 403 with error code `TIER_RESTRICTED`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"404":{"description":"The requested resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"429":{"description":"Rate limit exceeded. The `Retry-After` header carries the seconds to wait; `error.details.bucket` identifies which limit fired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"500":{"description":"Unexpected server error. Report `error.requestId` to support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"503":{"description":"A dependency is temporarily unavailable (`error.code = EXTERNAL_SERVICE_ERROR`). Retry with exponential back-off.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}}},"summary":"Search creators","tags":["Search"],"x-required-tier":"Starter+"}},"/api/rest/v1/search/sponsors":{"get":{"description":"<div class=\"tier-pill-row\"><span class=\"tier-pill tier-pill--professional\">Professional</span></div><p class=\"tier-pill-prose\">Callers below **Professional** receive `HTTP 403` with error code `TIER_RESTRICTED`.</p>\n\nPaginated list of sponsors (brands) matching `q`, ordered by the upstream BRAND search resolver. V1 supports `sort=alphabetical` only — four PRD-listed values (`relevancy`, `podcasts_sponsored`, `episodes_sponsored`, `ad_spend`) are deferred until upstream `BrandSortType` exposes matching enum members. `bool_search` is NOT supported on this endpoint because `Query.brands` upstream has no `SearchOptions` argument.","operationId":"searchSponsors","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (1-indexed)","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"per_page","required":false,"in":"query","description":"Results per page. Optional — when omitted, defaults to the caller tier default (FREE=10, STARTER=25, PROFESSIONAL=25). Requesting a higher value is silently capped to the tier maximum (FREE=10, STARTER=25, PROFESSIONAL=100; no 400).","schema":{"type":"number"}},{"name":"q","required":false,"in":"query","description":"Free-text brand-name search. Forwarded to upstream `searchTerm`.","schema":{"type":"string"}},{"name":"sort","required":false,"in":"query","description":"Sort field. Supported values: `alphabetical` (default, A→Z), `podcasts_sponsored` (unique podcasts the brand has sponsored over the last 180 days), `episodes_sponsored` (episodes sponsored over the last 180 days), `ad_spend` (estimated ad spend, high estimate over the last 30 days — mirrors `GET /brands` ordering). The three metric sorts default to descending (highest first). `relevancy` is not yet supported — upstream `BrandSortType` has no matching member.","schema":{"default":"alphabetical","type":"string","enum":["alphabetical","podcasts_sponsored","episodes_sponsored","ad_spend"]}},{"name":"sort_direction","required":false,"in":"query","description":"Sort direction (`asc` or `desc`). Default varies per sort field — resolved by `SponsorSearchSortPolicy.directionByField[sort]`. `alphabetical` defaults to ASC; `podcasts_sponsored`, `episodes_sponsored`, and `ad_spend` default to DESC.","schema":{"type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"Paginated sponsors matching the search term","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SponsorResponseDto"}}}}},"400":{"description":"Validation error — malformed query parameters or path variables.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"401":{"description":"Missing or invalid API key (header `x-api-key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"403":{"description":"Requires **Professional** tier. Callers on a lower tier receive HTTP 403 with error code `TIER_RESTRICTED`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"404":{"description":"The requested resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"429":{"description":"Rate limit exceeded. The `Retry-After` header carries the seconds to wait; `error.details.bucket` identifies which limit fired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"500":{"description":"Unexpected server error. Report `error.requestId` to support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"503":{"description":"A dependency is temporarily unavailable (`error.code = EXTERNAL_SERVICE_ERROR`). Retry with exponential back-off.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}}},"summary":"Search sponsors","tags":["Search"],"x-required-tier":"Professional"}},"/api/rest/v1/usage":{"get":{"description":"<div class=\"tier-pill-row\"><span class=\"tier-pill tier-pill--starter-plus\">Starter+</span></div>\n\nReturns the authenticated caller's tier, quota, used, and remaining request counts. Calls to this endpoint do NOT count against the monthly quota.","operationId":"getUsage","parameters":[],"responses":{"200":{"description":"Current usage for the authenticated caller","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageResponseDto"}}}},"400":{"description":"Validation error — malformed query parameters or path variables.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"401":{"description":"Missing or invalid API key (header `x-api-key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"403":{"description":"Caller tier does not have access to this endpoint or field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"404":{"description":"The requested resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"429":{"description":"Rate limit exceeded. The `Retry-After` header carries the seconds to wait; `error.details.bucket` identifies which limit fired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"500":{"description":"Unexpected server error. Report `error.requestId` to support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"503":{"description":"A dependency is temporarily unavailable (`error.code = EXTERNAL_SERVICE_ERROR`). Retry with exponential back-off.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}}},"summary":"Get current request usage","tags":["Usage"],"x-required-tier":"Starter+","x-tier-docs-only":true}},"/api/rest/v1/creators/{pcid}":{"get":{"description":"<div class=\"tier-pill-row\"><span class=\"tier-pill tier-pill--starter-plus\">Starter+</span></div><p class=\"tier-pill-prose\">Callers below **Starter+** receive `HTTP 403` with error code `TIER_RESTRICTED`.</p>\n\nReturns the creator envelope (`{ data, restricted_fields, meta }`). Tier-restricted fields are omitted from `data` and listed in `restricted_fields`.","operationId":"getCreatorById","parameters":[{"name":"pcid","required":true,"in":"path","description":"Podchaser creator id (e.g. `8`).","schema":{"example":"8","type":"string"}}],"responses":{"200":{"description":"The creator was found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatorResponseDto"}}}},"400":{"description":"Validation error — malformed query parameters or path variables.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"401":{"description":"Missing or invalid API key (header `x-api-key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"403":{"description":"Requires **Starter+** tier. Callers on a lower tier receive HTTP 403 with error code `TIER_RESTRICTED`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"404":{"description":"Creator not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"429":{"description":"Rate limit exceeded. The `Retry-After` header carries the seconds to wait; `error.details.bucket` identifies which limit fired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"500":{"description":"Unexpected server error. Report `error.requestId` to support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"503":{"description":"A dependency is temporarily unavailable (`error.code = EXTERNAL_SERVICE_ERROR`). Retry with exponential back-off.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}}},"summary":"Get a creator by Podchaser ID","tags":["Creators"],"x-required-tier":"Starter+"}},"/api/rest/v1/creators/{pcid}/podcasts":{"get":{"description":"<div class=\"tier-pill-row\"><span class=\"tier-pill tier-pill--starter-plus\">Starter+</span></div><p class=\"tier-pill-prose\">Callers below **Starter+** receive `HTTP 403` with error code `TIER_RESTRICTED`.</p>\n\nPaginated list of podcasts the creator is credited on, with the most recent episode credit inline. Pagination is silently capped at the caller's tier `per_page` max.","operationId":"getCreatorPodcasts","parameters":[{"name":"pcid","required":true,"in":"path","description":"Podchaser creator id.","schema":{"example":"8","type":"string"}},{"name":"page","required":false,"in":"query","description":"Page number (1-indexed)","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"per_page","required":false,"in":"query","description":"Results per page. Optional — when omitted, defaults to the caller tier default (FREE=10, STARTER=25, PROFESSIONAL=25). Requesting a higher value is silently capped to the tier maximum (FREE=10, STARTER=25, PROFESSIONAL=100; no 400).","schema":{"type":"number"}},{"name":"q","required":false,"in":"query","description":"Search term to filter podcast titles","schema":{"type":"string"}},{"name":"role","required":false,"in":"query","description":"Comma-separated role codes (e.g., host, guest)","schema":{"type":"string"}},{"name":"sort","required":false,"in":"query","description":"Sort field","schema":{"default":"date","type":"string","enum":["date","relevance"]}},{"name":"sort_direction","required":false,"in":"query","description":"Sort direction","schema":{"default":"desc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"Paginated list of creator podcast credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedCreatorPodcastCreditResponseDto"}}}},"400":{"description":"Validation error — malformed query parameters or path variables.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"401":{"description":"Missing or invalid API key (header `x-api-key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"403":{"description":"Requires **Starter+** tier. Callers on a lower tier receive HTTP 403 with error code `TIER_RESTRICTED`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"404":{"description":"Creator not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"429":{"description":"Rate limit exceeded. The `Retry-After` header carries the seconds to wait; `error.details.bucket` identifies which limit fired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"500":{"description":"Unexpected server error. Report `error.requestId` to support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"503":{"description":"A dependency is temporarily unavailable (`error.code = EXTERNAL_SERVICE_ERROR`). Retry with exponential back-off.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}}},"summary":"Get podcasts a creator is credited on","tags":["Creators"],"x-required-tier":"Starter+"}},"/api/rest/v1/creators/{pcid}/episodes":{"get":{"description":"<div class=\"tier-pill-row\"><span class=\"tier-pill tier-pill--starter-plus\">Starter+</span></div><p class=\"tier-pill-prose\">Callers below **Starter+** receive `HTTP 403` with error code `TIER_RESTRICTED`.</p>\n\nPaginated list of episode credits for the creator across all podcasts the creator has been credited on. Pagination is silently capped at the caller's tier `per_page` max.","operationId":"getCreatorEpisodes","parameters":[{"name":"pcid","required":true,"in":"path","description":"Podchaser creator id.","schema":{"example":"8","type":"string"}},{"name":"page","required":false,"in":"query","description":"Page number (1-indexed)","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"per_page","required":false,"in":"query","description":"Results per page. Optional — when omitted, defaults to the caller tier default (FREE=10, STARTER=25, PROFESSIONAL=25). Requesting a higher value is silently capped to the tier maximum (FREE=10, STARTER=25, PROFESSIONAL=100; no 400).","schema":{"type":"number"}},{"name":"q","required":false,"in":"query","description":"Search term","schema":{"type":"string"}},{"name":"role","required":false,"in":"query","description":"Comma-separated role codes","schema":{"type":"string"}},{"name":"sort","required":false,"in":"query","description":"Sort field","schema":{"default":"air_date","type":"string","enum":["air_date","relevance"]}},{"name":"sort_direction","required":false,"in":"query","description":"Sort direction","schema":{"default":"desc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"Paginated list of creator episode credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedCreatorEpisodeCreditResponseDto"}}}},"400":{"description":"Validation error — malformed query parameters or path variables.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"401":{"description":"Missing or invalid API key (header `x-api-key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"403":{"description":"Requires **Starter+** tier. Callers on a lower tier receive HTTP 403 with error code `TIER_RESTRICTED`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"404":{"description":"Creator not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"429":{"description":"Rate limit exceeded. The `Retry-After` header carries the seconds to wait; `error.details.bucket` identifies which limit fired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"500":{"description":"Unexpected server error. Report `error.requestId` to support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"503":{"description":"A dependency is temporarily unavailable (`error.code = EXTERNAL_SERVICE_ERROR`). Retry with exponential back-off.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}}},"summary":"Get episode credits for a creator","tags":["Creators"],"x-required-tier":"Starter+"}},"/api/rest/v1/sponsors/{id}":{"get":{"description":"<div class=\"tier-pill-row\"><span class=\"tier-pill tier-pill--professional\">Professional</span></div><p class=\"tier-pill-prose\">Callers below **Professional** receive `HTTP 403` with error code `TIER_RESTRICTED`.</p>\n\nReturns metadata for a brand that has appeared as a sponsor: estimated ad spend, total sponsored podcasts, and total sponsored episodes. Optional `ads_from`/`ads_to` (ISO 8601) window the `estimated_ad_spend` figures only — `podcasts_sponsored` and `episodes_sponsored` are always all-time because upstream does not yet accept a window on those counts. Omit both ad window params for an all-time estimate.","operationId":"getSponsorById","parameters":[{"name":"id","required":true,"in":"path","description":"Sponsor (brand) numeric identifier — Podchaser's internal `Brand.id`. Returned as `id` on this endpoint and as `brand_id` on related sub-resources. The human-readable `code` (e.g. `global.brand.shopify`) is still surfaced on the response payload for cross-reference.","schema":{"example":"13","type":"string"}},{"name":"ads_from","required":false,"in":"query","description":"Start date (ISO 8601) for the ad-estimates window. Affects `estimated_ad_spend` only — `podcasts_sponsored` is always all-time because upstream does not yet accept a window on it. Tip: a common choice is *today minus 90 days* paired with `ads_to` set to *today* for a rolling-quarter estimate.","schema":{"example":"2026-02-13T00:00:00Z","type":"string"}},{"name":"ads_to","required":false,"in":"query","description":"End date (ISO 8601) for the ad-estimates window. Must be greater than or equal to `ads_from` when both are supplied. Tip: set this to *today* and `ads_from` to *today minus 90 days* for a rolling-quarter estimate.","schema":{"example":"2026-05-14T23:59:59Z","type":"string"}}],"responses":{"200":{"description":"Sponsor metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SponsorResponseDto"},"examples":{"professional":{"summary":"Professional tier — full response","value":{"data":{"id":"13","code":"global.brand.shopify","name":"Shopify","estimatedAdSpend":{"low":50507000,"high":73998100},"podcastsSponsored":4148,"episodesSponsored":73333},"restricted_fields":[],"meta":{"request_id":"01J9KX5Q8H3M0Z6Y7Q1F2A4N6P","tier":"professional","requests_remaining":4998}}}}}}},"400":{"description":"Validation error — malformed query parameters or path variables.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"401":{"description":"Missing or invalid API key (header `x-api-key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"403":{"description":"Caller tier does not have access to this endpoint or field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"404":{"description":"Sponsor not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"429":{"description":"Rate limit exceeded. The `Retry-After` header carries the seconds to wait; `error.details.bucket` identifies which limit fired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"500":{"description":"Unexpected server error. Report `error.requestId` to support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"503":{"description":"A dependency is temporarily unavailable (`error.code = EXTERNAL_SERVICE_ERROR`). Retry with exponential back-off.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}}},"summary":"Get sponsor metadata","tags":["Sponsors"],"x-required-tier":"Professional"}},"/api/rest/v1/sponsors/{id}/podcasts":{"get":{"description":"<div class=\"tier-pill-row\"><span class=\"tier-pill tier-pill--professional\">Professional</span></div><p class=\"tier-pill-prose\">Callers below **Professional** receive `HTTP 403` with error code `TIER_RESTRICTED`.</p>\n\nPaginated summary of podcasts this brand has sponsored, with the per-podcast sponsored episode count and the air date of the brand's most recent placement on each show. Use `q` to filter by podcast title. `sort` accepts `alphabetical` (title order), `power_score` (Podchaser Power Score, default — desc), `episode_count` (number of episodes this brand sponsored on each podcast — desc by default), and `latest_episode` (air date of the brand's most recent placement on each podcast — desc by default; sponsorship-scoped, distinct from show-level latest-episode). `sort_direction` defaults vary by field (see `SponsorPodcastSortPolicy`). Professional-only.","operationId":"getSponsorPodcasts","parameters":[{"name":"id","required":true,"in":"path","description":"Sponsor (brand) numeric identifier — Podchaser's internal `Brand.id`. Same identifier accepted by `GET /sponsors/{id}`. The human-readable `code` (e.g. `global.brand.shopify`) is no longer accepted on the path; it is still surfaced on the parent endpoint response payload for cross-reference.","schema":{"example":"13","type":"string"}},{"name":"page","required":false,"in":"query","description":"Page number (1-indexed)","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"per_page","required":false,"in":"query","description":"Results per page. Optional — when omitted, defaults to the caller tier default (FREE=10, STARTER=25, PROFESSIONAL=25). Requesting a higher value is silently capped to the tier maximum (FREE=10, STARTER=25, PROFESSIONAL=100; no 400).","schema":{"type":"number"}},{"name":"q","required":false,"in":"query","description":"Search term to filter podcast titles","schema":{"type":"string"}},{"name":"sort","required":false,"in":"query","description":"Sort field. `alphabetical` orders by podcast title; `power_score` orders by Podchaser Power Score (Pro+ underlying upstream key); `episode_count` orders by the number of episodes this brand sponsored on each podcast; `latest_episode` orders by the air date of the brand's most recent sponsored episode on each podcast (both sponsorship-scoped — only meaningful on this endpoint).","schema":{"default":"power_score","type":"string","enum":["alphabetical","power_score","episode_count","latest_episode"]}},{"name":"sort_direction","required":false,"in":"query","description":"Sort direction. Defaults vary by sort field — `power_score`, `episode_count`, and `latest_episode` default to desc; `alphabetical` defaults to asc. See `SponsorPodcastSortPolicy`.","schema":{"type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"Paginated podcasts sponsored by this brand","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedSponsorPodcastResponseDto"},"examples":{"professional":{"summary":"Professional tier — full response","value":{"data":[{"podcast":{"id":"32228","title":"Global News Podcast","imageUrl":"http://ichef.bbci.co.uk/images/ic/3000x3000/p0lqf7hf.jpg","description":"The Global News Podcast brings you the breaking news you need to hear, as it happens. Listen for the latest headlines and current affairs from around the world.","numberOfEpisodes":6068,"powerScore":99,"audienceEstimate":42746611,"totalAudienceEstimate":42757916,"hostingProvider":null},"episodeCount":40,"latestSponsoredEpisodeDate":"2025-04-12 18:00:00"},{"podcast":{"id":"595400","title":"Crime Junkie","imageUrl":"https://image.simplecastcdn.com/images/a1a87b67-2865-4234-a087-b342aa30c358/ae42d51b-df99-4b19-bb3f-09f25598bcdd/3000x3000/crimejunkie-logo-registered.jpg?aid=rss_feed","description":"Does hearing about a true crime case always leave you scouring the internet for the truth behind the story? Dive into your next mystery with Crime Junkie.","numberOfEpisodes":571,"powerScore":99,"audienceEstimate":26150094,"totalAudienceEstimate":26244199,"hostingProvider":"audioBoom"},"episodeCount":19,"latestSponsoredEpisodeDate":"2025-03-31 09:00:00"},{"podcast":{"id":"10829","title":"The Joe Rogan Experience","imageUrl":"https://example.podchaser.com/podcast/10829/cover.jpg","description":"The official podcast of comedian Joe Rogan.","numberOfEpisodes":2648,"powerScore":99,"audienceEstimate":61472801,"totalAudienceEstimate":89526554},"episodeCount":12,"latestSponsoredEpisodeDate":"2025-02-08 16:30:00"}],"pagination":{"page":1,"per_page":25,"total_results":4148,"total_pages":166,"has_more":true},"restricted_fields":[],"meta":{"request_id":"01J9KX5Q8H3M0Z6Y7Q1F2A4N6P","tier":"professional","requests_remaining":4998}}}}}}},"400":{"description":"Validation error — malformed query parameters or path variables.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"401":{"description":"Missing or invalid API key (header `x-api-key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"403":{"description":"Caller tier does not have access to this endpoint or field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"404":{"description":"Sponsor not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"429":{"description":"Rate limit exceeded. The `Retry-After` header carries the seconds to wait; `error.details.bucket` identifies which limit fired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"500":{"description":"Unexpected server error. Report `error.requestId` to support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"503":{"description":"A dependency is temporarily unavailable (`error.code = EXTERNAL_SERVICE_ERROR`). Retry with exponential back-off.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}}},"summary":"Get podcasts sponsored by a brand","tags":["Sponsors"],"x-required-tier":"Professional"}},"/api/rest/v1/sponsors/{id}/episodes":{"get":{"description":"<div class=\"tier-pill-row\"><span class=\"tier-pill tier-pill--professional\">Professional</span></div><p class=\"tier-pill-prose\">Callers below **Professional** receive `HTTP 403` with error code `TIER_RESTRICTED`.</p>\n\nPaginated list of episode-level sponsorship placements for this brand, with ad markers and per-placement spend estimates. Use `podcast_id` to scope results to a single show; when omitted, returns every sponsored episode across the catalog. Sort surface is `air_date` only today, defaulting to `desc` (most-recent first) per `SponsorEpisodeSortPolicy`. Unknown sponsor `id` returns 404; unknown `podcast_id` returns an empty page (the addressed resource is the sponsor — `podcast_id` is a filter, not a path segment).","operationId":"getSponsorEpisodes","parameters":[{"name":"id","required":true,"in":"path","description":"Sponsor (brand) numeric identifier — Podchaser's internal `Brand.id`. Same identifier accepted by `GET /sponsors/{id}` and `GET /sponsors/{id}/podcasts`.","schema":{"example":"13","type":"string"}},{"name":"page","required":false,"in":"query","description":"Page number (1-indexed)","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"per_page","required":false,"in":"query","description":"Results per page. Optional — when omitted, defaults to the caller tier default (FREE=10, STARTER=25, PROFESSIONAL=25). Requesting a higher value is silently capped to the tier maximum (FREE=10, STARTER=25, PROFESSIONAL=100; no 400).","schema":{"type":"number"}},{"name":"podcast_id","required":false,"in":"query","description":"Filter to episodes on a specific podcast (Podchaser podcast id). When omitted, returns every sponsored placement for the brand across the catalog. Unknown ids resolve to an empty page (not a 404) — the addressed resource is the sponsor, the podcast id is a filter.","schema":{"example":"1576373","type":"string"}},{"name":"sort","required":false,"in":"query","description":"Sort field. v1 supports `air_date` only — placements are returned in episode publication order. Additional fields will be added as upstream lands sponsorship-scoped sort enums.","schema":{"default":"air_date","type":"string","enum":["air_date"]}},{"name":"sort_direction","required":false,"in":"query","description":"Sort direction. Defaults to `desc` for `air_date` (most-recent-first), per `SponsorEpisodeSortPolicy`.","schema":{"type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"Paginated episodes sponsored by this brand","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedSponsorEpisodeResponseDto"},"examples":{"professional":{"summary":"Professional tier — full response","value":{"data":[{"episode":{"id":"ep-1576373-0123","title":"How to Build Resilience","airDate":"2025-03-15 09:00:00"},"podcast":{"id":"1576373","title":"Huberman Lab"},"startTime":12.5,"endTime":47.25,"estimatedAdSpend":{"low":1500,"high":2300}},{"episode":{"id":"ep-32228-0456","title":"Markets Open Wednesday","airDate":"2025-03-12 06:00:00"},"podcast":{"id":"32228","title":"Global News Podcast"},"startTime":8,"endTime":38.5,"estimatedAdSpend":{"low":4200,"high":5800}}],"pagination":{"page":1,"per_page":25,"total_results":73333,"total_pages":2934,"has_more":true},"restricted_fields":[],"meta":{"request_id":"01J9KX5Q8H3M0Z6Y7Q1F2A4N6P","tier":"professional","requests_remaining":4998}}}}}}},"400":{"description":"Validation error — malformed query parameters or path variables.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"401":{"description":"Missing or invalid API key (header `x-api-key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"403":{"description":"Caller tier does not have access to this endpoint or field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"404":{"description":"Sponsor not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"429":{"description":"Rate limit exceeded. The `Retry-After` header carries the seconds to wait; `error.details.bucket` identifies which limit fired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"500":{"description":"Unexpected server error. Report `error.requestId` to support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"503":{"description":"A dependency is temporarily unavailable (`error.code = EXTERNAL_SERVICE_ERROR`). Retry with exponential back-off.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}}},"summary":"Get episodes sponsored by a brand","tags":["Sponsors"],"x-required-tier":"Professional"}},"/api/rest/v1/reference":{"get":{"description":"<div class=\"tier-pill-row\"><span class=\"tier-pill tier-pill--starter-plus\">Starter+</span></div>\n\nLook up static Podchaser reference data. Use this BEFORE constructing filters for search/discovery tools when you need the canonical set of valid values. Picks a `resource` from: categories | languages | demographics | charts | brandsafety. `categories` accepts optional `q` (search), `sort` (alphabetical|podcast_count|relevance), `page`, and `per_page` (capped per tier). `charts` accepts optional `platform` (omit to fan out across all platforms). `languages`, `demographics` (eight dimensions: age_ranges, income_tiers, gender_biases, parental_statuses, political_skews, ethnicities, education_levels, marital_statuses), and `brandsafety` take no additional params. Does not count against the monthly request quota.","operationId":"getReference","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (1-indexed)","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"per_page","required":false,"in":"query","description":"Results per page. Optional — when omitted, defaults to the caller tier default (FREE=10, STARTER=25, PROFESSIONAL=25). Requesting a higher value is silently capped to the tier maximum (FREE=10, STARTER=25, PROFESSIONAL=100; no 400).","schema":{"type":"number"}},{"name":"resource","required":true,"in":"query","description":"Reference catalogue to return (`categories`, `languages`, `demographics`, `charts`, or `brandsafety`).","schema":{"example":"categories","type":"string","enum":["categories","languages","demographics","charts","brandsafety"]}},{"name":"q","required":false,"in":"query","description":"Search / filter term for category titles. Applies only when `resource=categories`.","schema":{"example":"tech","type":"string"}},{"name":"sort","required":false,"in":"query","description":"Sort order for categories (`alphabetical`, `podcast_count`, `relevance`). Applies only when `resource=categories`.","schema":{"default":"alphabetical","type":"string","enum":["alphabetical","podcast_count","relevance"]}},{"name":"platform","required":false,"in":"query","description":"Chart platform filter (`apple_podcasts` or `spotify`). Applies only when `resource=charts`; omit to fan out across all supported platforms.","schema":{"example":"apple_podcasts","type":"string","enum":["apple_podcasts","spotify"]}}],"responses":{"200":{"description":"Reference catalogue for the requested resource."},"400":{"description":"Validation error — malformed query parameters or path variables.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"401":{"description":"Missing or invalid API key (header `x-api-key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"403":{"description":"Caller tier does not have access to this endpoint or field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"404":{"description":"The requested resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"429":{"description":"Rate limit exceeded. The `Retry-After` header carries the seconds to wait; `error.details.bucket` identifies which limit fired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"500":{"description":"Unexpected server error. Report `error.requestId` to support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"503":{"description":"A dependency is temporarily unavailable (`error.code = EXTERNAL_SERVICE_ERROR`). Retry with exponential back-off.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}}},"summary":"Get Podchaser reference data by resource","tags":["Reference"],"x-required-tier":"Starter+","x-tier-docs-only":true}},"/api/rest/v1/reference/categories":{"get":{"description":"<div class=\"tier-pill-row\"><span class=\"tier-pill tier-pill--starter-plus\">Starter+</span></div>\n\nReturns a paginated list of Podchaser categories. Does not count against the monthly request quota. Supports a search/filter term `q` and a `sort` order (`alphabetical` (default), `podcast_count`, `relevance`). `per_page` is silently capped at the caller tier max (FREE=10, STARTER=25, PROFESSIONAL=100).","operationId":"getReferenceCategories","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (1-indexed)","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"per_page","required":false,"in":"query","description":"Results per page. Optional — when omitted, defaults to the caller tier default (FREE=10, STARTER=25, PROFESSIONAL=25). Requesting a higher value is silently capped to the tier maximum (FREE=10, STARTER=25, PROFESSIONAL=100; no 400).","schema":{"type":"number"}},{"name":"q","required":false,"in":"query","description":"Search / filter term applied to the category title.","schema":{"example":"tech","type":"string"}},{"name":"sort","required":false,"in":"query","description":"Sort order for the returned list.","schema":{"default":"alphabetical","type":"string","enum":["alphabetical","podcast_count","relevance"]}}],"responses":{"200":{"description":"Paginated list of categories.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedCategoryResponseDto"}}}},"400":{"description":"Validation error — malformed query parameters or path variables.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"401":{"description":"Missing or invalid API key (header `x-api-key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"403":{"description":"Caller tier does not have access to this endpoint or field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"404":{"description":"The requested resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"429":{"description":"Rate limit exceeded. The `Retry-After` header carries the seconds to wait; `error.details.bucket` identifies which limit fired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"500":{"description":"Unexpected server error. Report `error.requestId` to support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"503":{"description":"A dependency is temporarily unavailable (`error.code = EXTERNAL_SERVICE_ERROR`). Retry with exponential back-off.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}}},"summary":"Get the list of podcast categories","tags":["Reference"],"x-required-tier":"Starter+","x-tier-docs-only":true}},"/api/rest/v1/reference/languages":{"get":{"description":"<div class=\"tier-pill-row\"><span class=\"tier-pill tier-pill--starter-plus\">Starter+</span></div>\n\nReturns the catalogue of language codes that appear on `Podcast.language`, each with an ISO 639-1-style `code` and a display `name`. Does not count against the monthly request quota. Free+.","operationId":"getReferenceLanguages","parameters":[],"responses":{"200":{"description":"Array of supported languages.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ReferenceLanguageDto"}}}}},"400":{"description":"Validation error — malformed query parameters or path variables.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"401":{"description":"Missing or invalid API key (header `x-api-key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"403":{"description":"Caller tier does not have access to this endpoint or field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"404":{"description":"The requested resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"429":{"description":"Rate limit exceeded. The `Retry-After` header carries the seconds to wait; `error.details.bucket` identifies which limit fired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"500":{"description":"Unexpected server error. Report `error.requestId` to support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"503":{"description":"A dependency is temporarily unavailable (`error.code = EXTERNAL_SERVICE_ERROR`). Retry with exponential back-off.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}}},"summary":"Get the list of languages","tags":["Reference"],"x-required-tier":"Starter+","x-tier-docs-only":true}},"/api/rest/v1/reference/demographics":{"get":{"description":"<div class=\"tier-pill-row\"><span class=\"tier-pill tier-pill--starter-plus\">Starter+</span></div>\n\nReturns the canonical machine keys and display labels for the eight demographic filter dimensions (`age_ranges`, `income_tiers`, `gender_biases`, `parental_statuses`, `political_skews`, `ethnicities`, `education_levels`, `marital_statuses`). Does not count against the monthly request quota. Every field is a list of `{key, label}` pairs — the `key` is the value accepted by the corresponding `/podcasts` search filter.","operationId":"getReferenceDemographics","parameters":[],"responses":{"200":{"description":"Demographic reference catalogue.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DemographicsResponseDto"}}}},"400":{"description":"Validation error — malformed query parameters or path variables.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"401":{"description":"Missing or invalid API key (header `x-api-key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"403":{"description":"Caller tier does not have access to this endpoint or field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"404":{"description":"The requested resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"429":{"description":"Rate limit exceeded. The `Retry-After` header carries the seconds to wait; `error.details.bucket` identifies which limit fired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"500":{"description":"Unexpected server error. Report `error.requestId` to support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"503":{"description":"A dependency is temporarily unavailable (`error.code = EXTERNAL_SERVICE_ERROR`). Retry with exponential back-off.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}}},"summary":"Get the valid demographic filter values","tags":["Reference"],"x-required-tier":"Starter+","x-tier-docs-only":true}},"/api/rest/v1/reference/charts":{"get":{"description":"<div class=\"tier-pill-row\"><span class=\"tier-pill tier-pill--starter-plus\">Starter+</span></div>\n\nReturns the supported chart platforms and chart category rows (`title`, `slug`, `platform`). The `platform` query param is optional: when provided the response carries categories for that platform only and `platforms` echoes back just that one platform; when omitted the response carries categories for every supported platform in a single list (each row tagged with its own `platform`) and `platforms` lists every supported platform. Does not count against the monthly request quota.","operationId":"getReferenceCharts","parameters":[{"name":"platform","required":false,"in":"query","description":"Chart platform whose categories to return (`apple_podcasts` or `spotify`). Optional — when omitted the endpoint returns categories for every supported platform; each row carries a `platform` field so callers can disambiguate.","schema":{"example":"apple_podcasts","type":"string","enum":["apple_podcasts","spotify"]}}],"responses":{"200":{"description":"Chart platforms and categories.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReferenceChartsResponseDto"}}}},"400":{"description":"Validation error — malformed query parameters or path variables.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"401":{"description":"Missing or invalid API key (header `x-api-key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"403":{"description":"Caller tier does not have access to this endpoint or field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"404":{"description":"The requested resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"429":{"description":"Rate limit exceeded. The `Retry-After` header carries the seconds to wait; `error.details.bucket` identifies which limit fired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"500":{"description":"Unexpected server error. Report `error.requestId` to support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"503":{"description":"A dependency is temporarily unavailable (`error.code = EXTERNAL_SERVICE_ERROR`). Retry with exponential back-off.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}}},"summary":"Get chart platforms and category slugs","tags":["Reference"],"x-required-tier":"Starter+","x-tier-docs-only":true}},"/api/rest/v1/reference/brandsafety":{"get":{"description":"<div class=\"tier-pill-row\"><span class=\"tier-pill tier-pill--starter-plus\">Starter+</span></div>\n\nReturns the complete catalogue of brand-safety risk codes used in `GET /podcasts/{id}/brandsafety`, `GET /episodes/{id}/brandsafety`, and the `brand_safety_exclude` / `brand_safety_max_level` search filters. Does not count against the monthly request quota. Free+.","operationId":"getReferenceBrandSafety","parameters":[],"responses":{"200":{"description":"Array of brand-safety risk codes with descriptions and possible levels.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ReferenceBrandSafetyCodeDto"}}}}},"400":{"description":"Validation error — malformed query parameters or path variables.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"401":{"description":"Missing or invalid API key (header `x-api-key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"403":{"description":"Caller tier does not have access to this endpoint or field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"404":{"description":"The requested resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"429":{"description":"Rate limit exceeded. The `Retry-After` header carries the seconds to wait; `error.details.bucket` identifies which limit fired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"500":{"description":"Unexpected server error. Report `error.requestId` to support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"503":{"description":"A dependency is temporarily unavailable (`error.code = EXTERNAL_SERVICE_ERROR`). Retry with exponential back-off.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}}},"summary":"Get brand safety risk codes","tags":["Reference"],"x-required-tier":"Starter+","x-tier-docs-only":true}},"/api/rest/v1/reference/hosting-providers":{"get":{"description":"Returns the catalogue of podcast hosting providers known to Podchaser, each with a `name` and `podcastCount`. Anchor variants are consolidated into a single entry. Supports `sort_by` (`alphabetical`, `podcast_count`) and `sort_direction` (`asc`, `desc`). Does not count against the monthly request quota. Free+.","operationId":"getReferenceHostingProviders","parameters":[{"name":"sort_by","required":false,"in":"query","description":"Sort field: `alphabetical` (by name) or `podcast_count` (by number of podcasts).","schema":{"default":"podcast_count","type":"string","enum":["alphabetical","podcast_count"]}},{"name":"sort_direction","required":false,"in":"query","description":"Sort direction: `asc` or `desc`. When omitted, upstream picks the natural default for the chosen `sort_by` (alphabetical → asc, podcast_count → desc).","schema":{"type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"Array of hosting providers with podcast counts.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/HostingProviderResponseDto"}}}}},"400":{"description":"Validation error — malformed query parameters or path variables.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"401":{"description":"Missing or invalid API key (header `x-api-key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"403":{"description":"Caller tier does not have access to this endpoint or field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"404":{"description":"The requested resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"429":{"description":"Rate limit exceeded. The `Retry-After` header carries the seconds to wait; `error.details.bucket` identifies which limit fired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"500":{"description":"Unexpected server error. Report `error.requestId` to support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"503":{"description":"A dependency is temporarily unavailable (`error.code = EXTERNAL_SERVICE_ERROR`). Retry with exponential back-off.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}}},"summary":"Get the list of hosting providers","tags":["Reference"],"x-required-tier":"Free+","x-tier-docs-only":true}},"/api/rest/v1/networks/{id}":{"get":{"description":"<div class=\"tier-pill-row\"><span class=\"tier-pill tier-pill--starter-plus\">Starter+</span></div><p class=\"tier-pill-prose\">Callers below **Starter+** receive `HTTP 403` with error code `TIER_RESTRICTED`.</p>\n\nReturns the network envelope (`{ data, restricted_fields, meta }`). Tier-restricted fields are omitted from `data` and listed in `restricted_fields`.","operationId":"getNetworkById","parameters":[{"name":"id","required":true,"in":"path","description":"Podchaser network id (e.g. `1`).","schema":{"example":"1","type":"string"}},{"name":"id_type","required":false,"in":"query","description":"Identifier type used in the path: podchaser (default) or title","schema":{"default":"podchaser","type":"string","enum":["podchaser","title"]}}],"responses":{"200":{"description":"The network was found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NetworkResponseDto"}}}},"400":{"description":"Validation error — malformed query parameters or path variables.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"401":{"description":"Missing or invalid API key (header `x-api-key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"403":{"description":"Requires **Starter+** tier. Callers on a lower tier receive HTTP 403 with error code `TIER_RESTRICTED`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"404":{"description":"Network not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"429":{"description":"Rate limit exceeded. The `Retry-After` header carries the seconds to wait; `error.details.bucket` identifies which limit fired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"500":{"description":"Unexpected server error. Report `error.requestId` to support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"503":{"description":"A dependency is temporarily unavailable (`error.code = EXTERNAL_SERVICE_ERROR`). Retry with exponential back-off.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}}},"summary":"Get a network by ID","tags":["Networks"],"x-required-tier":"Starter+"}},"/api/rest/v1/networks/{id}/insights":{"get":{"description":"<div class=\"tier-pill-row\"><span class=\"tier-pill tier-pill--starter-plus\">Starter+</span></div><p class=\"tier-pill-prose\">Callers below **Starter+** receive `HTTP 403` with error code `TIER_RESTRICTED`.</p>\n\nAggregated podcast insights (categories, status, power-score, audience estimate, etc.) computed across every podcast in the network.","operationId":"getNetworkInsights","parameters":[{"name":"id","required":true,"in":"path","description":"Podchaser network id.","schema":{"example":"1","type":"string"}}],"responses":{"200":{"description":"Aggregated network insights","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NetworkInsightsResponseDto"}}}},"400":{"description":"Validation error — malformed query parameters or path variables.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"401":{"description":"Missing or invalid API key (header `x-api-key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"403":{"description":"Requires **Starter+** tier. Callers on a lower tier receive HTTP 403 with error code `TIER_RESTRICTED`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"404":{"description":"Network not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"429":{"description":"Rate limit exceeded. The `Retry-After` header carries the seconds to wait; `error.details.bucket` identifies which limit fired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"500":{"description":"Unexpected server error. Report `error.requestId` to support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"503":{"description":"A dependency is temporarily unavailable (`error.code = EXTERNAL_SERVICE_ERROR`). Retry with exponential back-off.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}}},"summary":"Get aggregate insights for a network","tags":["Networks"],"x-required-tier":"Starter+"}},"/api/rest/v1/networks/{id}/podcasts":{"get":{"description":"<div class=\"tier-pill-row\"><span class=\"tier-pill tier-pill--starter-plus\">Starter+</span></div><p class=\"tier-pill-prose\">Callers below **Starter+** receive `HTTP 403` with error code `TIER_RESTRICTED`.</p>\n\nPaginated list of podcasts that belong to the network. Reuses `PodcastResponseDto` so the shape matches `GET /podcasts/{id}`.","operationId":"getNetworkPodcasts","parameters":[{"name":"id","required":true,"in":"path","description":"Podchaser network id.","schema":{"example":"1","type":"string"}},{"name":"page","required":false,"in":"query","description":"Page number (1-indexed)","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"per_page","required":false,"in":"query","description":"Results per page. Optional — when omitted, defaults to the caller tier default (FREE=10, STARTER=25, PROFESSIONAL=25). Requesting a higher value is silently capped to the tier maximum (FREE=10, STARTER=25, PROFESSIONAL=100; no 400).","schema":{"type":"number"}},{"name":"q","required":false,"in":"query","description":"Free-text search query. When `bool_search=true`, parsed as a boolean expression supporting AND, OR, NOT, and parentheses (validated by `validateBooleanExpression`).","schema":{"type":"string"}},{"name":"bool_search","required":false,"in":"query","description":"When true, `q` is parsed as a boolean expression. When false / omitted, `q` is treated as free text. Accepts the strings `true`/`false`/`1`/`0`.","schema":{"default":false,"type":"boolean"}},{"name":"sort","required":false,"in":"query","description":"Sort field","schema":{"default":"relevance","type":"string","enum":["relevance","power_score","date_of_first_episode","alphabetical"]}},{"name":"sort_direction","required":false,"in":"query","description":"Sort direction (`asc` or `desc`). Default varies per endpoint — each `/search/*` resource declares its own `<Resource>SortPolicy` whose `directionByField` table is the source of truth. When the caller omits this field, the use case resolves the default from that policy; the base class deliberately ships NO default so a subclass field initializer can never accidentally mask the per-endpoint policy (under `useDefineForClassFields: true` a parent initializer runs unless the subclass explicitly resets the property — rather than hand-waving that override on every subclass, the base simply leaves the field undefined).","schema":{"type":"string","enum":["asc","desc"]}},{"name":"categories","required":false,"in":"query","description":"Comma-separated category slugs","schema":{"type":"string"}},{"name":"language","required":false,"in":"query","description":"Language code (e.g., en, es). See GET /reference/languages for the full catalogue.","schema":{"example":"en","type":"string","enum":["en","ab","aa","af","ag","ai","ak","al","sq","am","ar","an","hy","as","au","av","ay","az","bm","bn","ba","eu","be","bf","bh","bi","bs","br","bu","bg","my","ca","cc","cd","cg","ch","ce","zh","cu","cv","ck","cl","cm","cn","kw","co","cr","hr","cz","cs","da","di","dv","dj","dk","do","ds","du","nl","dy","dz","eb","eo","et","ew","ee","fo","fj","fi","fr","fu","ff","gl","lg","ge","ka","de","gh","gr","el","gs","gt","gn","gu","ht","ha","he","iw","hz","hi","ho","hm","hs","hu","is","io","ig","il","im","id","in","ia","ie","iu","ik","ga","it","iv","ja","jv","jw","jg","jm","jo","jp","ju","kl","kn","kr","ks","kk","ke","kh","km","ki","rw","kg","ko","ku","ky","lo","la","lv","le","li","ln","lt","lk","lr","lu","lb","ma","mk","mg","ms","ml","mt","gv","mi","mr","md","me","mf","mn","mu","mx","mz","na","nv","ne","ni","nm","nd","se","no","nb","nn","nu","ny","oc","or","om","os","ps","pc","fa","pg","po","pl","pt","pr","pa","qu","rh","mo","ro","rm","rs","rn","ru","sm","sg","sa","sc","sb","gd","sr","sh","sn","ii","sd","si","sk","sl","so","nr","st","sp","es","su","sw","ss","sv","tl","ty","tg","ta","tt","tc","te","th","bo","ti","to","ts","tn","tr","tk","tw","tz","ua","uk","un","ur","us","ug","uz","va","ve","vi","vn","vu","wa","cy","fy","wo","xh","xo","ya","ye","ji","yi","yo","yu","zg","za","zu","zx","zz"]}},{"name":"status","required":false,"in":"query","description":"Comma-separated: active, idle, complete","schema":{"type":"string"}},{"name":"has_guests","required":false,"in":"query","description":"Filter by guest presence","schema":{"type":"boolean"}},{"name":"hosting_providers","required":false,"in":"query","description":"Comma-separated hosting provider names (e.g. Acast,Libsyn). Values are case-sensitive and combined with OR. Use GET /reference/hosting-providers for the catalogue.","schema":{"type":"string"}},{"name":"start_date_from","required":false,"in":"query","description":"Podcast start date from (ISO 8601)","schema":{"type":"string"}},{"name":"start_date_to","required":false,"in":"query","description":"Podcast start date to (ISO 8601)","schema":{"type":"string"}},{"name":"latest_episode_from","required":false,"in":"query","description":"Date of last episode from (ISO 8601)","schema":{"type":"string"}},{"name":"latest_episode_to","required":false,"in":"query","description":"Date of last episode to (ISO 8601)","schema":{"type":"string"}},{"name":"added_date_from","required":false,"in":"query","description":"Date added to Podchaser from (ISO 8601)","schema":{"type":"string"}},{"name":"added_date_to","required":false,"in":"query","description":"Date added to Podchaser to (ISO 8601)","schema":{"type":"string"}},{"name":"modified_date_from","required":false,"in":"query","description":"Date last modified from (ISO 8601)","schema":{"type":"string"}},{"name":"modified_date_to","required":false,"in":"query","description":"Date last modified to (ISO 8601)","schema":{"type":"string"}},{"name":"include_removed","required":false,"in":"query","description":"Include removed podcasts in results","schema":{"default":false,"type":"boolean"}},{"name":"power_score_min","required":false,"in":"query","description":"Power Score min (0-100). Starter+","schema":{"type":"number"}},{"name":"power_score_max","required":false,"in":"query","description":"Power Score max (0-100). Starter+","schema":{"type":"number"}},{"name":"network_id","required":false,"in":"query","description":"Network Podchaser ID. Starter+","schema":{"minimum":1,"type":"number"}},{"name":"network_title","required":false,"in":"query","description":"Network title. Starter+","schema":{"type":"string"}},{"name":"political_skew","required":false,"in":"query","description":"Comma-separated political skew: high_left, medium_left, low_left, neutral, low_right, medium_right, high_right. Starter+","schema":{"type":"string"}},{"name":"gender_bias","required":false,"in":"query","description":"Comma-separated gender bias: high_male, moderate_male, mixed, moderate_female, high_female. Starter+","schema":{"type":"string"}},{"name":"age_range","required":false,"in":"query","description":"Comma-separated age range keys. Starter+","schema":{"type":"string"}},{"name":"income_tier","required":false,"in":"query","description":"Comma-separated income tier: income_tier_0 through income_tier_4. Starter+","schema":{"type":"array","items":{"type":"string","enum":["income_tier_0","income_tier_1","income_tier_2","income_tier_3","income_tier_4"]}}},{"name":"parental_status","required":false,"in":"query","description":"Comma-separated parental status: parent, non_parent, mixed, high_parent, high_non_parent. Starter+","schema":{"type":"array","items":{"type":"string","enum":["mixed","non_parent","parent","high_parent","high_non_parent"]}}},{"name":"education_level","required":false,"in":"query","description":"Comma-separated education level: higher_education, mixed, no_higher_education. Starter+","schema":{"type":"array","items":{"type":"string","enum":["higher_education","mixed","no_higher_education"]}}},{"name":"marital_status","required":false,"in":"query","description":"Comma-separated marital status: married, mixed, not_married. Starter+","schema":{"type":"array","items":{"type":"string","enum":["married","mixed","not_married"]}}},{"name":"country","required":false,"in":"query","description":"Demographic country filter. Starter+","schema":{"type":"string"}},{"name":"monthly_reach_min","required":false,"in":"query","description":"Monthly audience estimate min. Pro+","schema":{"type":"number"}},{"name":"monthly_reach_max","required":false,"in":"query","description":"Monthly audience estimate max. Pro+","schema":{"type":"number"}},{"name":"episode_reach_min","required":false,"in":"query","description":"Per-episode audience estimate min. Pro+","schema":{"type":"number"}},{"name":"episode_reach_max","required":false,"in":"query","description":"Per-episode audience estimate max. Pro+","schema":{"type":"number"}},{"name":"brand_safety_exclude","required":false,"in":"query","description":"Comma-separated brand safety risk codes to exclude. Pro+. Required when `brand_safety_max_level` is set — exclusions are applied per risk code, so a max level on its own has no code to scope to.","schema":{"type":"string"}},{"name":"brand_safety_max_level","required":false,"in":"query","description":"Max risk level: clean, low, medium, high. Pro+. Must be combined with `brand_safety_exclude` — see that field.","schema":{"type":"string","enum":["clean","low","medium","high"]}}],"responses":{"200":{"description":"Paginated list of network podcasts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedPodcastResponseDto"}}}},"400":{"description":"Validation error — malformed query parameters or path variables.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"401":{"description":"Missing or invalid API key (header `x-api-key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"403":{"description":"Requires **Starter+** tier. Callers on a lower tier receive HTTP 403 with error code `TIER_RESTRICTED`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"404":{"description":"Network not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"429":{"description":"Rate limit exceeded. The `Retry-After` header carries the seconds to wait; `error.details.bucket` identifies which limit fired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"500":{"description":"Unexpected server error. Report `error.requestId` to support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"503":{"description":"A dependency is temporarily unavailable (`error.code = EXTERNAL_SERVICE_ERROR`). Retry with exponential back-off.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}}},"summary":"Get podcasts in a network","tags":["Networks"],"x-required-tier":"Starter+"}},"/api/rest/v1/charts":{"get":{"description":"<div class=\"tier-pill-row\"><span class=\"tier-pill tier-pill--professional\">Professional</span></div><p class=\"tier-pill-prose\">Callers below **Professional** receive `HTTP 403` with error code `TIER_RESTRICTED`.</p>\n\nPaginated chart positions across podcasts for a given platform. The envelope-level `as_of_date` tells clients which UTC day the response is anchored to — resolved to the most recent day upstream has a chart for the requested (platform, country, category); `null` when no chart was available in the recent window.","operationId":"getGlobalCharts","parameters":[{"name":"page","required":false,"in":"query","description":"Page number (1-indexed)","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"per_page","required":false,"in":"query","description":"Results per page. Optional — when omitted, defaults to the caller tier default (FREE=10, STARTER=25, PROFESSIONAL=25). Requesting a higher value is silently capped to the tier maximum (FREE=10, STARTER=25, PROFESSIONAL=100; no 400).","schema":{"type":"number"}},{"name":"platform","required":true,"in":"query","description":"Chart platform (required)","schema":{"type":"string","enum":["apple_podcasts","spotify"]}},{"name":"category","required":true,"in":"query","description":"Category slug filter (omit for all categories). Use `top-podcasts` for the platform-wide chart on either platform — it's the cross-platform slug for Podchaser's `Top Podcasts` view. On Apple Podcasts, `allcategories` is an equivalent alias of `top-podcasts` (both resolve to the upstream `All Categories` chart). Apple Podcasts: all 111 listed slugs are supported. Spotify: only the following 18 slugs have chart data — arts, business, comedy, education, fiction, health-and-fitness, history, leisure, music, news, religion-and-spirituality, science, society-and-culture, sports, technology, top-podcasts, true-crime, tv-and-film. Note: Apple and Spotify use different hyphenation for a handful of shared categories — Spotify spells them `tv-and-film`, `society-and-culture`, `religion-and-spirituality`, `health-and-fitness`; Apple spells them `tv-film`, `society-culture`, `religion-spirituality`, `health-fitness`. Selecting an unsupported (platform, category) pair returns `400 VALIDATION_ERROR` with the supported list for that platform.","schema":{"default":"top-podcasts","example":"top-podcasts","type":"string","enum":["allcategories","after-shows","alternative-health","animation-manga","arts","astronomy","automotive","aviation","baseball","basketball","books","buddhism","business","business-news","careers","chemistry","christianity","comedy","comedy-fiction","comedy-interviews","courses","crafts","cricket","daily-news","design","documentary","drama","earth-sciences","education","education-for-kids","entertainment-news","entrepreneurship","fantasy-sports","fashion-beauty","fiction","film-history","film-interviews","film-reviews","fitness","food","football","games","golf","government","health-and-fitness","health-fitness","hinduism","history","hobbies","hockey","home-garden","how-to","improv","investing","islam","judaism","kids-family","language-learning","leisure","life-sciences","management","marketing","mathematics","medicine","mental-health","music","music-commentary","music-history","music-interviews","natural-sciences","nature","news","news-commentary","non-profit","nutrition","parenting","performing-arts","personal-journals","pets-animals","philosophy","physics","places-travel","politics","relationships","religion","religion-and-spirituality","religion-spirituality","rugby","running","science","science-fiction","self-improvement","sexuality","soccer","social-sciences","society-and-culture","society-culture","spirituality","sports","sports-news","stand-up","stories-for-kids","swimming","tv-and-film","tv-film","tv-reviews","tech-news","technology","tennis","top-podcasts","true-crime","video-games","visual-arts","volleyball","wrestling"]}},{"name":"country","required":true,"in":"query","description":"Country code filter (lowercase ISO 3166-1 alpha-2). Defaults to `us` when omitted. Apple Podcasts: all 173 listed codes are supported. Spotify: only the following codes have chart data — ar, at, au, br, ca, cl, co, de, dk, es, fi, fr, gb, id, ie, in, it, jp, mx, nl, no, nz, ph, pl, se, us. Selecting an unsupported (platform, country) pair returns `400 VALIDATION_ERROR`.","schema":{"default":"us","example":"us","type":"string","enum":["ae","af","ag","ai","al","am","ao","ar","at","au","az","ba","bb","be","bf","bg","bh","bj","bn","bo","br","bs","bt","bw","by","bz","ca","cd","cg","ch","ci","cl","cm","cn","co","cr","cv","cy","cz","de","dk","dm","do","dz","ec","ee","eg","es","fi","fj","fm","fr","ga","gb","gd","ge","gh","gm","gr","gt","gw","gy","hk","hn","hr","hu","id","ie","il","in","iq","is","it","jm","jo","jp","ke","kg","kh","kn","kr","kw","ky","kz","la","lb","lc","lk","lr","lt","lu","lv","ly","ma","md","me","mg","mk","ml","mm","mn","mo","mr","ms","mt","mu","mv","mw","mx","my","mz","na","ne","ng","ni","nl","no","np","nr","nz","om","pa","pe","pg","ph","pk","pl","pt","pw","py","qa","ro","rs","ru","rw","sa","sb","sc","se","sg","si","sk","sl","sn","sr","st","sv","sz","tc","td","th","tj","tm","tn","to","tr","tt","tw","tz","ua","ug","us","uy","uz","vc","ve","vg","vn","vu","ye","za","zm","zw"]}},{"name":"sort","required":false,"in":"query","description":"Sort field","schema":{"default":"position","type":"string","enum":["position","category","country"]}},{"name":"sort_direction","required":false,"in":"query","description":"Sort direction","schema":{"default":"asc","type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"Paginated global chart positions with envelope-level `as_of_date`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedGlobalChartResponseDto"}}}},"400":{"description":"Validation error — malformed query parameters or path variables.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"401":{"description":"Missing or invalid API key (header `x-api-key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"403":{"description":"Requires **Professional** tier. Callers on a lower tier receive HTTP 403 with error code `TIER_RESTRICTED`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"404":{"description":"The requested resource was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"429":{"description":"Rate limit exceeded. The `Retry-After` header carries the seconds to wait; `error.details.bucket` identifies which limit fired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"500":{"description":"Unexpected server error. Report `error.requestId` to support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}},"503":{"description":"A dependency is temporarily unavailable (`error.code = EXTERNAL_SERVICE_ERROR`). Retry with exponential back-off.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelopeDto"}}}}},"summary":"Get global podcast charts","tags":["Charts"],"x-required-tier":"Professional"}}},"info":{"title":"Podchaser REST API","description":"The world’s largest podcast database, available through a single API. Millions of podcasts and hundreds of millions of episodes — search them, enrich your data with them, monitor them at scale, and surface the audience and creator signals that power smarter decisions across media monitoring, competitive intelligence, and podcast analytics.\n\n- **Existing REST API customer?** [Find your API key](https://www.podchaser.com/profile/settings/api/api-settings) in your Podchaser account settings.\n- **New here?** Compare plans and learn about the REST API and Enterprise API offerings on the [Podchaser API landing page](https://www.podchaser.com/api).\n- **Hook into AI tools with MCP.** Use our [MCP server](#tag/mcp) to connect Podchaser data directly to AI assistants like Claude and Cursor.\n\n## Machine-readable docs\n\n- OpenAPI (JSON): `/api/rest/v1/openapi.json`\n- OpenAPI (YAML): `/api/rest/v1/openapi.yaml`\n- LLM index: `/llms.txt` (also at `/api/rest/v1/llms.txt`)\n- LLM full reference: `/llms-full.txt` (also at `/api/rest/v1/llms-full.txt`)","version":"1.0.0","contact":{}},"tags":[{"name":"Quickstart","description":"> **Looking for the Enterprise API?** Higher volumes, S3 delivery, or custom data — see the [Enterprise API docs](https://api-docs.podchaser.com/). The Enterprise API is a separate product with its own surface.\n\n## 1. Send your API key\n\nEvery request must carry your key in the `x-api-key` header. The key determines which endpoints, filters, and fields are available; quota and rate limits live in Redis, not in the key string.\n\n## 2. Make your first call\n\n```bash\ncurl -H \"x-api-key: YOUR_KEY\" \\\n  https://developers.podchaser.com/api/rest/v1/podcasts/1576373\n```\n\n## Three endpoints to know on day one\n\n- `GET /search/podcasts?q=…` — find a podcast by name, topic, or boolean expression.\n- `GET /podcasts/{id}` — full metadata for a single podcast.\n- `GET /usage` — current tier, quota, and remaining requests for the cycle. This call does not count against your quota."},{"name":"MCP","description":"Connect this REST API directly to AI assistants like Claude and Cursor over the [Model Context Protocol](https://modelcontextprotocol.io). Once connected, you ask questions in plain language and the assistant makes the calls for you — no integration code to write.\n\n## Server URL\n\n```\nhttps://developers.podchaser.com/mcp\n```\n\nStreamable HTTP, authenticated with your API key in the `x-api-key` header — the same key the REST endpoints take. There is **no OAuth flow**: nothing to authorize, no consent screen. Paste your key into one of the blocks below and you are connected. [Find your API key](https://www.podchaser.com/profile/settings/api/api-settings) in your account settings, or [compare plans](https://www.podchaser.com/api) if you do not have one yet.\n\n## Quick connect\n\nOne-click install: [Add to Cursor](/api/rest/v1/mcp/install/cursor) · [Add to VS Code](https://vscode.dev/redirect/mcp/install?name=podchaser&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fdevelopers.podchaser.com%2Fmcp%22%2C%22headers%22%3A%7B%22x-api-key%22%3A%22%24%7Binput%3Apodchaser_api_key%7D%22%7D%7D) — then add your API key (VS Code prompts you for it; in Cursor, replace the `PASTE_YOUR_API_KEY` placeholder in `mcp.json`).\n\nEvery client below is one command or one config block, buttons included. Replace `PASTE_YOUR_API_KEY` with your own key in each snippet.\n\nEach JSON block is a whole file, shown with nothing else in it — the file you are opening probably is not empty. Merge the block rather than paste it: keep the outer braces and everything already inside them, add the `\"mcpServers\"` key if it is not there yet, and put the `\"podchaser\": { … }` entry inside that. A file left holding two top-level `{ … }` documents parses as neither, and the client then loads none of its servers rather than simply missing this one.\n\n### Claude Code\n\nRun this in your terminal, from the project you want to use it in. `claude mcp add` defaults to `local` scope — the server loads in that one directory and stays private to you. Add `--scope user` to register it once for every project, or `--scope project` to write a `.mcp.json` you can commit for your team. It prints an `Added …` line on success; `claude mcp list` then shows the connection status.\n\n```bash\nclaude mcp add --transport http podchaser \\\n  https://developers.podchaser.com/mcp \\\n  --header \"x-api-key: PASTE_YOUR_API_KEY\"\n```\n\n### Codex CLI\n\nOpen or create `~/.codex/config.toml` and append the block below. `codex mcp add` has no flag for a custom header, so the key goes in the file. Swap `http_headers` for `env_http_headers` to read it from an environment variable instead of storing it here.\n\n```toml\n[mcp_servers.podchaser]\nurl = \"https://developers.podchaser.com/mcp\"\nhttp_headers = { \"x-api-key\" = \"PASTE_YOUR_API_KEY\" }\n```\n\n### VS Code\n\nUse the one-click button above, or open `.vscode/mcp.json` and add the block below, then reload the window. The `inputs` block makes VS Code prompt each person for their own key and store it securely, so the file is safe to commit for your team.\n\nPut it in `.vscode/mcp.json` specifically — VS Code [silently discards the `headers` block](https://github.com/microsoft/vscode/issues/319528) from a workspace-root `.mcp.json`, which shows up as an unexplained `401`.\n\n```json\n{\n  \"inputs\": [\n    {\n      \"id\": \"podchaser_api_key\",\n      \"type\": \"promptString\",\n      \"description\": \"Podchaser API key\",\n      \"password\": true\n    }\n  ],\n  \"servers\": {\n    \"podchaser\": {\n      \"type\": \"http\",\n      \"url\": \"https://developers.podchaser.com/mcp\",\n      \"headers\": {\n        \"x-api-key\": \"${input:podchaser_api_key}\"\n      }\n    }\n  }\n}\n```\n\n### Cursor\n\nUse the one-click button above, or open `~/.cursor/mcp.json` (`.cursor/mcp.json` for a single project), add the block below, then save and restart. Cursor has no command-line installer for MCP servers.\n\n```json\n{\n  \"mcpServers\": {\n    \"podchaser\": {\n      \"url\": \"https://developers.podchaser.com/mcp\",\n      \"headers\": {\n        \"x-api-key\": \"PASTE_YOUR_API_KEY\"\n      }\n    }\n  }\n}\n```\n\n### Windsurf\n\nOpen or create `~/.codeium/windsurf/mcp_config.json`, add the block below, then refresh the server list in Cascade. Windsurf names the URL key `serverUrl`, not `url`.\n\n```json\n{\n  \"mcpServers\": {\n    \"podchaser\": {\n      \"serverUrl\": \"https://developers.podchaser.com/mcp\",\n      \"headers\": {\n        \"x-api-key\": \"PASTE_YOUR_API_KEY\"\n      }\n    }\n  }\n}\n```\n\n### Zed\n\nOpen your Zed `settings.json` (`cmd-,`), add the block below, then restart. Zed offers an OAuth sign-in for remote servers that carry no `Authorization` header; this server has no OAuth flow, so dismiss that prompt if it appears — the `x-api-key` header below is what authenticates you.\n\n```json\n{\n  \"context_servers\": {\n    \"podchaser\": {\n      \"url\": \"https://developers.podchaser.com/mcp\",\n      \"headers\": {\n        \"x-api-key\": \"PASTE_YOUR_API_KEY\"\n      }\n    }\n  }\n}\n```\n\n### Claude Desktop\n\n**1. Open the config file.** In **Claude Desktop** (the menu-bar app, not claude.ai in a browser): **Settings → Developer → Edit Config**. That opens `claude_desktop_config.json`. Yours may already have keys such as `preferences` or `coworkUserFilesPath` and **no** `mcpServers` — that is normal. Do **not** replace the file. Do **not** paste a second `{ … }` underneath it (that is the `Unexpected non-whitespace character after JSON` error).\n\n**2. Merge the Podchaser server.** Add a top-level `\"mcpServers\"` object next to your existing keys if it is missing, and put `\"podchaser\"` inside it. Replace `PASTE_YOUR_API_KEY` with your [API key](https://www.podchaser.com/profile/settings/api/api-settings). Claude Desktop cannot attach a custom header to a remote URL in this file, so the block below bridges through `mcp-remote`.\n\n```json\n{\n  \"mcpServers\": {\n    \"podchaser\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"mcp-remote\",\n        \"https://developers.podchaser.com/mcp\",\n        \"--header\",\n        \"x-api-key:${PODCHASER_API_KEY}\"\n      ],\n      \"env\": {\n        \"PODCHASER_API_KEY\": \"PASTE_YOUR_API_KEY\"\n      }\n    }\n  }\n}\n```\n\n**3. Fully quit and reopen.** Saving is not enough — Claude Desktop does not reload this file while it is running. On macOS use **Claude → Quit Claude** in the menu bar (closing the window leaves it running). On Windows quit from the system-tray icon. Then open Claude Desktop again.\n\n**4. Confirm it loaded.** After reopen, use the **+** control in the chat box and look under Connectors for `podchaser`. Ask *\"What is my Podchaser API usage?\"* — that check is free.\n\nAccount-wide Connectors on claude.ai cannot take a per-user API key on this server.\n\n**Note.** This block runs `npx`. If the server does not start after a correct merge and a full quit, in Terminal run `node --version`. If that command is not found, install Node from [nodejs.org/en/download](https://nodejs.org/en/download) and quit/reopen Desktop again.\n\n### Any other MCP client\n\nIf the client speaks Streamable HTTP, point it at the server URL and add the `x-api-key` header — that is the whole configuration. If it only speaks stdio, bridge to it with [`mcp-remote`](https://www.npmjs.com/package/mcp-remote):\n\n```bash\nnpx -y mcp-remote https://developers.podchaser.com/mcp \\\n  --header \"x-api-key: PASTE_YOUR_API_KEY\"\n```\n\nThat spacing is correct for a shell. If you are putting it into a JSON `args` array instead, drop the space after the colon and move the key to `env`, exactly as the Claude Desktop block above does — Cursor, Codex CLI and Claude Desktop on Windows do not escape spaces inside `args`, so `\"x-api-key: KEY\"` reaches the server mangled.\n\n## Test the connection\n\nAsk your assistant *\"What is my Podchaser API usage?\"* — it should return your tier and remaining requests. This check is free and does not count against your quota.\n\n## Troubleshooting\n\n- **The client will not start, or reports a config parse error.** A message like `Unexpected non-whitespace character after JSON` means the file now holds two JSON documents — the block was pasted below the config that was already there instead of merged into it. Keep the outer braces you had and move `\"podchaser\": { … }` inside them, so the file has exactly one top-level `{ … }`. Until it parses, the client loads none of its servers.\n- **I only see Connect, or there is no API key field.** You are on a company Claude plan. Customize → Connectors will not ask for a Podchaser key. Use **Settings → Developer → Edit Config** in the Claude Desktop section.\n- **The config looks right but `podchaser` is missing after I save.** Claude Desktop does not reload the file while it is running. Fully quit (Claude → Quit Claude on macOS; the tray icon on Windows) and reopen.\n- **An Owner added Podchaser for the org and I still have no access.** Account-wide Connectors cannot send your API key on this server. Use Edit Config on your laptop.\n- **`npx` is not found, or the server does not start after a correct merge.** See the Node note at the end of the Claude Desktop section.\n- **`401` on every call.** Your API key is missing or wrong — check the `x-api-key` value in your config. The header name is case-insensitive; the key itself is not. If the config looks right, check the client is sending headers at all (see the VS Code note above).\n- **The client asks you to sign in, or fails with an authentication error.** This server does not use OAuth, and it deliberately returns `404` on OAuth discovery so clients fall back to the header. Make sure the `headers` block is present and spelled exactly as above.\n- **A tool you expected is missing from the list.** Tools are filtered by tier before the list is sent, so a tool above your tier never appears. Ask for your usage to see the tier you are on.\n- **`403 TIER_RESTRICTED`.** The tool is real but your tier cannot call it.\n- **`429`.** Two different limits share this status: a short-term rate limit (retry after a moment) and the monthly quota (`QUOTA_EXCEEDED`, resets at `cycle_end`). Asking for your usage tells you which one you hit, and does not itself count against the quota.\n- **Still stuck?** The [setup guide](https://support.podchaser.com/en/articles/15901951-podchaser-mcp-server-for-rest-api) has the long-form walkthrough.\n\n## What you get\n\nThe MCP server is **read-only** and uses the same `x-api-key`, tier, quota, and field rules as the rest of this API. Tools and fields are scoped to your tier: tools you cannot call are hidden from the tool list, and higher-tier fields are dropped from results. MCP results do not carry the `restricted_fields` list that REST responses do, so call the REST endpoint directly when you need to see exactly which fields your tier is missing.\n\n> The MCP server works only with this REST API. It does **not** connect to the [Enterprise GraphQL API](https://api-docs.podchaser.com/)."},{"name":"Podcasts","description":"Per-podcast resource fetches: metadata, reach, charts, credits, demographics, brand safety, network, similar, contacts, socials and sponsors. Path id defaults to a Podchaser id; `id_type=apple_podcasts|spotify|rss` resolves an external identifier."},{"name":"Episodes","description":"Per-episode resource fetches: metadata, reach, credits, brand safety and transcript. Episode endpoints are reach-tier or higher except `/transcript`, which is open to all tiers when transcript data is available."},{"name":"Creators","description":"Per-creator resource fetches: profile, podcast credits and episode credits. Creator endpoints are Starter+ across the board."},{"name":"Networks","description":"Per-network resource fetches: profile, member podcasts and aggregate audience insights. Network endpoints require Starter or Professional tier."},{"name":"Sponsors","description":"Per-sponsor resource fetches: metadata (estimated ad spend, total sponsored podcasts and episodes), paginated podcast appearances and episode appearances. Professional-only."},{"name":"Charts","description":"Global podcast chart positions by platform, country and category. Returns paginated rankings anchored to the most recent available date. Professional-only."},{"name":"Search","description":"Full-text and filtered search across podcasts, episodes, transcripts, networks and creators. Per-page caps are tier-driven (Starter 100 / Pro 500); filters that exceed the caller’s tier surface as `400 VALIDATION_ERROR`."},{"name":"Reference","description":"Lookup data needed to build search filters: category taxonomy, language list, demographic ranges and brand-safety code dictionary."},{"name":"Usage","description":"Caller-side rate-limit and quota introspection. Returns the active cycle, remaining quota and per-bucket counters; the same body schema is reflected in the `429 QUOTA_EXCEEDED` error envelope."},{"name":"System","description":"Operator surfaces: liveness (`/health/live`), readiness (`/health/ready`) and the legacy alias (`/health`). These return the Terminus probe shape, not the V1 envelope, and are unauthenticated by design so the ALB target-group check can hit them."},{"name":"Conventions","description":"### Date & time wire formats (FR-16)\n\nResponse-body fields tagged `datetime` are serialized as `YYYY-MM-DD HH:MM:SS` in **UTC**, with a literal space (not `T`), no millisecond fragment, and **no** `Z` / `+00:00` suffix. Clients MUST treat the value as UTC — parsing as local time will silently shift the moment.\n\n```js\n// JavaScript / TypeScript\nconst utc = new Date(value.replace(' ', 'T') + 'Z');\n```\n\n```python\n# Python\nfrom datetime import datetime, timezone\nutc = datetime.strptime(value, \"%Y-%m-%d %H:%M:%S\").replace(tzinfo=timezone.utc)\n```\n\nResponse-body fields tagged `date` (no time component) are serialized as `YYYY-MM-DD` (UTC calendar date). The `cycle_end` field inside the `429 QUOTA_EXCEEDED` error body follows the same `datetime` format as success bodies.\n\nIn the OpenAPI document each `datetime` field carries the custom keyword `format: \"date-time-utc-space\"` — this is intentionally NOT the standard `date-time` keyword, which would direct generated SDKs to RFC 3339 / ISO 8601 parsing and fail on the literal-space separator.\n\nThe wire-body formats above apply only to JSON response bodies. The `X-RateLimit-Reset` header carries Unix epoch seconds; `Retry-After` carries integer seconds; structured logs use full ISO 8601 with millisecond precision; inbound range-filter query parameters accept ISO 8601."}],"servers":[{"url":"https://developers.podchaser.com"}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"x-api-key","description":"API key issued by Podchaser. Send it verbatim in the `x-api-key` request header."}},"schemas":{"ErrorBodyDto":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code. Clients SHOULD branch on this value.","enum":["VALIDATION_ERROR","UNAUTHORIZED","TIER_RESTRICTED","RESOURCE_NOT_FOUND","PAYLOAD_TOO_LARGE","RATE_LIMITED","QUOTA_EXCEEDED","INTERNAL_ERROR","FORBIDDEN","CONFLICT","DEPRECATED_ENDPOINT","SERVICE_UNAVAILABLE","GATEWAY_TIMEOUT","EXTERNAL_SERVICE_ERROR"],"example":"RESOURCE_NOT_FOUND"},"message":{"type":"string","description":"Human-readable explanation. Stable but not part of the API contract.","example":"Podcast not found"},"status":{"type":"number","description":"HTTP status code. Mirrors the response status line.","enum":[400,401,403,404,409,410,413,422,429,500,502,503,504],"example":404},"requestId":{"type":"string","description":"Request correlation id (echo of `X-Correlation-Id` response header). Pass to support when reporting issues.","example":"01J9P3RJX5K7Z2YQM4TGWQ8E2N"},"timestamp":{"type":"string","description":"ISO 8601 timestamp when the error was generated.","example":"2026-04-19T12:34:56.789Z"},"details":{"type":"object","description":"Per-error structured payload (e.g. `{ retryAfter, bucket }` for `RATE_LIMITED`, `{ fields }` for `VALIDATION_ERROR`, `{ currentTier, requiredTiers }` for `TIER_RESTRICTED`). Always an object; empty when the error has no extra context.","additionalProperties":true,"example":{}}},"required":["code","message","status","requestId","timestamp","details"]},"ErrorEnvelopeDto":{"type":"object","properties":{"error":{"$ref":"#/components/schemas/ErrorBodyDto"}},"required":["error"]},"PodcastCategoryDto":{"type":"object","properties":{"title":{"type":"string"},"slug":{"type":"string"}},"required":["title","slug"]},"PodcastAuthorDto":{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string"}},"required":["name"]},"PodcastRemovedInfoDto":{"type":"object","properties":{"isRemoved":{"type":"boolean"},"reason":{"type":"string"},"removedDate":{"type":"string","format":"date-time-utc-space","example":"2026-04-24 17:30:45"},"redirectedPodcastId":{"type":"string"}},"required":["isRemoved"]},"PodcastResponseDto":{"type":"object","properties":{"id":{"type":"string"},"applePodcastsId":{"type":"string"},"spotifyId":{"type":"string"},"rssUrl":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"webUrl":{"type":"string"},"imageUrl":{"type":"string"},"language":{"type":"string"},"numberOfEpisodes":{"type":"number"},"avgEpisodeLength":{"type":"number"},"episodeFrequency":{"type":"number"},"startDate":{"type":"string","format":"date-time-utc-space","example":"2026-04-24 17:30:45"},"latestEpisodeDate":{"type":"string","format":"date-time-utc-space","example":"2026-04-24 17:30:45"},"categories":{"type":"array","items":{"$ref":"#/components/schemas/PodcastCategoryDto"}},"hasGuests":{"type":"boolean","description":"Whether the podcast regularly features guests (Starter+)"},"explicit":{"type":"boolean"},"status":{"type":"string","enum":["active","idle","complete"]},"author":{"$ref":"#/components/schemas/PodcastAuthorDto"},"modifiedDate":{"type":"string","format":"date-time-utc-space","example":"2026-04-24 17:30:45"},"removedInfo":{"$ref":"#/components/schemas/PodcastRemovedInfoDto"},"hostingProvider":{"type":"string","description":"The hosting provider of the podcast (e.g. Acast, Libsyn), or null if unknown.","example":"Acast"}},"required":["id","title"]},"ReachRangeDto":{"type":"object","properties":{"from":{"type":"number","description":"Lower bound of the estimated range (Professional)"},"to":{"type":"number","description":"Upper bound of the estimated range (Professional)"}},"required":["from","to"]},"PodcastReachResponseDto":{"type":"object","properties":{"powerScore":{"type":"number","description":"Podchaser Power Score (0–100) (Starter+)"},"monthlyReach":{"description":"Estimated monthly audience range (Professional)","allOf":[{"$ref":"#/components/schemas/ReachRangeDto"}]},"avgEpisodeReach":{"description":"Estimated per-episode audience range (Professional)","allOf":[{"$ref":"#/components/schemas/ReachRangeDto"}]}}},"EpisodePodcastSummaryDto":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"rss":{"type":"string"},"imageUrl":{"type":"string"}},"required":["id","title"]},"EpisodeResponseDto":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"airDate":{"type":"string","format":"date-time-utc-space","example":"2026-04-24 17:30:45"},"imageUrl":{"type":"string"},"audioUrl":{"type":"string"},"webUrl":{"type":"string"},"length":{"type":"number"},"explicit":{"type":"boolean"},"episodeType":{"type":"string"},"guid":{"type":"string"},"fileSize":{"type":"number"},"modifiedDate":{"type":"string","format":"date-time-utc-space","example":"2026-04-24 17:30:45"},"podcast":{"$ref":"#/components/schemas/EpisodePodcastSummaryDto"}},"required":["id","title"]},"PaginationMeta":{"type":"object","properties":{"page":{"type":"number","description":"Current page number (1-indexed)","example":1},"per_page":{"type":"number","description":"Results per page","example":25},"total_results":{"type":"number","description":"Total number of results","example":482},"total_pages":{"type":"number","description":"Total number of pages (ceil(total_results / per_page))","example":20},"has_more":{"type":"boolean","description":"Whether more pages exist","example":true}},"required":["page","per_page","total_results","total_pages","has_more"]},"PaginatedEpisodeResponseDto":{"type":"object","properties":{"data":{"description":"Result set for the requested page","type":"array","items":{"$ref":"#/components/schemas/EpisodeResponseDto"}},"pagination":{"description":"Pagination envelope metadata","allOf":[{"$ref":"#/components/schemas/PaginationMeta"}]}},"required":["data","pagination"]},"PodcastChartResponseDto":{"type":"object","properties":{"date":{"type":"string","description":"Chart date (Professional)"},"platform":{"type":"string","enum":["apple_podcasts","spotify"],"description":"Chart platform (Professional)"},"country":{"type":"string","description":"Country code (Professional)"},"category":{"type":"string","description":"Category slug (Professional)"},"position":{"type":"number","description":"Chart position (Professional)"},"change":{"type":"number","description":"Position change from previous day (Professional)"},"changeStatus":{"type":"string","enum":["no_change","new","up","down"],"description":"Direction of position change (Professional)"}},"required":["date","platform","position"]},"PaginatedPodcastChartResponseDto":{"type":"object","properties":{"data":{"description":"Chart rows for the resolved as-of date (may be empty).","type":"array","items":{"$ref":"#/components/schemas/PodcastChartResponseDto"}},"pagination":{"description":"Pagination envelope metadata.","allOf":[{"$ref":"#/components/schemas/PaginationMeta"}]},"as_of_date":{"type":"string","nullable":true,"example":"2026-04-21","description":"Anchor date ('YYYY-MM-DD', UTC) the response is scoped to. Resolved to the most recent day a chart is available in Podchaser's system for the requested (platform, country, category); `null` when no chart was available in the recent window. When `data` is empty and `as_of_date` is set, the podcast does not appear on that day's chart."}},"required":["data","pagination","as_of_date"]},"CreditCreatorDto":{"type":"object","properties":{"pcid":{"type":"string","description":"Creator Podchaser ID (Starter+)"},"name":{"type":"string","description":"Creator name (Starter+)"},"bio":{"type":"string","description":"Creator bio (Starter+)"},"imageUrl":{"type":"string","description":"Creator image URL (Starter+)"},"url":{"type":"string","description":"Creator web URL (Starter+)"}},"required":["pcid","name"]},"CreditRoleDto":{"type":"object","properties":{"code":{"type":"string","description":"Role code (Starter+)"},"title":{"type":"string","description":"Role display name (Starter+)"}},"required":["code","title"]},"CreditLastEpisodeDto":{"type":"object","properties":{"id":{"type":"string","description":"Most recent episode ID (Starter+)"},"title":{"type":"string","description":"Most recent episode title (Starter+)"},"airDate":{"type":"string","format":"date-time-utc-space","example":"2026-04-24 17:30:45","description":"Most recent episode air date (UTC, format `YYYY-MM-DD HH:MM:SS`) (Starter+)"},"role":{"type":"string","description":"Role on most recent episode (Starter+)"}},"required":["id","title"]},"PodcastCreditResponseDto":{"type":"object","properties":{"creator":{"description":"Creator details (Starter+)","allOf":[{"$ref":"#/components/schemas/CreditCreatorDto"}]},"role":{"description":"Credit role (Starter+)","allOf":[{"$ref":"#/components/schemas/CreditRoleDto"}]},"episodeCount":{"type":"number","description":"Number of episodes with this credit (Starter+)"},"episodeCreditsModifiedDate":{"type":"string","format":"date-time-utc-space","example":"2026-04-24 17:30:45","description":"The date the podcast credit most recently had its episode credits updated (UTC, format `YYYY-MM-DD HH:MM:SS`). Reflects the latest change to the credit at the episode level — a new episode credit attached, an existing episode credit removed, or any field on an underlying episode credit changing — so it is the right freshness signal for incremental sync. (Starter+)"},"lastEpisode":{"description":"Most recent episode with this credit (Starter+)","allOf":[{"$ref":"#/components/schemas/CreditLastEpisodeDto"}]}},"required":["creator","role","episodeCount"]},"PaginatedPodcastCreditResponseDto":{"type":"object","properties":{"data":{"description":"Result set for the requested page","type":"array","items":{"$ref":"#/components/schemas/PodcastCreditResponseDto"}},"pagination":{"description":"Pagination envelope metadata","allOf":[{"$ref":"#/components/schemas/PaginationMeta"}]}},"required":["data","pagination"]},"DemographicRangeDto":{"type":"object","properties":{"from":{"type":"string","description":"Lower bound label of the range (Starter+)"},"to":{"type":"string","description":"Upper bound label of the range (Starter+)"},"count":{"type":"number","description":"Listener count in this range (Starter+)"}},"required":["from","to","count"]},"DemographicSegmentDto":{"type":"object","properties":{"title":{"type":"string","description":"Segment label (Starter+)"},"percentage":{"type":"number","description":"Percentage of audience in this segment (Starter+)"}},"required":["title","percentage"]},"PodcastDemographicsResponseDto":{"type":"object","properties":{"medianAge":{"type":"number","description":"Median listener age (Starter+)"},"ageRanges":{"description":"Age distribution (Starter+)","type":"array","items":{"$ref":"#/components/schemas/DemographicRangeDto"}},"medianIncome":{"type":"number","description":"Median listener income (USD) (Starter+)"},"incomeRanges":{"description":"Income distribution (Starter+)","type":"array","items":{"$ref":"#/components/schemas/DemographicRangeDto"}},"genderBias":{"description":"Gender skew breakdown (Starter+)","allOf":[{"$ref":"#/components/schemas/DemographicSegmentDto"}]},"parentalStatus":{"type":"string","description":"Parental status skew (Starter+)"},"educationLevel":{"type":"string","description":"Education level skew (Starter+)"},"maritalStatus":{"type":"string","description":"Marital status skew (Starter+)"},"politicalSkew":{"type":"string","description":"Political leaning (Starter+)"},"countries":{"description":"Top listener countries (Starter+)","type":"array","items":{"$ref":"#/components/schemas/DemographicSegmentDto"}},"states":{"description":"Top listener US states (Starter+)","type":"array","items":{"$ref":"#/components/schemas/DemographicSegmentDto"}},"cities":{"description":"Top listener cities (Starter+)","type":"array","items":{"$ref":"#/components/schemas/DemographicSegmentDto"}},"occupations":{"description":"Top listener occupations (Starter+)","type":"array","items":{"$ref":"#/components/schemas/DemographicSegmentDto"}},"interests":{"description":"Top listener interests (Starter+)","type":"array","items":{"$ref":"#/components/schemas/DemographicSegmentDto"}},"brands":{"description":"Top listener brands (Starter+)","type":"array","items":{"$ref":"#/components/schemas/DemographicSegmentDto"}},"influencers":{"description":"Top listener influencers (Starter+)","type":"array","items":{"$ref":"#/components/schemas/DemographicSegmentDto"}},"employers":{"description":"Top listener employers (Starter+)","type":"array","items":{"$ref":"#/components/schemas/DemographicSegmentDto"}},"ethnicities":{"description":"Listener ethnicity breakdown (Starter+)","type":"array","items":{"$ref":"#/components/schemas/DemographicSegmentDto"}}}},"PodcastBrandSafetyResponseDto":{"type":"object","properties":{"code":{"type":"string","description":"Brand safety category code (Professional)","enum":["adult","censor","criminal","disinfo","drugs","graphic","inflammatory","piracy","political","profanity","spam","terror","weapons"]},"description":{"type":"string","description":"Human-readable description of the category (Professional)"},"value":{"type":"number","description":"Risk score (0-1) (Professional)"},"level":{"type":"string","description":"Risk level (Professional)","enum":["clean","low","medium","high"]}},"required":["code","description","value","level"]},"NetworkSocialLinksDto":{"type":"object","properties":{"twitter":{"type":"string"},"facebook":{"type":"string"},"instagram":{"type":"string"},"youtube":{"type":"string"},"linkedin":{"type":"string"},"tiktok":{"type":"string"},"patreon":{"type":"string"},"twitch":{"type":"string"}}},"NetworkResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Network Podchaser ID (Starter+)"},"title":{"type":"string","description":"Network title (Starter+)"},"description":{"type":"string","description":"Network description (Starter+)"},"url":{"type":"string","description":"Network RSS or canonical URL (Starter+)"},"webUrl":{"type":"string","description":"Network website URL (Starter+)"},"imageUrl":{"type":"string","description":"Network logo image URL (Starter+)"},"numberOfPodcasts":{"type":"number","description":"Number of podcasts in this network (Starter+)"},"socialLinks":{"description":"Network social media URLs (Starter+)","allOf":[{"$ref":"#/components/schemas/NetworkSocialLinksDto"}]},"modifiedDate":{"type":"string","format":"date-time-utc-space","example":"2026-04-24 17:30:45","description":"Last-modified timestamp (Starter+)"}},"required":["id","title"]},"PaginatedPodcastResponseDto":{"type":"object","properties":{"data":{"description":"Result set for the requested page","type":"array","items":{"$ref":"#/components/schemas/PodcastResponseDto"}},"pagination":{"description":"Pagination envelope metadata","allOf":[{"$ref":"#/components/schemas/PaginationMeta"}]}},"required":["data","pagination"]},"PodcastContactResponseDto":{"type":"object","properties":{"rssEmail":{"type":"string","description":"Email address from the RSS feed (Starter+)"},"email":{"type":"string","description":"Contact email (Professional)"},"url":{"type":"string","description":"Contact URL (Professional)"},"fullName":{"type":"string","description":"Contact full name (Professional)"},"type":{"type":"string","description":"Contact type (Professional)"},"role":{"type":"string","description":"Role / title (Professional)"},"department":{"type":"string","description":"Department (Professional)"},"confidence":{"type":"number","description":"Data confidence score (0-1) (Professional)"},"modifiedDate":{"type":"string","format":"date-time-utc-space","example":"2026-04-24 17:30:45","description":"Last-updated timestamp (UTC, format `YYYY-MM-DD HH:MM:SS`) (Professional)"}}},"PaginatedPodcastContactResponseDto":{"type":"object","properties":{"data":{"description":"Result set for the requested page","type":"array","items":{"$ref":"#/components/schemas/PodcastContactResponseDto"}},"pagination":{"description":"Pagination envelope metadata","allOf":[{"$ref":"#/components/schemas/PaginationMeta"}]}},"required":["data","pagination"]},"SocialLinksDto":{"type":"object","properties":{"twitter":{"type":"string","description":"Twitter / X URL (Starter+)"},"facebook":{"type":"string","description":"Facebook URL (Starter+)"},"instagram":{"type":"string","description":"Instagram URL (Starter+)"},"youtube":{"type":"string","description":"YouTube URL (Starter+)"},"linkedin":{"type":"string","description":"LinkedIn URL (Starter+)"},"tiktok":{"type":"string","description":"TikTok URL (Starter+)"},"patreon":{"type":"string","description":"Patreon URL (Starter+)"},"twitch":{"type":"string","description":"Twitch URL (Starter+)"}}},"SocialFollowerCountsDto":{"type":"object","properties":{"twitter":{"type":"number","description":"Twitter / X follower count (Professional)"},"facebook":{"type":"number","description":"Facebook follower count (Professional)"},"instagram":{"type":"number","description":"Instagram follower count (Professional)"},"youtube":{"type":"number","description":"YouTube subscriber count (Professional)"},"linkedin":{"type":"number","description":"LinkedIn follower count (Professional)"},"tiktok":{"type":"number","description":"TikTok follower count (Professional)"},"patreon":{"type":"number","description":"Patreon patron count (Professional)"},"twitch":{"type":"number","description":"Twitch follower count (Professional)"}}},"HostSocialAccountDto":{"type":"object","properties":{"platform":{"type":"string","description":"Platform identifier (e.g. `twitter`, `instagram`). (Starter+)"},"username":{"type":"string","description":"Handle / username on the platform. (Starter+)"},"url":{"type":"string","description":"Public URL of the social account. (Starter+)"},"followerCount":{"type":"number","description":"Follower / subscriber count for this account. (Professional)"}}},"HostSocialDto":{"type":"object","properties":{"id":{"type":"string","description":"Podchaser ID of the host. (Starter+)"},"name":{"type":"string","description":"Display name of the host. (Starter+)"},"role":{"type":"string","description":"Credit role code. Always `host` for `Podcast.hostSocials`. (Starter+)"},"creditCount":{"type":"number","description":"Total number of episode credits this host has across all podcasts. (Starter+)"},"socialAccounts":{"description":"Social-media accounts attached to this host. (Starter+)","type":"array","items":{"$ref":"#/components/schemas/HostSocialAccountDto"}}},"required":["id","name","role","socialAccounts"]},"PodcastSocialsResponseDto":{"type":"object","properties":{"socialLinks":{"description":"Podcast social media URLs (Starter+)","allOf":[{"$ref":"#/components/schemas/SocialLinksDto"}]},"socialFollowers":{"description":"Podcast social media follower counts (Professional)","allOf":[{"$ref":"#/components/schemas/SocialFollowerCountsDto"}]},"hostSocials":{"description":"Host creator socials (Starter+)","type":"array","items":{"$ref":"#/components/schemas/HostSocialDto"}}},"required":["hostSocials"]},"EstimatedAdSpendDto":{"type":"object","properties":{"low":{"type":"number","description":"Lower bound estimate, in dollars (Professional)"},"high":{"type":"number","description":"Upper bound estimate, in dollars (Professional)"}},"required":["low","high"]},"PodcastSponsorEpisodeResponseDto":{"type":"object","properties":{"episodeId":{"type":"string","description":"Episode Podchaser ID (Professional)"},"episodeTitle":{"type":"string","description":"Episode title (Professional)"},"airDate":{"type":"string","description":"Episode publication date (YYYY-MM-DD HH:MM:SS UTC) (Professional)"},"startTime":{"type":"number","description":"Ad start time in seconds from start of episode (Professional)"},"endTime":{"type":"number","description":"Ad end time in seconds from start of episode (Professional)"},"estimatedAdSpend":{"description":"Estimated spend range for this single placement (Professional)","allOf":[{"$ref":"#/components/schemas/EstimatedAdSpendDto"}]}},"required":["episodeId","episodeTitle"]},"PaginatedPodcastSponsorEpisodeResponseDto":{"type":"object","properties":{"data":{"description":"Result set for the requested page","type":"array","items":{"$ref":"#/components/schemas/PodcastSponsorEpisodeResponseDto"}},"pagination":{"description":"Pagination envelope metadata","allOf":[{"$ref":"#/components/schemas/PaginationMeta"}]}},"required":["data","pagination"]},"PodcastSponsorResponseDto":{"type":"object","properties":{"brandId":{"type":"string","description":"Brand Podchaser ID (Professional)"},"brandName":{"type":"string","description":"Brand name (Professional)"},"episodeCount":{"type":"number","description":"Total number of sponsored episodes (Professional)"},"estimatedTotalAdSpend":{"description":"Estimated total spend across all sponsored episodes (Professional)","allOf":[{"$ref":"#/components/schemas/EstimatedAdSpendDto"}]}},"required":["brandId","brandName","episodeCount"]},"PaginatedPodcastSponsorResponseDto":{"type":"object","properties":{"data":{"description":"Result set for the requested page","type":"array","items":{"$ref":"#/components/schemas/PodcastSponsorResponseDto"}},"pagination":{"description":"Pagination envelope metadata","allOf":[{"$ref":"#/components/schemas/PaginationMeta"}]}},"required":["data","pagination"]},"EpisodeReachRangeDto":{"type":"object","properties":{"from":{"type":"number","description":"Lower bound of the estimated range (Professional)"},"to":{"type":"number","description":"Upper bound of the estimated range (Professional)"}},"required":["from","to"]},"EpisodeReachResponseDto":{"type":"object","properties":{"estimatedReach":{"description":"Estimated episode audience range (Professional)","allOf":[{"$ref":"#/components/schemas/EpisodeReachRangeDto"}]},"podcastEstimatedReach":{"type":"number","description":"Estimated reach derived from podcast-level data (Professional)"},"podcastPowerScore":{"type":"number","description":"Podcast Podchaser Power Score (0–100) (Starter+)"}}},"EpisodeCreditCreatorDto":{"type":"object","properties":{"pcid":{"type":"string","description":"Creator Podchaser ID (Starter+)"},"name":{"type":"string","description":"Creator name (Starter+)"},"imageUrl":{"type":"string","description":"Creator image URL (Starter+)"}},"required":["pcid","name"]},"EpisodeCreditRoleDto":{"type":"object","properties":{"code":{"type":"string","description":"Role code (Starter+)"},"title":{"type":"string","description":"Role display name (Starter+)"}},"required":["code","title"]},"EpisodeCreditCharacterDto":{"type":"object","properties":{"name":{"type":"string","description":"Character name (Starter+)"}},"required":["name"]},"EpisodeCreditResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Credit record ID (Starter+)"},"creator":{"description":"Creator details (Starter+)","allOf":[{"$ref":"#/components/schemas/EpisodeCreditCreatorDto"}]},"role":{"description":"Credit role (Starter+)","allOf":[{"$ref":"#/components/schemas/EpisodeCreditRoleDto"}]},"characters":{"description":"Characters voiced or played (Starter+)","type":"array","items":{"$ref":"#/components/schemas/EpisodeCreditCharacterDto"}}},"required":["creator","role"]},"PaginatedEpisodeCreditResponseDto":{"type":"object","properties":{"data":{"description":"Result set for the requested page","type":"array","items":{"$ref":"#/components/schemas/EpisodeCreditResponseDto"}},"pagination":{"description":"Pagination envelope metadata","allOf":[{"$ref":"#/components/schemas/PaginationMeta"}]}},"required":["data","pagination"]},"EpisodeBrandSafetyResponseDto":{"type":"object","properties":{"code":{"type":"string","description":"Brand safety category code (Professional)","enum":["adult","censor","criminal","disinfo","drugs","graphic","inflammatory","piracy","political","profanity","spam","terror","weapons"]},"description":{"type":"string","description":"Human-readable description of the category (Professional)"},"value":{"type":"number","description":"Risk score (0-1) (Professional)"},"level":{"type":"string","description":"Risk level (Professional)","enum":["clean","low","medium","high"]}},"required":["code","description","value","level"]},"EpisodeTranscriptDto":{"type":"object","properties":{"url":{"type":"string"},"source":{"type":"string"},"type":{"type":"string"},"generatedDate":{"type":"string","format":"date-time-utc-space","example":"2026-04-24 17:30:45"},"transcribedAudioUrl":{"type":"string"}},"required":["url","source","type"]},"EpisodeTranscriptResponseDto":{"type":"object","properties":{"transcripts":{"type":"array","items":{"$ref":"#/components/schemas/EpisodeTranscriptDto"}}},"required":["transcripts"]},"MentionDto":{"type":"object","properties":{"startTime":{"type":"string","description":"Segment start (HH:MM:SS[.mmm])"},"endTime":{"type":"string","description":"Segment end (HH:MM:SS[.mmm])"},"snippet":{"type":"string","description":"Matched transcript text"}}},"TranscriptSearchResultDto":{"type":"object","properties":{"mentionCount":{"type":"number","description":"Number of mentions of the search term in this episode"},"episode":{"$ref":"#/components/schemas/EpisodeResponseDto"},"mentions":{"type":"array","items":{"$ref":"#/components/schemas/MentionDto"}}},"required":["mentionCount","episode","mentions"]},"CreatorSocialLinksDto":{"type":"object","properties":{"twitter":{"type":"string","description":"Creator Twitter / X URL (Starter+)"},"wikipedia":{"type":"string","description":"Creator Wikipedia URL (Starter+)"}}},"CreatorResponseDto":{"type":"object","properties":{"pcid":{"type":"string","description":"Creator Podchaser ID (Starter+)"},"name":{"type":"string","description":"Creator display name (Starter+)"},"informalName":{"type":"string","description":"Informal or first name (Starter+)"},"pronouns":{"type":"string","enum":["they_them","she_her","he_him","unsure"],"description":"Creator pronouns (Starter+)"},"subtitle":{"type":"string","description":"Short subtitle or tagline (Starter+)"},"location":{"type":"string","description":"Location string (Starter+)"},"bio":{"type":"string","description":"Creator biography (Starter+)"},"url":{"type":"string","description":"Creator web URL (Starter+)"},"imageUrl":{"type":"string","description":"Creator profile image URL (Starter+)"},"birthday":{"type":"string","format":"date","description":"Date of birth (ISO 8601 calendar date, YYYY-MM-DD) (Starter+)"},"episodeAppearanceCount":{"type":"number","description":"Number of episode appearances (Starter+)"},"socialLinks":{"description":"Creator social links (Starter+)","allOf":[{"$ref":"#/components/schemas/CreatorSocialLinksDto"}]},"modifiedDate":{"type":"string","format":"date-time-utc-space","example":"2026-04-24 17:30:45","description":"Last-modified timestamp (Starter+)"}},"required":["pcid"]},"SponsorEstimatedAdSpendDto":{"type":"object","properties":{"low":{"type":"number","description":"Lower bound estimate, in dollars (Professional)"},"high":{"type":"number","description":"Upper bound estimate, in dollars (Professional)"}},"required":["low","high"]},"SponsorResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Sponsor (brand) numeric identifier — Podchaser's internal `Brand.id`. This is the same value the path param accepts (e.g. `13`). Stable for round-tripping back to `GET /sponsors/{id}`. (Professional)","example":"13"},"code":{"type":"string","description":"Sponsor (brand) lookup code — the human-readable string Podchaser uses internally for cross-referencing (e.g. `global.brand.shopify`). Returned for SDK convenience; the canonical path identifier is `id`. (Professional)","example":"global.brand.shopify"},"name":{"type":"string","description":"Brand name (Professional)"},"estimatedAdSpend":{"description":"Estimated total ad spend for the requested window (or all-time when `ads_from`/`ads_to` are omitted). (Professional)","allOf":[{"$ref":"#/components/schemas/SponsorEstimatedAdSpendDto"}]},"podcastsSponsored":{"type":"number","description":"Total number of podcasts this brand has sponsored (always all-time; the `ads_from`/`ads_to` window is not yet honoured by upstream for this count). (Professional)"},"episodesSponsored":{"type":"number","description":"Total number of episodes this brand has sponsored (always all-time; the `ads_from`/`ads_to` window is not honoured by upstream for this count either). (Professional)"}},"required":["id","code","name"]},"UsageResponseDto":{"type":"object","properties":{"tier":{"type":"string","description":"Current pricing tier","enum":["free","starter","professional"],"example":"starter"},"quota":{"type":"object","description":"Request limit for the tier. `null` for unlimited tiers (Enterprise shape, not yet shipped).","example":1000,"nullable":true},"used":{"type":"number","description":"In-cycle request count. Resets lazily on the first request after `cycle_end` — a fresh cycle reads `0` for callers that have not yet requested.","example":847},"remaining":{"type":"object","description":"Requests remaining in the current cycle before the quota is reached. `null` for unlimited tiers — callers MUST handle `null` without treating it as \"unknown\" or \"zero\".","example":153,"nullable":true},"cycle_start":{"type":"string","format":"date-time-utc-space","example":"2026-04-17 00:00:00","description":"Start of the current 30-day usage cycle (UTC, format `YYYY-MM-DD HH:MM:SS`, always midnight UTC). Anchored on the API key creation date and snapped to start-of-day. Inclusive lower bound. Per FR-16, the value is UTC; there is no timezone suffix on the wire — clients MUST NOT parse it as local time."},"cycle_end":{"type":"string","format":"date-time-utc-space","example":"2026-05-17 00:00:00","description":"End of the current 30-day usage cycle (UTC, format `YYYY-MM-DD HH:MM:SS`). Exclusive upper bound — a request at exactly this instant belongs to the NEXT cycle. The counter resets lazily on the first request after this moment. Per FR-16, the value is UTC; there is no timezone suffix on the wire."}},"required":["tier","quota","used","remaining","cycle_start","cycle_end"]},"CreditPodcastSummaryDto":{"type":"object","properties":{"id":{"type":"string","description":"Podcast Podchaser ID (Starter+)"},"title":{"type":"string","description":"Podcast title (Starter+)"},"imageUrl":{"type":"string","description":"Podcast cover image URL (Starter+)"}},"required":["id"]},"CreditEpisodeSummaryDto":{"type":"object","properties":{"id":{"type":"string","description":"Episode Podchaser ID (Starter+)"},"title":{"type":"string","description":"Episode title (Starter+)"},"airDate":{"type":"string","format":"date-time-utc-space","example":"2026-04-24 17:30:45","description":"Episode air date (Starter+)"}},"required":["id"]},"CreatorPodcastCreditResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Credit record ID (Starter+)"},"podcast":{"description":"Podcast summary (Starter+)","allOf":[{"$ref":"#/components/schemas/CreditPodcastSummaryDto"}]},"role":{"description":"Credit role (Starter+)","allOf":[{"$ref":"#/components/schemas/CreditRoleDto"}]},"episodeCount":{"type":"number","description":"Number of episodes with this credit (Starter+)"},"lastEpisode":{"description":"Most recent episode with this credit (Starter+)","allOf":[{"$ref":"#/components/schemas/CreditEpisodeSummaryDto"}]}},"required":["podcast","role","episodeCount"]},"PaginatedCreatorPodcastCreditResponseDto":{"type":"object","properties":{"data":{"description":"Result set for the requested page","type":"array","items":{"$ref":"#/components/schemas/CreatorPodcastCreditResponseDto"}},"pagination":{"description":"Pagination envelope metadata","allOf":[{"$ref":"#/components/schemas/PaginationMeta"}]}},"required":["data","pagination"]},"CreditCharacterDto":{"type":"object","properties":{"name":{"type":"string","description":"Character name (Starter+)"}},"required":["name"]},"CreatorEpisodeCreditResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Credit record ID (Starter+)"},"episode":{"description":"Episode summary (Starter+)","allOf":[{"$ref":"#/components/schemas/CreditEpisodeSummaryDto"}]},"podcast":{"description":"Podcast summary (Starter+)","allOf":[{"$ref":"#/components/schemas/CreditPodcastSummaryDto"}]},"role":{"description":"Credit role (Starter+)","allOf":[{"$ref":"#/components/schemas/CreditRoleDto"}]},"characters":{"description":"Characters voiced or played (Starter+)","type":"array","items":{"$ref":"#/components/schemas/CreditCharacterDto"}}},"required":["episode","podcast","role"]},"PaginatedCreatorEpisodeCreditResponseDto":{"type":"object","properties":{"data":{"description":"Result set for the requested page","type":"array","items":{"$ref":"#/components/schemas/CreatorEpisodeCreditResponseDto"}},"pagination":{"description":"Pagination envelope metadata","allOf":[{"$ref":"#/components/schemas/PaginationMeta"}]}},"required":["data","pagination"]},"SponsorPodcastInnerDto":{"type":"object","properties":{"id":{"type":"string","description":"Podcast Podchaser ID (Professional)","example":"1576373"},"title":{"type":"string","description":"Podcast title (Professional)","example":"Huberman Lab"},"imageUrl":{"type":"string","description":"Podcast cover art URL (Professional)","example":"https://example.podchaser.com/podcast/1576373/cover.jpg"},"description":{"type":"string","description":"Plain-text description of the podcast as published in the RSS feed. (Professional)","example":"The Huberman Lab Podcast discusses neuroscience and science-based tools for everyday life."},"numberOfEpisodes":{"type":"number","description":"Total number of episodes the podcast has published. (Professional)","example":412},"powerScore":{"type":"number","description":"Podchaser Power Score (popularity / influence). May be null when we don't have enough data yet for the podcast. (Professional)","example":92},"audienceEstimate":{"type":"number","description":"Estimated monthly listens for the podcast's RSS feed. May be null when we don't have enough data yet for the podcast. (Professional)","example":1250000},"totalAudienceEstimate":{"type":"number","description":"Total estimated monthly listens including YouTube. Falls back to `audienceEstimate` when only RSS reach is available. May be null when we do not have enough data yet for the podcast. (Professional)","example":1875000},"hostingProvider":{"type":"string","description":"The hosting provider of the podcast, detected from the RSS feed (e.g. `Acast`, `Buzzsprout`, `Libsyn`, `Omny Studio`). May be null when a known provider has not been detected. (Professional)","example":"Acast"}},"required":["id","title"]},"SponsorPodcastResponseDto":{"type":"object","properties":{"podcast":{"description":"The sponsored podcast (Professional)","allOf":[{"$ref":"#/components/schemas/SponsorPodcastInnerDto"}]},"episodeCount":{"type":"number","description":"Number of sponsored episodes on this podcast (Professional)","example":17},"latestSponsoredEpisodeDate":{"type":"string","description":"Air date of the most recent episode of this podcast that featured a placement for this brand. Sponsorship-scoped — distinct from show-level latest-episode (`Podcast.latestEpisodeDate`), which would conflate \"the show released a new episode\" with \"the brand placed a new ad\". Wire format `YYYY-MM-DD HH:MM:SS` UTC (FR-16). May be null when upstream has no recorded sponsored episode date for this row. (Professional)","example":"2025-04-12 18:00:00"}},"required":["podcast","episodeCount"]},"PaginatedSponsorPodcastResponseDto":{"type":"object","properties":{"data":{"description":"Result set for the requested page","type":"array","items":{"$ref":"#/components/schemas/SponsorPodcastResponseDto"}},"pagination":{"description":"Pagination envelope metadata","allOf":[{"$ref":"#/components/schemas/PaginationMeta"}]}},"required":["data","pagination"]},"SponsorEpisodeAudienceRangeDto":{"type":"object","properties":{"from":{"type":"number","description":"Lower bound of the audience-estimate range (Professional)","example":1500000},"to":{"type":"number","description":"Upper bound of the audience-estimate range (Professional)","example":2250000}},"required":["from","to"]},"SponsorEpisodeInnerDto":{"type":"object","properties":{"id":{"type":"string","description":"Episode Podchaser ID (Professional)","example":"ep-1576373-001"},"title":{"type":"string","description":"Episode title (Professional)","example":"How to Build Resilience"},"airDate":{"type":"string","description":"Episode publication date as `YYYY-MM-DD HH:MM:SS` UTC (FR-16 wire format). (Professional)","example":"2025-03-15 09:00:00"},"description":{"type":"string","description":"Plain-text description of the episode as published in the RSS feed. (Professional)","example":"In this episode we discuss strategies for building resilience under stress."},"url":{"type":"string","description":"Podchaser URL for the episode. (Professional)","example":"https://www.podchaser.com/podcasts/huberman-lab-1576373/episodes/ep-1576373-001"},"totalAudienceEstimate":{"type":"number","description":"Total estimated number of listeners for this episode (including YouTube). Falls back to RSS-only audience reach when only that signal is available. May be null when we do not have enough data yet for the episode. (Professional)","example":925000},"totalAudienceEstimateRange":{"description":"Total estimated audience range for this episode (including YouTube). May be null when we do not have enough data yet for the episode. (Professional)","allOf":[{"$ref":"#/components/schemas/SponsorEpisodeAudienceRangeDto"}]}},"required":["id","title"]},"SponsorEpisodePodcastDto":{"type":"object","properties":{"id":{"type":"string","description":"Podcast Podchaser ID (Professional)","example":"1576373"},"title":{"type":"string","description":"Podcast title (Professional)","example":"Huberman Lab"},"powerScore":{"type":"number","description":"Podchaser Power Score (popularity / influence). May be null when we don't have enough data yet for the podcast. (Professional)","example":92},"totalAudienceEstimate":{"type":"number","description":"Total estimated monthly listens including YouTube. Falls back to RSS-only audience reach when only that signal is available. May be null when we do not have enough data yet for the podcast. (Professional)","example":1875000},"totalAudienceEstimateRange":{"description":"Total estimated monthly audience range for the podcast (including YouTube). May be null when we do not have enough data yet for the podcast. (Professional)","allOf":[{"$ref":"#/components/schemas/SponsorEpisodeAudienceRangeDto"}]},"webUrl":{"type":"string","description":"Publisher's homepage URL for the podcast as specified in the RSS feed. (Professional)","example":"https://hubermanlab.com"}},"required":["id","title"]},"SponsorEpisodeResponseDto":{"type":"object","properties":{"episode":{"description":"The sponsored episode (Professional)","allOf":[{"$ref":"#/components/schemas/SponsorEpisodeInnerDto"}]},"podcast":{"description":"The podcast that hosts the sponsored episode (Professional)","allOf":[{"$ref":"#/components/schemas/SponsorEpisodePodcastDto"}]},"startTime":{"type":"number","description":"Ad start time in seconds from start of episode (Professional)","example":12.5},"endTime":{"type":"number","description":"Ad end time in seconds from start of episode (Professional)","example":47.25},"estimatedAdSpend":{"description":"Estimated spend range for this single placement (Professional)","allOf":[{"$ref":"#/components/schemas/EstimatedAdSpendDto"}]}},"required":["episode","podcast"]},"PaginatedSponsorEpisodeResponseDto":{"type":"object","properties":{"data":{"description":"Result set for the requested page","type":"array","items":{"$ref":"#/components/schemas/SponsorEpisodeResponseDto"}},"pagination":{"description":"Pagination envelope metadata","allOf":[{"$ref":"#/components/schemas/PaginationMeta"}]}},"required":["data","pagination"]},"CategoryResponseDto":{"type":"object","properties":{"title":{"type":"string","description":"Category name.","example":"Technology"},"slug":{"type":"string","description":"Category identifier slug.","example":"technology"},"podcastCount":{"type":"number","description":"Number of podcasts in the category.","example":1234}},"required":["title","slug"]},"PaginatedCategoryResponseDto":{"type":"object","properties":{"data":{"description":"Result set for the requested page","type":"array","items":{"$ref":"#/components/schemas/CategoryResponseDto"}},"pagination":{"description":"Pagination envelope metadata","allOf":[{"$ref":"#/components/schemas/PaginationMeta"}]}},"required":["data","pagination"]},"ReferenceLanguageDto":{"type":"object","properties":{"code":{"type":"string","description":"Language code as it appears on `Podcast.language`. Typically an ISO 639-1 two-letter code (e.g. `en`, `es`); the catalogue also includes the long-tail of non-ISO codes that show up in the wild.","example":"en"},"name":{"type":"string","description":"Display name for the language.","example":"English"}},"required":["code","name"]},"KeyLabelDto":{"type":"object","properties":{"key":{"type":"string","description":"Machine-readable key.","example":"income-tier-0"},"label":{"type":"string","description":"Human-readable label.","example":"$"}},"required":["key","label"]},"DemographicsResponseDto":{"type":"object","properties":{"age_ranges":{"description":"Available age-range keys with display labels.","type":"array","items":{"$ref":"#/components/schemas/KeyLabelDto"}},"income_tiers":{"description":"Valid income-tier keys (`income-tier-0` … `income-tier-4`) with display labels.","type":"array","items":{"$ref":"#/components/schemas/KeyLabelDto"}},"gender_biases":{"description":"Valid gender-bias keys with display labels.","type":"array","items":{"$ref":"#/components/schemas/KeyLabelDto"}},"parental_statuses":{"description":"Valid parental-status keys with display labels.","type":"array","items":{"$ref":"#/components/schemas/KeyLabelDto"}},"political_skews":{"description":"Valid political-skew keys with display labels.","type":"array","items":{"$ref":"#/components/schemas/KeyLabelDto"}},"ethnicities":{"description":"Valid ethnicity keys with display labels.","type":"array","items":{"$ref":"#/components/schemas/KeyLabelDto"}},"education_levels":{"description":"Valid education-level keys with display labels.","type":"array","items":{"$ref":"#/components/schemas/KeyLabelDto"}},"marital_statuses":{"description":"Valid marital-status keys with display labels.","type":"array","items":{"$ref":"#/components/schemas/KeyLabelDto"}}},"required":["age_ranges","income_tiers","gender_biases","parental_statuses","political_skews","ethnicities","education_levels","marital_statuses"]},"ReferenceChartCategoryItemDto":{"type":"object","properties":{"title":{"type":"string","description":"Chart category display title.","example":"Technology"},"slug":{"type":"string","description":"Chart category slug.","example":"technology"},"platform":{"type":"string","description":"Chart platform this category belongs to (`apple_podcasts` or `spotify`).","example":"apple_podcasts"}},"required":["title","slug","platform"]},"ReferenceChartsResponseDto":{"type":"object","properties":{"platforms":{"description":"Chart platforms reflected by the response. When the `platform` query param is provided this contains only that platform; when omitted it lists every supported platform.","example":["apple_podcasts","spotify"],"type":"array","items":{"type":"string"}},"categories":{"description":"Chart categories for the requested platform, or for every supported platform when the `platform` query param is omitted. Each row carries `{ title, slug, platform }`.","type":"array","items":{"$ref":"#/components/schemas/ReferenceChartCategoryItemDto"}}},"required":["platforms","categories"]},"ReferenceBrandSafetyCodeDto":{"type":"object","properties":{"code":{"type":"string","description":"Risk category code.","example":"drugs"},"description":{"type":"string","description":"Human-readable description of the risk category.","example":"Illegal Substances & Misuse"},"levels":{"description":"Possible risk levels for this category.","example":["clean","low","medium","high"],"type":"array","items":{"type":"string"}}},"required":["code","description","levels"]},"HostingProviderResponseDto":{"type":"object","properties":{"name":{"type":"string","description":"Display name of the hosting provider (e.g. \"Acast\", \"Libsyn\").","example":"Acast"},"podcastCount":{"type":"number","description":"Number of podcasts associated with this hosting provider.","example":4200}},"required":["name","podcastCount"]},"InsightBucketDto":{"type":"object","properties":{"title":{"type":"string"},"count":{"type":"number"}},"required":["title","count"]},"AudienceEstimateDto":{"type":"object","properties":{"from":{"type":"number"},"to":{"type":"number"}}},"NetworkInsightsResponseDto":{"type":"object","properties":{"categories":{"description":"Podcast category distribution (Starter+)","type":"array","items":{"$ref":"#/components/schemas/InsightBucketDto"}},"status":{"description":"Podcast status distribution (Starter+)","type":"array","items":{"$ref":"#/components/schemas/InsightBucketDto"}},"powerScore":{"description":"Power Score distribution (Starter+)","type":"array","items":{"$ref":"#/components/schemas/InsightBucketDto"}},"audienceEstimate":{"description":"Aggregate audience estimate range (Starter+)","allOf":[{"$ref":"#/components/schemas/AudienceEstimateDto"}]},"medianAge":{"description":"Median age distribution (Starter+)","type":"array","items":{"$ref":"#/components/schemas/InsightBucketDto"}},"genderBias":{"description":"Gender bias distribution (Starter+)","type":"array","items":{"$ref":"#/components/schemas/InsightBucketDto"}},"incomeTier":{"description":"Income tier distribution (Starter+)","type":"array","items":{"$ref":"#/components/schemas/InsightBucketDto"}},"parentalStatus":{"description":"Parental status distribution (Starter+)","type":"array","items":{"$ref":"#/components/schemas/InsightBucketDto"}},"countries":{"description":"Top listener countries (Starter+)","type":"array","items":{"$ref":"#/components/schemas/InsightBucketDto"}},"interests":{"description":"Top listener interests (Starter+)","type":"array","items":{"$ref":"#/components/schemas/InsightBucketDto"}}}},"GlobalChartPodcastSummaryDto":{"type":"object","properties":{"id":{"type":"string","description":"Podcast Podchaser ID (Professional)"},"title":{"type":"string","description":"Podcast title (Professional)"},"rssUrl":{"type":"string","description":"Podcast RSS feed URL (Professional)"},"applePodcastsId":{"type":"string","description":"Apple Podcasts ID (Professional)"},"spotifyId":{"type":"string","description":"Spotify podcast ID (Professional)"},"imageUrl":{"type":"string","description":"Podcast cover image URL (Professional)"}},"required":["id","title"]},"GlobalChartResponseDto":{"type":"object","properties":{"position":{"type":"number","description":"Chart position (Professional)"},"change":{"type":"number","description":"Position change from previous day (Professional)"},"changeStatus":{"type":"string","enum":["no_change","new","up","down"],"description":"Direction of position change (Professional)"},"platform":{"type":"string","enum":["apple_podcasts","spotify"],"description":"Chart platform (Professional)"},"country":{"type":"string","description":"Country code (Professional)"},"category":{"type":"string","description":"Category slug (Professional)"},"day":{"type":"string","description":"Chart date (YYYY-MM-DD, UTC) (Professional)"},"podcast":{"description":"Podcast summary (Professional)","allOf":[{"$ref":"#/components/schemas/GlobalChartPodcastSummaryDto"}]}},"required":["position","platform","day","podcast"]},"PaginatedGlobalChartResponseDto":{"type":"object","properties":{"data":{"description":"Chart rows for the resolved as-of date (may be empty).","type":"array","items":{"$ref":"#/components/schemas/GlobalChartResponseDto"}},"pagination":{"description":"Pagination envelope metadata.","allOf":[{"$ref":"#/components/schemas/PaginationMeta"}]},"as_of_date":{"type":"string","nullable":true,"example":"2026-04-21","description":"Anchor date ('YYYY-MM-DD', UTC) the response is scoped to. Resolved to the most recent day a chart is available in Podchaser's system for the requested (platform, country, category); `null` when no chart was available in the recent window."}},"required":["data","pagination","as_of_date"]}}},"security":[{"apiKey":[]}],"x-tagGroups":[{"name":"Getting Started","tags":["Quickstart","MCP"]},{"name":"Data","tags":["Search","Podcasts","Episodes","Creators","Networks","Sponsors","Charts"]},{"name":"Utilities","tags":["Reference","Usage","System","Conventions"]}]}