API Documentation

Authentication

All API requests require a Bearer token in the Authorization header. Create API keys from your account settings.

Authorization: Bearer fire_your_token_here

Tokens use the fire_ prefix followed by 64 hex characters. The raw token is shown once at creation — store it securely. If a token is lost, revoke it and create a new one.

Each key is either Read Only (the default) or Read/Write, chosen when you create it and changeable later under Account > API Keys, without replacing the key. Read Only keys can use every endpoint on this page. Endpoints that make changes need a Read/Write key, and are still limited to what your role on the podcast allows. Current User reports a key’s access as read_only or read_and_write.

Invalid or missing tokens return 401 Unauthorized:

{
  "error": {
    "message": "Invalid or missing API token",
    "code": "unauthorized"
  }
}

Base URL

All endpoints are under the /api/v1/ namespace:

https://fireside.fm/api/v1/

All responses are JSON. Endpoints return appropriate HTTP status codes:

• 200 — Success
• 201 — Created
• 400 — A parameter or field is missing, unknown, or the wrong type
• 401 — Invalid or missing token
• 403 — Your role or plan doesn’t allow this (same rules as the Fireside dashboard), or a Read Only key tried to make a change
• 404 — Resource not found (or not accessible to your account)
• 422 — The change didn’t pass validation; nothing was saved
• 429 — Rate limit exceeded

Rate Limiting

API requests are limited to 120 requests per minute per API token, or per IP address for unauthenticated requests. Every response includes rate limit headers:

When the limit is exceeded, the API returns 429 Too Many Requests:

{
  "error": {
    "message": "Rate limit exceeded.",
    "code": "rate_limited"
  }
}

Current User

GET /api/v1/me

Returns the account the token belongs to. Useful for checking that a token works.

Response

{
  "data": {
    "name": "Jane Doe",
    "email": "[email protected]",
    "created_at": "2024-01-15T12:00:00Z",
    "api_token": {
      "name": "My CLI",
      "access": "read_only",
      "created_at": "2026-09-01T12:00:00Z"
    }
  }
}

List Podcasts

GET /api/v1/podcasts

Returns all podcasts you own or collaborate on. Only complete, active podcasts are included. Results are paginated (50 per page).

Parameters

Response

{
  "data": [
    {
      "token": "550e8400-e29b-41d4-a716-446655440000",
      "title": "My Podcast",
      "slug": "my-podcast",
      "description": "A podcast about things.",
      "subtitle": "Things and stuff",
      "author_name": "Jane Doe",
      "language": "en-us",
      "explicit": false,
      "artwork_url": "https://media24.fireside.fm/file/fireside-images-2024/podcasts/images/5/550e8400-e29b-41d4-a716-446655440000/cover.jpg?v=3",
      "created_at": "2024-01-15T12:00:00Z",
      "url": "https://my-podcast.fireside.fm",
      "feed_url": "https://feeds.fireside.fm/my-podcast/rss",
      "type": "episodic",
      "categories": [{ "name": "Tech News", "parent": "Technology" }],
      "copyright": "© 2026 My Podcast",
      "donation_url": null,
      "owner": { "name": "Jane Doe", "email": "[email protected]" }
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "max_per_page": 50,
    "previous": null,
    "next": 2
  }
}

The podcast fields are the same as the Get Podcast endpoint, except total_downloads which is only available on the show endpoint.

Get Podcast

GET /api/v1/podcasts/:podcast_token

Returns details for a single podcast, including total_downloads.

Response

{
  "data": {
    "token": "550e8400-e29b-41d4-a716-446655440000",
    "title": "My Podcast",
    "slug": "my-podcast",
    "description": "A podcast about things.",
    "subtitle": "Things and stuff",
    "author_name": "Jane Doe",
    "language": "en-us",
    "explicit": false,
    "artwork_url": "https://media24.fireside.fm/file/fireside-images-2024/podcasts/images/5/550e8400-e29b-41d4-a716-446655440000/cover.jpg?v=3",
    "total_downloads": 50000,
    "created_at": "2024-01-15T12:00:00Z",
    "url": "https://my-podcast.fireside.fm",
    "feed_url": "https://feeds.fireside.fm/my-podcast/rss",
    "type": "episodic",
    "categories": [{ "name": "Tech News", "parent": "Technology" }],
    "copyright": "© 2026 My Podcast",
    "donation_url": null,
    "owner": { "name": "Jane Doe", "email": "[email protected]" }
  }
}

List Episodes

GET /api/v1/podcasts/:podcast_token/episodes

Returns every episode of a podcast, including drafts and scheduled episodes, ordered by publish date (newest first). Results are paginated (100 per page). Requires the owner, manager, or producer role, the same as the episode pages in the Fireside dashboard.

Parameters

Response

{
  "data": [
    {
      "token": "6a20c700-51d3-4c0a-abe7-da88d972a27c",
      "title": "Alternating Currents",
      "subtitle": "Tesla vs. Edison",
      "slug": "42",
      "season": 2,
      "episode_type": "full",
      "status": "published",
      "visibility": "public",
      "members_only": false,
      "explicit": false,
      "duration": 3120,
      "published_at": "2026-09-10T23:14:54Z",
      "created_at": "2026-09-01T12:00:00Z",
      "updated_at": "2026-09-10T23:14:54Z",
      "url": "https://my-podcast.fireside.fm/42",
      "preview_url": "https://my-podcast.fireside.fm/preview/x7Kq2mPa",
      "audio_url": "https://aphid.fireside.fm/d/1437767933/550e8400-e29b-41d4-a716-446655440000/6a20c700-51d3-4c0a-abe7-da88d972a27c.mp3",
      "audio_size": 49920000,
      "audio_status": "ready",
      "audio_error": null,
      "guid": "6a20c700-51d3-4c0a-abe7-da88d972a27c",
      "artwork_url": "https://media24.fireside.fm/file/fireside-images-2024/podcasts/images/5/550e8400-e29b-41d4-a716-446655440000/cover.jpg?v=3",
      "transcript_url": "https://media24.fireside.fm/file/fireside-images-2024/podcasts/transcripts/5/550e8400-e29b-41d4-a716-446655440000/episodes/6/6a20c700-51d3-4c0a-abe7-da88d972a27c/transcript.txt",
      "chapters_url": "https://feeds.fireside.fm/my-podcast/json/episodes/6a20c700-51d3-4c0a-abe7-da88d972a27c/chapters",
      "player_url": "https://fireside.fm/player/v2/AbCd1234+EfGh5678",
      "player_embed_code": "<iframe src=\"https://fireside.fm/player/v2/AbCd1234+EfGh5678\" width=\"740\" height=\"200\" frameborder=\"0\" scrolling=\"no\"></iframe>",
      "soundbite": { "title": "The best bit", "start_time": 90, "duration": 30 },
      "hosts": [{ "name": "Jane Doe", "url": "https://janedoe.example.com" }],
      "guests": [{ "name": "Sam Lee", "url": null }]
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 100,
    "max_per_page": 100,
    "previous": null,
    "next": null
  }
}

Get Episode

GET /api/v1/podcasts/:podcast_token/episodes/:episode_token

Returns a single episode with the same fields as List Episodes, plus description (the show notes).

Create Episode

POST /api/v1/podcasts/:podcast_token/episodes

Creates a draft episode, starting from the podcast’s episode defaults as a new episode in the dashboard does. It stays private until you publish it. Needs a Read/Write key and the producer role. Send a JSON body (Content-Type: application/json) with any of these fields:

Returns 201 Created with the episode, as in Get Episode. Unknown fields are refused with a 400 rather than ignored.

Cover art and transcripts transfer during the request. If one can’t be processed, the response is 422 with the code upload_failed, naming the file; the episode’s other changes are still saved, and the response’s data is the episode, so you can retry the file with an update. Resending an audio file_url after its transfer failed retries it.

Validation errors return 422, keyed by the field you sent:

{
  "error": {
    "message": "slug has already been taken",
    "code": "validation_failed",
    "fields": {
      "slug": ["has already been taken"]
    }
  }
}

A Read Only key gets 403 on every endpoint that makes changes:

{
  "error": {
    "message": "Token does not have write access. Change this key to Read/Write under Account > API Keys to make changes.",
    "code": "write_access_required"
  }
}

While a podcast is on hiatus, suspended, or taken down, its episodes can still be read but not changed, as in the dashboard. Writes then return 403 with the code podcast_inactive.

Update Episode

PATCH /api/v1/podcasts/:podcast_token/episodes/:episode_token

Changes the fields you send, from the same list as Create Episode, and leaves the rest alone. Changes to a published episode go live right away, and a new slug changes its URL. Release date and visibility change only through publish and unpublish. Returns the updated episode.

Publish Episode

POST /api/v1/podcasts/:podcast_token/episodes/:episode_token/publish

Releases an episode now, on a schedule, or backdated. The episode needs audio; one without returns 422 with the code audio_required. If the episode is set in the dashboard to be posted to the podcast’s connected social accounts, publishing posts it, as it does from the dashboard. Returns the episode.

Unpublish Episode

POST /api/v1/podcasts/:podcast_token/episodes/:episode_token/unpublish

Makes the episode a private draft, taking it out of the feed and off the website. Its published_at is kept, so publishing again with that time puts it back in place. Returns the episode.

Upload a File

POST /api/v1/podcasts/:podcast_token/uploads

Episode audio, cover art and transcripts upload in two steps. First ask for a signed upload URL, describing the file; it’s checked against your plan’s limits before anything is sent. Then upload the file with an HTTP PUT to upload_url within the hour, sending the returned headers, and attach its file_url to an episode with Create Episode or Update Episode. Needs a Read/Write key and the producer role.

Response

{
  "data": {
    "kind": "audio",
    "upload_url": "https://s3.amazonaws.com/...",
    "method": "PUT",
    "headers": { "Content-Type": "audio/mpeg" },
    "file_url": "https://s3.amazonaws.com/...",
    "expires_at": "2026-10-12T15:00:00Z"
  }
}

Upload, then attach:

curl -X PUT -T episode.mp3 -H "Content-Type: audio/mpeg" "$UPLOAD_URL"

curl -X PATCH https://fireside.fm/api/v1/podcasts/:podcast_token/episodes/:episode_token \
  -H "Authorization: Bearer fire_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"audio_file_url": "'"$FILE_URL"'"}'

Attaching checks the uploaded file is one granted for that podcast and still within the limit. A file that isn’t returns 422 and nothing on the episode changes.

Episode Metrics

GET /api/v1/podcasts/:podcast_token/metrics/episodes

Per-episode download statistics for all published episodes, ordered by publish date (newest first). Results are paginated (100 per page). Each episode has the same fields as List Episodes, plus downloads.

Parameters

Response

{
  "data": [
    {
      "token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "title": "Episode Title",
      "subtitle": null,
      "slug": "episode-slug",
      "season": 2,
      "episode_type": "full",
      "status": "published",
      "visibility": "public",
      "members_only": false,
      "explicit": false,
      "duration": 1830,
      "published_at": "2026-03-01T05:00:00Z",
      "created_at": "2026-02-20T12:00:00Z",
      "updated_at": "2026-03-01T05:00:00Z",
      "url": "https://mypodcast.fireside.fm/episode-slug",
      "preview_url": "https://mypodcast.fireside.fm/preview/x7Kq2mPa",
      "audio_url": "https://aphid.fireside.fm/d/1437767933/550e8400-e29b-41d4-a716-446655440000/a1b2c3d4-e5f6-7890-abcd-ef1234567890.mp3",
      "audio_size": 29280000,
      "audio_status": "ready",
      "audio_error": null,
      "downloads": {
        "1_day": 500,
        "7_day": 1200,
        "14_day": 1800,
        "30_day": 2500,
        "90_day": 4000,
        "spotify": 300,
        "total": 5000
      }
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 100,
    "max_per_page": 100,
    "previous": null,
    "next": 2
  }
}

Downloads by Month

GET /api/v1/podcasts/:podcast_token/metrics/downloads

Monthly download totals for the podcast, in reverse chronological order. Results are paginated (36 per page).

Parameters

Response

{
  "data": [
    { "date": "2026-03-01", "value": 1500 },
    { "date": "2026-02-01", "value": 1200 }
  ],
  "meta": {
    "total_downloads": 50000
  },
  "pagination": {
    "page": 1,
    "per_page": 36,
    "max_per_page": 36,
    "previous": null,
    "next": 2
  }
}

Downloads by Day

GET /api/v1/podcasts/:podcast_token/metrics/daily
GET /api/v1/podcasts/:podcast_token/episodes/:episode_token/metrics/daily

Downloads per day for the whole podcast, or for one episode, oldest first. Every day in the range is listed, including days with none. Days are the podcast’s local calendar days, as in the dashboard.

Parameters

A range can cover at most 90 days; request longer periods in parts.

Response

{
  "data": [
    { "day": "2026-10-01", "downloads": 412, "spotify": 38, "total": 450 },
    { "day": "2026-10-02", "downloads": 297, "spotify": 21, "total": 318 }
  ],
  "meta": {
    "start_date": "2026-10-01",
    "end_date": "2026-10-02",
    "time_zone": "Eastern Time (US & Canada)",
    "downloads": 709,
    "spotify": 59,
    "total": 768
  }
}

downloads are counted by Fireside; spotify are Spotify’s own counts, reported separately; total adds the two.

Quick Start

1. Create an API key from your API Keys page.

2. List your podcasts:

curl -H "Authorization: Bearer fire_your_token" \
  https://fireside.fm/api/v1/podcasts

3. Get episode metrics using a podcast token from the response:

curl -H "Authorization: Bearer fire_your_token" \
  https://fireside.fm/api/v1/podcasts/PODCAST_TOKEN/metrics/episodes

4. Get monthly downloads:

curl -H "Authorization: Bearer fire_your_token" \
  https://fireside.fm/api/v1/podcasts/PODCAST_TOKEN/metrics/downloads