Docs

Appearance

Versioning & Policies ​

The public API is a contract. This page spells out what we promise, what we reserve, and what has changed.

Rely on URL versioning ​

The API is versioned in the URL path: every endpoint lives under /v1.

Additive changes stay in v1. New fields on existing payloads, new endpoints, and new optional query parameters can appear in v1 at any time without notice. Write your integration to tolerate unknown fields: never fail on a key you don't recognise.

Breaking changes ship as a new version. Renaming or removing a field, changing a type, or changing an endpoint's semantics will only ever happen in a new version prefix (/v2). When a new version ships:

  • v1 keeps running in parallel for at least 12 months.
  • The deprecation timeline is documented here, in the changelog, before anything is switched off.

Version the player too ​

The embeddable player follows the same principle on its own axis:

  • https://embed.cdn.media/player/v1.js receives backwards-compatible updates in place: visual refinements, fixes, and new optional attributes.
  • Breaking player changes ship as /player/v2.js; existing v1.js embeds keep working.

Embed codes copied from the dashboard always reference the current recommended version.

Authentication ​

Public read endpoints are keyless: you never need credentials to read published content, and that will not change. Sending an Authorization header to them is harmless: it is ignored, never an error.

Your own data is under /v1/me, read with an API key:

Authorization: Bearer showfm_live_…

Keys are read-only, expire within a year, and are created in Settings → API keys. The same API serves development and production: there is no separate sandbox. See Develop and test your integration.

Fair-use rate limits ​

The API and embed hosts are free to use. Dynamic GET and HEAD reads have a fair-use limit of 600 requests per 60 seconds per client IP at each Cloudflare location. API /v1/* requests and embed /ep/* and /latest/* requests share the same allowance across production hosts and paths. Staging has a separate allowance. Static player assets and OPTIONS requests do not count toward this limit.

The counters are approximate and eventually consistent, so this is not a precise global quota. Clients sharing a public IP also share its allowance.

  • When the Worker rejects a read, it returns 429 with the rate_limited error envelope and Retry-After: 60. Wait at least 60 seconds, then retry with jitter.
  • Responses are heavily cached (Cache-Control with max-age=60); honour those headers and use ETag / If-None-Match conditional requests instead of re-downloading unchanged payloads. Content changes at podcast-publishing cadence, so polling more than once a minute gains you nothing.
  • Embedding players on high-traffic sites is fine and expected; the player and its data path are built to be cached at the edge.

Keyed requests (/v1/me) have their own allowances instead, per minute: 600 across every key you hold, and, for each plan's podcasts, Creator 60, Studio 120, Production House 300 and Enterprise 600. Every keyed response carries RateLimit-Policy and RateLimit headers, and a 429 carries Retry-After. See API keys.

There is no SLA on the public API or embed hosts. They're built on the same edge infrastructure that serves show.fm RSS feeds and media, but we make no formal availability guarantee for third-party integrations.

Changelog ​

The October 2026 additions below are announced together in the show.fm changelog: Read your own show.fm data with an API key.

2026-10: Episodes and transcripts with an API key ​

Additive, within v1:

  • Content endpoints (episodes:read): your episodes, including drafts and scheduled ones, with plain-text and sanitised-HTML show notes; their roster and credits. Media URLs appear only once an episode is public. See Your episodes.
  • Transcripts (transcripts:read): transcript segments with speaker names.

2026-10: Analytics with an API key ​

Additive, within v1:

  • Analytics endpoints (owner only, analytics:read): downloads over time for a podcast or an episode, downloads per episode, breakdowns by app, country, device, source and referrer, and Apple and Spotify imports. Every response says which window it used, how complete the figures are and how they were counted. See Analytics API guide.
  • error.details items may carry a reason, for example outside_retention.

2026-10: API keys and your own podcasts ​

Additive, within v1:

  • API keys: create read-only keys in Settings → API keys. See API keys.
  • Keyed endpoints: GET /v1/me, GET /v1/me/podcasts, GET /v1/me/podcasts/{podcast_id}.
  • OpenAPI: the whole v1 surface at GET /v1/openapi.json.
  • New error codes (keyed endpoints only): unauthorized, invalid_api_key, insufficient_scope, forbidden, plan_upgrade_required.

2026-07-06: v1 launch ​

Initial public release:

  • Podcasts: GET /v1/podcasts/{slug}, GET /v1/podcasts/{slug}/episodes (cursor pagination), GET /v1/podcasts/{slug}/episodes/latest, GET /v1/podcasts/{slug}/episodes/{idOrSlug}.
  • Episodes: GET /v1/episodes/{id}.
  • oEmbed: GET /v1/oembed for listen-page URLs, with discovery tags on listen pages.
  • Embeddable player: <showfm-player> web component at embed.cdn.media/player/v1.js, plus iframe pages at /ep/{episodeId} and /latest/{podcastSlug}.

Was this page helpful?