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.podcasterplus.com/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.

Reserved authentication scheme

v1 endpoints are keyless: you never need credentials to read published content, and that will not change.

For future endpoints that expose private data or accept writes, the following scheme is reserved:

Authorization: Bearer pp_live_xxxxxxxxxxxxxxxx   # production keys
Authorization: Bearer pp_test_xxxxxxxxxxxxxxxx   # test keys

Two things follow from the reservation:

1. If you build a client library today, model authentication as an optional bearer token with the pp_live_ / pp_test_ prefixes; it will slot in when keyed endpoints arrive.
2. Sending an Authorization header to v1 read endpoints is harmless: it's silently ignored, never an error.

API keys do not exist yet; there is nothing to generate in the dashboard today.

Fair-use rate limits

The API and embed hosts are free to use, without published hard quotas, under a fair-use policy:

• Abusive or runaway traffic is rate limited at the platform edge, in front of the API. Expect 429 responses if you hit the limits (they may not carry the API's JSON error envelope); back off and 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.

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

Changelog

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: <podcasterplus-player> web component at embed.podcasterplus.com/player/v1.js, plus iframe pages at /ep/{episodeId} and /latest/{podcastSlug}.