Skip to main content
POST

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.

Body

application/json
​
shows
object[]
required
Required array length: 1 - 100 elements
​
episodes_per_show
integer
default:1

The N in "the newest N episodes per show". Ignored for a show whose episode_ids name its episodes. Clamped to the plan's whole selection total when it exceeds it, and reported.

Required range: 1 <= x <= 100
​
include_music_led
boolean

The music-led switch. Named shows are taken as chosen, so it changes nothing here; it is accepted so one client can send one body shape for both sources.

Response

The recorded quote — priced entries, exclusions, clamps, totals, and headroom.

The recorded quote. total_ceiling_credits is the sum of the entries' ceilings and cached_members the count of entries with is_cached: true — both derived by the store at write time, never taken from a caller. The quote is valid until expires_at; a confirm after that is refused.

balance_credits and reserved_credits are the caller's account as it stood when the quote was priced, read off the same row remaining_open_jobs was counted from — so an agent can see what it holds at the moment it decides to spend without a second call. Like the headroom beside them they are reported, never enforced: a quote reserves nothing, so a balance below total_ceiling_credits is a fact to act on rather than a refusal, and affordability is decided by the confirm.

​
quote_id
string
required

Opaque, server-generated quote identifier.

Maximum string length: 40
Pattern: ^qte_[A-Za-z0-9]{16,32}$
​
source
enum<string>
required

Which request shape produced this quote.

Available options:
shows,
chart,
uploads
​
episodes_per_show
integer
required

The N after the tier had its say.

Required range: x >= 1
​
entries
object[]
required
Required array length: 1 - 100 elements
​
excluded
object[]
required
​
clamps
object[]
required
Maximum array length: 3
​
cached_members
integer
required
Required range: x >= 0
​
uncached_members
integer
required
Required range: x >= 0
​
total_ceiling_credits
integer
required

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
​
remaining_open_jobs
integer
required

How many more jobs the caller's tier lets them have open — reserved and not yet terminal — right now, so a selection can be sized before it is confirmed. Reported here, enforced at confirm.

Required range: x >= 0
​
balance_credits
integer
required

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
​
reserved_credits
integer
required

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
​
expires_at
string<date-time>
required
​
created_at
string<date-time>
required