A New Public Surface for Podcasts

Spotify has opened its podcast functionality to third-party developers with a new Podcasts API. External apps can now connect to Spotify to manage a user’s podcast library, search the podcast catalog, and retrieve detailed metadata about shows and episodes.

The new endpoints extend the existing Web API family, which already serves millions of daily consumers across a wide range of applications and hardware. As with other Spotify developer surfaces, the podcast API did not appear overnight—it follows an established internal incubation and review process.

From Internal Tool to Public Product

Spotify's Web API team deliberately keeps the public API surface smaller than the full feature set of its consumer apps. New functionality is often introduced internally first, where it can be exercised by engineers in contexts like Hack Week projects and internally developed applications.

The podcast endpoints followed this pattern. Their initial iteration dates back to 2015, when a small feature set supported functionality for open.spotify.com—chiefly the ability to list episodes and shows in a user’s library and to read podcast metadata from the catalog.

Before writing code for the expanded public version, the Web API team circulated a design proposal documenting the planned endpoints. Sharing the design ahead of implementation lets the team collect feedback from both internal stakeholders and prospective partners while changes are still inexpensive.

Balancing Four Design Constraints

The design phase weighed several competing concerns. The team’s proposal needed to satisfy four main criteria:

  • Backward compatibility. Existing endpoints that gained podcast functionality had to remain usable by older clients. The Player API, for instance, now accepts a query parameter that lets clients capable of handling podcast objects opt in to receiving information about currently playing episodes.
  • Consistency with existing Spotify Web APIs. Developers who have worked with other Spotify endpoints should find familiar error codes, request and response payloads, and authentication flows.
  • Alignment with app terminology. A newcomer should be able to map features in the Spotify app to corresponding API features without guesswork.
  • Payload verbosity control. The endpoints can return either a full episode object or a simplified episode object depending on context. The team had to decide which fields justify inclusion in the simplified form and which belong only in the complete object.

Operational Readiness and Partner Feedback

Before any API is exposed externally, the team provisions monitoring for the service using Grafana and Lightstep. The setup integrates with PagerDuty so that an outage or degraded performance triggers an alert and pages an engineer. This operational baseline is a prerequisite for scaling to external partners.

The public launch this week was not the first time outside code ran against these endpoints. A select group of Spotify partners building external integrations received early access. Their feedback drove refinements to both the API design and the onboarding experience for first-time developers.

Documentation received particular attention during this period. At Spotify, API documentation is produced jointly by engineers, technical writers, and the developer relations team, with review conducted through GitHub pull requests.

An Iterative Launch

The public release is not the end of the process. The team plans to monitor feedback closely over the coming six months and to continue improving the API in response. Developers can submit feedback directly to the team.