How to use the Podbite API

The Podbite API lets you create and manage bites and playlists programmatically. This guide covers key generation, authentication, and three calls that form the foundation of any integration. For the full endpoint reference, see the interactive API docs.

The API is available on the Automate plan.

What you'll need

• An Automate plan subscription
• An API key — go to Manage account → Developers → API Keys and click Generate key

The key is shown once. Copy it now and store it in a secret manager or environment variable — you cannot retrieve it again, only regenerate.

Authentication

Every request requires your key in the X-Podbite-Key header:

X-Podbite-Key: YOUR_API_KEY

The base URL for all API calls is https://api.podbite.link/v1.

1. Confirm your key works

GET /v1/quota is the lightest call available — it returns your current usage and does not count against your monthly quota.

curl https://api.podbite.link/v1/quota \
  -H "X-Podbite-Key: YOUR_API_KEY"

A successful response:

{
  "used": 12,
  "limit": 500,
  "remaining": 488,
  "resets_at": "2026-08-01T00:00:00.000Z"
}

resets_at is midnight UTC on the first day of the next calendar month.

If you get a 401, the key is wrong or revoked. A 402 means the Automate subscription is not active.

2. Resolve an episode

Before creating a bite you need an episode_short_id. Use GET /v1/episodes/resolve to look up an episode by its URL.

curl "https://api.podbite.link/v1/episodes/resolve?url=https%3A%2F%2Fpodcasts.apple.com%2Fpodcast%2Fid1234567890%3Fi%3D9876543210" \
  -H "X-Podbite-Key: YOUR_API_KEY"

Supported URL formats: Apple Podcasts (podcasts.apple.com) and Podchaser (podchaser.com).

A successful response:

{
  "episode_short_id": "abc123",
  "title": "Episode title",
  "podcast_title": "Podcast name"
}

Why resolve first? The first time Podbite sees an episode it fetches metadata from the provider, which takes 1–3 seconds. Resolving once and reusing the episode_short_id keeps subsequent bite creation calls fast. If you're creating multiple bites from the same episode, resolve it once at the start.

You can skip this step and pass episode_url directly when creating a bite — useful for one-off calls. The resolution happens inline; the first request takes the hit.

If you receive a 504, the provider took too long. Retry once — if it persists, the episode metadata may not be publicly available.

3. Create a bite

curl https://api.podbite.link/v1/bites \
  -X POST \
  -H "X-Podbite-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "episode_short_id": "abc123",
    "start_time": 312.5,
    "end_time": 347.0,
    "caption": "The moment everything clicked"
  }'

start_time and end_time are in seconds. The response includes the bite's short_id and its public URL.

Limits at a glance

Quota counts bites and playlists created via the API. Items created in the web app do not count against it.

What's next

• Full reference — every endpoint, parameter, and response schema is in the API docs
• Webhooks — receive real-time notifications when bites or playlists change instead of polling — see How to use Podbite webhooks
• Playlists — group bites with POST /v1/playlists and POST /v1/playlists/:id/bites; the API docs have the full schema