Skip to main content
GET
A category chart of a chosen size, capped by tier

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

category
string
required

A provider category name, e.g. Business or Society & Culture; filtered server-side.

Required string length: 1 - 100
size
integer
default:10

How many shows the caller wants. Clamped to the account tier's chart cap, never rejected for exceeding it; the response's size says what was asked and what was allowed.

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

Restrict the chart to shows in one language, as a BCP-47 tag. A BCP-47 language tag (general syntax check, not full IANA subtag validation).

Maximum string length: 35
Pattern: ^[A-Za-z]{2,3}(-[A-Za-z0-9]{1,8})*$

Response

The chart, in provider order, with the size clamp reported.

category
string
required
Required string length: 1 - 100
language
required

A BCP-47 language tag (general syntax check, not full IANA subtag validation).

Maximum string length: 35
Pattern: ^[A-Za-z]{2,3}(-[A-Za-z0-9]{1,8})*$
size
object
required

One number after the caller's tier had its say. requested is what was asked for, allowed what the tier permitted, limit the ceiling that produced it — reported whether or not the ceiling bit, because "your 40-show chart became 10" is the sentence a caller can act on and "10 shows" alone is not.

data
object[]
required

The chart, in provider order, at most size.allowed long.

Maximum array length: 100
excluded
object[]
required
Maximum array length: 100