curl --request GET \
--url https://k8mfogcvz4.execute-api.us-east-1.amazonaws.com/prod/v1/charts \
--header 'Authorization: Bearer <token>'import requests
url = "https://k8mfogcvz4.execute-api.us-east-1.amazonaws.com/prod/v1/charts"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://k8mfogcvz4.execute-api.us-east-1.amazonaws.com/prod/v1/charts', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://k8mfogcvz4.execute-api.us-east-1.amazonaws.com/prod/v1/charts",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://k8mfogcvz4.execute-api.us-east-1.amazonaws.com/prod/v1/charts"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://k8mfogcvz4.execute-api.us-east-1.amazonaws.com/prod/v1/charts")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://k8mfogcvz4.execute-api.us-east-1.amazonaws.com/prod/v1/charts")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"category": "Business",
"language": "en",
"size": {
"requested": 40,
"allowed": 10,
"limit": 10,
"clamped": true
},
"data": [
{
"show_id": "sh_k4n7qzvw2mtxyabc",
"title": "The Vergecast",
"feed_url": "https://feeds.example.com/vergecast.xml",
"itunes_id": 430333725,
"author": "The Verge",
"categories": [
"Technology",
"Business"
],
"artwork_url": "https://cdn.example.com/art/vergecast.jpg",
"music_led": false,
"music_led_basis": "no music category is on the show"
}
],
"excluded": []
}{
"error": {
"code": "invalid_request",
"type": "invalid_request",
"message": "<string>",
"doc_url": "<string>",
"request_id": "<string>",
"retryable": true
}
}{
"error": {
"code": "invalid_request",
"type": "invalid_request",
"message": "<string>",
"doc_url": "<string>",
"request_id": "<string>",
"retryable": true
}
}{
"error": {
"code": "invalid_request",
"type": "invalid_request",
"message": "<string>",
"doc_url": "<string>",
"request_id": "<string>",
"retryable": true
}
}{
"error": {
"code": "invalid_request",
"type": "invalid_request",
"message": "<string>",
"doc_url": "<string>",
"request_id": "<string>",
"retryable": true
}
}{
"error": {
"code": "invalid_request",
"type": "invalid_request",
"message": "<string>",
"doc_url": "<string>",
"request_id": "<string>",
"retryable": true
}
}A category chart of a chosen size, capped by tier
The provider’s chart for one category, of the size the caller asks for, clamped to the account tier’s chart cap. The clamp is applied before the provider is called and is always reported in size, whether or not it bit: requested is what the caller asked for, allowed is what the tier permitted, limit is the tier’s ceiling. Entries are marked music_led but not removed — a chart is only a list until POST /v1/quotes turns it into a selection, and that is where the music boundary applies by default.
curl --request GET \
--url https://k8mfogcvz4.execute-api.us-east-1.amazonaws.com/prod/v1/charts \
--header 'Authorization: Bearer <token>'import requests
url = "https://k8mfogcvz4.execute-api.us-east-1.amazonaws.com/prod/v1/charts"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://k8mfogcvz4.execute-api.us-east-1.amazonaws.com/prod/v1/charts', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://k8mfogcvz4.execute-api.us-east-1.amazonaws.com/prod/v1/charts",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://k8mfogcvz4.execute-api.us-east-1.amazonaws.com/prod/v1/charts"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://k8mfogcvz4.execute-api.us-east-1.amazonaws.com/prod/v1/charts")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://k8mfogcvz4.execute-api.us-east-1.amazonaws.com/prod/v1/charts")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"category": "Business",
"language": "en",
"size": {
"requested": 40,
"allowed": 10,
"limit": 10,
"clamped": true
},
"data": [
{
"show_id": "sh_k4n7qzvw2mtxyabc",
"title": "The Vergecast",
"feed_url": "https://feeds.example.com/vergecast.xml",
"itunes_id": 430333725,
"author": "The Verge",
"categories": [
"Technology",
"Business"
],
"artwork_url": "https://cdn.example.com/art/vergecast.jpg",
"music_led": false,
"music_led_basis": "no music category is on the show"
}
],
"excluded": []
}{
"error": {
"code": "invalid_request",
"type": "invalid_request",
"message": "<string>",
"doc_url": "<string>",
"request_id": "<string>",
"retryable": true
}
}{
"error": {
"code": "invalid_request",
"type": "invalid_request",
"message": "<string>",
"doc_url": "<string>",
"request_id": "<string>",
"retryable": true
}
}{
"error": {
"code": "invalid_request",
"type": "invalid_request",
"message": "<string>",
"doc_url": "<string>",
"request_id": "<string>",
"retryable": true
}
}{
"error": {
"code": "invalid_request",
"type": "invalid_request",
"message": "<string>",
"doc_url": "<string>",
"request_id": "<string>",
"retryable": true
}
}{
"error": {
"code": "invalid_request",
"type": "invalid_request",
"message": "<string>",
"doc_url": "<string>",
"request_id": "<string>",
"retryable": true
}
}Authorizations
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
A provider category name, e.g. Business or Society & Culture; filtered server-side.
1 - 100How 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.
1 <= x <= 100Restrict 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).
35^[A-Za-z]{2,3}(-[A-Za-z0-9]{1,8})*$Response
The chart, in provider order, with the size clamp reported.
1 - 100A BCP-47 language tag (general syntax check, not full IANA subtag validation).
35^[A-Za-z]{2,3}(-[A-Za-z0-9]{1,8})*$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.
Show child attributes
Show child attributes
The chart, in provider order, at most size.allowed long.
100Show child attributes
Show child attributes
100Show child attributes
Show child attributes

