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.

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
401 — Invalid or missing token
404 — Resource not found (or not accessible to your account)
429 — Rate limit exceeded

Rate Limiting

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

Header	Description
`X-RateLimit-Limit`	Maximum requests per minute
`X-RateLimit-Remaining`	Requests remaining in the current window
`Retry-After`	Seconds to wait before retrying (only on 429 responses)

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

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

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

Parameter	Type	Default	Description
`page`	integer	1	Page number

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://storage.example.com/covers/my-podcast.jpg",
      "created_at": "2024-01-15T12:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "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://storage.example.com/covers/my-podcast.jpg",
    "total_downloads": 50000,
    "created_at": "2024-01-15T12:00:00Z"
  }
}

Field	Type	Description
`token`	string	Unique podcast identifier (UUID). Use this in other API calls.
`title`	string	Podcast title
`slug`	string	URL slug
`description`	string	Podcast description
`subtitle`	string or null	Podcast subtitle
`author_name`	string	Author name
`language`	string	Language code (e.g. "en-us")
`explicit`	boolean	Whether the podcast is marked explicit
`artwork_url`	string or null	URL to the podcast cover artwork
`total_downloads`	integer	All-time total downloads for the podcast (show endpoint only)
`created_at`	string	Creation timestamp (ISO 8601)

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

Parameters

Parameter	Type	Default	Description
`page`	integer	1	Page number

Response

{
  "data": [
    {
      "token": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "title": "Episode Title",
      "slug": "episode-slug",
      "url": "https://mypodcast.fireside.fm/episode-slug",
      "season": 2,
      "duration": 1830,
      "explicit": false,
      "published_at": "2026-03-01T00:00:00-05:00",
      "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,
    "previous": null,
    "next": 2
  }
}

Field	Type	Description
`token`	string	Unique episode identifier
`title`	string	Episode title
`slug`	string	URL slug for the episode
`url`	string	Full URL to the episode page
`season`	integer or null	Season number
`duration`	integer or null	Duration in seconds
`explicit`	boolean	Whether the episode is marked explicit
`published_at`	string	Publish timestamp (ISO 8601)
`downloads.1_day`	integer or null	Downloads within 1 day of publish. `null` if not enough time has passed.
`downloads.7_day`	integer or null	Downloads within 7 days of publish
`downloads.14_day`	integer or null	Downloads within 14 days of publish
`downloads.30_day`	integer or null	Downloads within 30 days of publish
`downloads.90_day`	integer or null	Downloads within 90 days of publish
`downloads.spotify`	integer	Total Spotify downloads. Only present when the podcast has Spotify connected.
`downloads.total`	integer	All-time total downloads for this episode
`pagination.page`	integer	Current page number
`pagination.per_page`	integer	Results per page
`pagination.previous`	integer or null	Previous page number, or `null` if on the first page
`pagination.next`	integer or null	Next page number, or `null` if on the last page

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

Parameter	Type	Default	Description
`page`	integer	1	Page number

Response

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

Field	Type	Description
`data[].date`	string	First day of the period (YYYY-MM-DD)
`data[].value`	integer	Total downloads for that period
`meta.total_downloads`	integer	All-time total downloads for the podcast
`pagination.page`	integer	Current page number
`pagination.per_page`	integer	Results per page
`pagination.previous`	integer or null	Previous page number, or `null` if on the first page
`pagination.next`	integer or null	Next page number, or `null` if on the last page

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