Data API

Documentation

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.

Authentication

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.

Quickstart

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.

Podcast details

GET https://novacast.ai/api/v1/podcasts/{uuid}?episodes=10
ParameterValuesNotes
episodes0 to 100Default 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.

Episodes

GET https://novacast.ai/api/v1/podcasts/{uuid}/episodes?page=1&pageSize=20
ParameterValuesNotes
page1 to 50Default 1.
pageSize1 to 100Default 20.

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

Similar podcasts

GET https://novacast.ai/api/v1/podcasts/{uuid}/similar?limit=4
ParameterValuesNotes
limit1 to 20Default 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.

Host contacts

POST https://novacast.ai/api/v1/podcasts/{uuid}/contact

Returns 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.

AI assistants (MCP)

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/mcp

Claude 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.

Limits and credits

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

ParameterValuesNotes
Creditssandbox: 25 every week; standard: purchased bundlesOne 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 minute10 sandbox, 60 standardX-RateLimit-Minute-Limit and X-RateLimit-Minute-Remaining. Over the limit: 429 with Retry-After.
Per day25 sandbox, 5,000 standardX-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.

Buying credits

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

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

ParameterValuesNotes
400Invalid query, Invalid uuid, Unknown bundleFix the parameter named in details. The request is refunded.
401Missing API keySend the Authorization header.
403Invalid or revoked API keyCreate 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.
404Podcast not foundThe uuid is not in the catalogue.
429Per-minute rate limit exceeded, Daily quota exceeded, Credits exhaustedWait for Retry-After, or top up (the body carries a topUp link).
500Search failed, Internal errorRetry; if it persists, email support.
503API temporarily disabledThe API is paused for maintenance. Retry later.

Reference

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.