Skip to main content
GET
Resolve a podcast pointer to canonical IDs without creating a job

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.

Query Parameters

url
string<uri>

An Apple Podcasts episode URL.

Required string length: 1 - 2048
feed_url
string<uri>

An RSS feed URL. Requires guid. Mutually exclusive with url. An RSS/Atom feed URL.

Required string length: 1 - 2048
guid
string

An episode GUID from the feed named by feed_url. An episode GUID as published in the feed's <guid> element. Used verbatim — GUIDs are case- and whitespace-significant.

Required string length: 1 - 512

Response

Resolved canonical identity plus cache/quote hints.

Resolves a pointer to canonical IDs without creating a job.

episode_id
string
required

Canonical episode identifier.

Pattern: ^ep_[a-z2-7]{16}$
show_id
string
required

Canonical show identifier.

Pattern: ^sh_[a-z2-7]{16}$
is_cached
boolean
required
estimated_credits

A non-negative JavaScript-safe integer credit amount. The upper bound matches Number.MAX_SAFE_INTEGER, which is enforced by the domain ledger so arithmetic and JSON round-trips cannot silently lose cents worth of credit precision.

Required range: 0 <= x <= 9007199254740991
quote_basis

feed_metadata when the estimate is derived from feed-published duration; probed when a bounded enclosure probe measured it.

Available options:
feed_metadata,
probed
estimated_seconds

Estimated wall-clock processing seconds, or null when the pointer resolved but nothing has been estimated yet (e.g. the episode is already cached, so no fresh work would be scheduled).

Required range: 0 <= x <= 72000