Every request carries your key in the Authorization header. The x-api-key header works too.

Authorization: Bearer nvk_your_key

Create a developer account with your email; no subscription needed. Your first key is created for you, and more can be made on the Data API page of your account. A key is shown once at creation and only its hash is stored, so copy it straight away. A new key is a sandbox key: 25 credits every week, 10 requests per minute, up to 20 results per search page and 3 pages per query. Buying any credit bundle turns it into a standard key.

Search for shows about B2B SaaS founders and read one result in full.

curl "https://novacast.ai/api/v1/podcasts/search?q=b2b+saas+founders&pageSize=3" \
  -H "Authorization: Bearer nvk_your_key"

curl "https://novacast.ai/api/v1/podcasts/<uuid from the first response>?episodes=5" \
  -H "Authorization: Bearer nvk_your_key"

The first call returns a list of podcasts under data and paging information under meta. For the second call, copy the uuid of any podcast in the first response's data array into the URL; it returns that podcast with its latest episodes.

GET https://novacast.ai/api/v1/podcasts/search

Each result carries the catalogue fields (uuid, name, description, imageUrl, authorName, language, genres, websiteUrl, itunesId, datePublished; itunesId is present where the catalogue has it and null otherwise), the audience estimate (listenersLow, listenersHigh), the quality score (pciScore, 0 to 100) and the listener rating (userRatingValue, userRatingCount, null when the show has none) and hosts, the hosts who claimed the show on Novacast (hostName, username, avatarUrl; empty when nobody has claimed it). Host contact details are never returned.

{
  "data": [ { "uuid": "…", "name": "…", "pciScore": 71.3, "listenersLow": 4200, "listenersHigh": 6100, … } ],
  "meta": { "total": 1284, "page": 1, "pageSize": 10, "sort": "relevance", "mode": "semantic", "language": null, "isLastPage": false, "requestMs": 412 }
}

GET https://novacast.ai/api/v1/podcasts/{uuid}?episodes=10

Returns one podcast under data with the same fields as search plus the evaluation details behind the quality score and the latest episodes. 404 when the uuid is unknown.

GET https://novacast.ai/api/v1/podcasts/{uuid}/episodes?page=1&pageSize=20

Newest first. Each episode has uuid, name, description, datePublished, imageUrl, audioUrl, duration, episodeNumber and seasonNumber. meta.isLastPage tells you when to stop paging.

GET https://novacast.ai/api/v1/podcasts/{uuid}/similar?limit=4

Shows closest to the given one, each with a similarity value (cosine similarity, highest first). The list is empty for shows that have no similarity embedding yet, which is about half the catalogue.

Three brakes apply per key, and every response reports where you stand.

The sandbox allowance resets every Monday at 00:00 UTC and does not carry over. Purchased credits never expire. A request the API rejects as invalid (400) is refunded: it gives back the daily unit and the credit. It still counts toward the per-minute limit. Rate-limited requests are not served and spend nothing.

The per-minute limit is a 60 second sliding window, not a calendar minute. When it is exceeded the API answers 429 with the message "Per-minute rate limit exceeded" and a fixed Retry-After: 60; the daily and credit headers come with it so you can see where you stand.

The simplest way is the Data API page in your account: pick a key, pick a bundle, pay with Stripe. The same is available from code; both calls are free and never spend credits.

GET  https://novacast.ai/api/v1/billing/bundles
POST https://novacast.ai/api/v1/billing/checkout?bundle=api_credits_starter

The checkout call returns a Stripe Checkout url. Open it in a browser; the credits land on the key when the payment completes, and a sandbox key becomes a standard key on its first purchase.

On that first purchase the remaining sandbox allowance is replaced by the purchased credits, not added to them: a sandbox key with 25 credits left that buys a 5,000 credit bundle has 5,000 credits.

Errors are JSON with an error message; validation errors add details.fieldErrors naming the parameter.

The interactive reference, generated from the OpenAPI document, lets you try every endpoint with your own key: /api/v1/docs. The OpenAPI JSON itself is at /api/v1/openapi, for code generators and API clients.