Skip to main content
GET
Episode metadata for a show

Authorizations

Authorization
string
header
required

Authorization: Bearer hk_live_... for live keys or Authorization: Bearer hk_test_... for test-mode keys. hk_test_ keys resolve real public catalog metadata but return deterministic committed fixtures, never call inference, and never mutate live credits. This is the only transport for the credential: the x-api-key alias once documented was removed in 0.2.0, because the edge authorizer reads Authorization as its single identity source and a request on any other header is refused before it is authenticated.

Never accepted on a dashboardJwt operation, and there are no exceptions. GET /v1/usage and GET /v1/limits briefly declared both schemes (0.8.0); that was withdrawn in 0.8.1 because no deployed route could honor it — both operations are served by the control-plane API, whose authorizer verifies a Cognito token and refuses an hk_live_ credential on shape, and the customer API does not route either path. An API-key holder reads its balance and reservation from QuoteResponse, which carries balance_credits and reserved_credits on every quote. Every operation in this document takes one scheme or the other and refuses the wrong one as unauthenticated.

Path Parameters

show_id
string
required

Canonical show identifier.

Pattern: ^sh_[a-z2-7]{16}$

Query Parameters

feed_url
string<uri>
required

The show's feed URL, as GET /v1/search/shows and GET /v1/charts return it. Required because a show_id is a one-way derivation and cannot be resolved back to a feed: the id names the show, and this names where to read it. The two must agree — the handler re-derives the id from feed_url and itunes_id and refuses the request when it does not match the path, so the id in the URL stays a canonical identifier rather than decoration, and a caller cannot point one show's id at another show's feed. An RSS/Atom feed URL.

Required string length: 1 - 2048
itunes_id
integer

The show's Apple collection id when the discovery surface returned one. It changes how show_id derives, so a show that has one must send it or the re-derivation above will not match.

Required range: x >= 1
limit
integer
default:20

Maximum number of items to return.

Required range: 1 <= x <= 100
cursor
string

Opaque pagination cursor from a previous page's next_cursor. An opaque pagination cursor. Callers must treat it as opaque.

Pattern: ^[A-Za-z0-9_-]{1,512}$

Response

A page of episodes for the show.

data
object[]
required
Maximum array length: 100
next_cursor
required

An opaque pagination cursor, or null when there is no next page.

Pattern: ^[A-Za-z0-9_-]{1,512}$