Skip to main content

API versioning and deprecation policy

This policy explains how Feed.fm changes its public REST API and gives you time to update your integration when a change requires it. It covers documented endpoints and behavior under /api/v3 and future public major versions.

Introducing the direct API and this policy does not require existing Feed.fm SDK customers to migrate. SDK releases have their own version numbers and release notes.

Choosing an API version​

Select the major version in the request URL. For example, POST /api/v3/session uses version 3. Include the version prefix on every request; omitting it does not select a default public API version.

Compatible improvements and fixes are delivered within that major version. Selecting /api/v3 keeps your requests on v3 while receiving those updates.

Planned breaking changes use a new major version, such as a future /api/v4. You choose when to move to the replacement before the old version's announced retirement date. Both versions remain available throughout the migration window.

What counts as a breaking change​

A change is breaking when an integration that follows the documented API contract must change to keep working. This includes changes to behavior as well as request and response formats.

Examples include:

  • Removing or renaming an endpoint, request parameter, or response field.
  • Changing a field's type, meaning, or default behavior.
  • Adding a required parameter, or tightening validation so previously valid requests fail.
  • Changing authentication or adding required playback reporting steps.
  • Changing documented HTTP status codes, error codes, or error behavior in a way that requires different handling.
  • Reducing documented rate limits so previously permitted usage is rejected.
  • Changing supported audio formats or bitrate requirements in a way that requires playback code to change.

Compatible changes can include new endpoints, new optional response fields, and optional request parameters that preserve existing behavior when omitted. Clients should ignore response fields they do not use.

New enum values are compatible only where the documentation already tells clients to expect and handle additional values. Bug fixes are assessed for compatibility using the same rules as other changes.

Deprecation and retirement​

Deprecation announces a future retirement. A deprecated version continues to work until its announced retirement date, subject to the urgent exceptions below. Deprecating a feature does not remove it from the version you are using. Removing it is a breaking change, so the removal ships in a new major version and the old version keeps the feature until that version retires.

Feed.fm provides at least 180 calendar days' notice before retiring a public API version. The notice period starts when all three are available:

  1. A working replacement version that affected customers can use and test.
  2. A migration guide explaining the required changes, with before-and-after examples.
  3. A customer notice stating the affected version and retirement date.

The old version remains available throughout this period. We continue to address security issues and defects that prevent documented behavior from working. New features may be limited to the replacement version. Retirement happens on the announced date; reaching 180 days does not automatically retire a version.

Complete your migration before that date. If you expect difficulty meeting the deadline, contact your Feed.fm customer contact early to discuss the impact and available options.

How we communicate changes​

We publish deprecation notices in the API changelog, mark affected features in the API documentation, and email affected customers' technical contacts.

Each notice includes:

  • The affected API version and endpoints or features.
  • What is changing and what customers need to do.
  • The replacement version and migration guide.
  • The retirement date and a contact for migration questions.

For planned retirements, we send a reminder 30 calendar days before retirement. Keep your technical contact details current with your Feed.fm customer contact so notices reach the people responsible for your integration.

Urgent security or licensing changes​

An urgent security issue or licensing requirement may require a breaking change within an existing version or retirement with less than 180 days' notice.

We notify affected customers as soon as possible, explain what is changing and why, and provide the effective date and any required action. We publish the change in the changelog, including migration guidance where applicable.

Changelog and questions​

The API changelog is the public record of changes that affect integrations. Entries appear newest first and include the date, affected API version, change, customer action, and any deadline or migration guide.

Contact your usual Feed.fm customer contact with questions about this policy, a planned migration, or requirements in your agreement.