Everything you need to search the Novacast podcast catalogue from your own code. The base URL is https://novacast.ai/api/v1. Responses are JSON.
The playground runs every endpoint in your browser: press Authorize, paste your key, then Try it out.
Every request carries your key in the Authorization header. The x-api-key header works too.
Authorization: Bearer nvk_your_keyCreate 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| Parameter | Values | Notes |
|---|---|---|
q | text, 1 to 200 characters | Required. A topic, a show name or a host name. |
page | 1 to 20 (sandbox keys: 3) | Default 1. At most 1,000 results per query. |
pageSize | 1 to 50 (sandbox keys: 20) | Default 10. |
language | a language name, e.g. english, german | Optional. Any case. |
sort | relevance, new, recent-publication, pci, rating | Default relevance. pci is the quality score, rating the listener rating. The other sorts order the 50 most relevant matches, so the results stay on topic; meta.total still counts every match. |
mode | hybrid (default), semantic | Relevance engine. The default, hybrid, combines vector (meaning), keyword and title matching, so it also finds shows by name. semantic is the vector match alone. With another sort it picks the relevant matches that sort orders. |
Each result carries the catalogue fields (uuid, name, description, imageUrl, authorName, language, genres, websiteUrl, itunesId, datePublished, and novacastUrl, the show's public page on Novacast; 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). Search never returns host contact details; see Host contacts.
{
"data": [ { "uuid": "…", "name": "…", "pciScore": 71.3, "listenersLow": 4200, "listenersHigh": 6100, … } ],
"meta": { "total": 1284, "page": 1, "pageSize": 10, "sort": "relevance", "mode": "hybrid", "language": null, "isLastPage": false, "requestMs": 412 }
}GET https://novacast.ai/api/v1/podcasts/{uuid}?episodes=10| Parameter | Values | Notes |
|---|---|---|
episodes | 0 to 100 | Default 10. Latest episodes to include; 0 leaves them out. |
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| Parameter | Values | Notes |
|---|---|---|
page | 1 to 50 | Default 1. |
pageSize | 1 to 100 | Default 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| Parameter | Values | Notes |
|---|---|---|
limit | 1 to 20 | Default 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.
POST https://novacast.ai/api/v1/podcasts/{uuid}/contactReturns the host email of one podcast: email, emailStatus (the verification result, for example VERIFIED or CATCH_ALL), ownerName from the feed, unlockedAt and alreadyUnlocked. Standard keys only; a sandbox key gets 403.
The first unlock of a podcast costs 160 credits (meta.creditsCharged). Calling it again for the same podcast is free and returns alreadyUnlocked: true. We check the mailbox the first time a podcast is unlocked, so that call can take up to a minute, and we only sell an address that passes (VERIFIED, or CATCH_ALL when the domain accepts every address). A podcast with no deliverable email returns 404 and costs nothing. If the check is still running you get 503 with a Retry-After header: call again, nothing was charged. Each key can unlock 100 podcasts a day (resets 00:00 UTC) and 2,500 in total; past either limit the API answers 429. Unlocks do not count toward the daily request quota.
The API is also available as a Model Context Protocol (MCP) server, so AI assistants and agents can search the catalogue for you. It offers four tools: search_podcasts, get_podcast, list_podcast_episodes and get_similar_podcasts. They work like the endpoints above: each tool call uses your key, spends one credit and follows the same limits, and every result includes creditsRemaining.
https://novacast.ai/api/mcpClaude Code:
claude mcp add --transport http novacast https://novacast.ai/api/mcp \
--header "Authorization: Bearer nvk_your_key"Cursor and other clients that accept a remote server with headers (for example ~/.cursor/mcp.json):
{
"mcpServers": {
"novacast": {
"url": "https://novacast.ai/api/mcp",
"headers": { "Authorization": "Bearer nvk_your_key" }
}
}
}Claude Desktop, through the mcp-remote bridge (Node.js required), in claude_desktop_config.json:
{
"mcpServers": {
"novacast": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://novacast.ai/api/mcp",
"--header", "Authorization: Bearer nvk_your_key"]
}
}
}Then ask in plain words, for example: "Find B2B SaaS podcasts with at least 5,000 listeners and show their quality scores". If a key runs out of credits, the assistant gets the error with a link to buy more.
Three brakes apply per key, and every response reports where you stand.
| Parameter | Values | Notes |
|---|---|---|
Credits | sandbox: 25 every week; standard: purchased bundles | One credit per served request. X-Credits-Remaining on every response, X-Credits-Reset when an allowance applies. At zero: 429 with a topUp link in the body. |
Per minute | 10 sandbox, 60 standard | X-RateLimit-Minute-Limit and X-RateLimit-Minute-Remaining. Over the limit: 429 with Retry-After. |
Per day | 25 sandbox, 5,000 standard | X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset (Unix time). Resets at 00:00 UTC. |
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_starterThe 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.
| Parameter | Values | Notes |
|---|---|---|
400 | Invalid query, Invalid uuid, Unknown bundle | Fix the parameter named in details. The request is refunded. |
401 | Missing API key | Send the Authorization header. |
403 | Invalid or revoked API key | Create a new key. An unknown key and a revoked key get the same answer by design, so the response does not reveal which keys exist. |
404 | Podcast not found | The uuid is not in the catalogue. |
429 | Per-minute rate limit exceeded, Daily quota exceeded, Credits exhausted | Wait for Retry-After, or top up (the body carries a topUp link). |
500 | Search failed, Internal error | Retry; if it persists, email support. |
503 | API temporarily disabled | The API is paused for maintenance. Retry later. |
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.