Versioning and deprecation

This page describes how the API is versioned, which changes can happen without notice, and how you are notified before anything is removed.

How the API is versioned

The version is in the path: every endpoint lives under /api/v1/. A new major version would appear at /api/v2/ alongside it, not in place of it.

What is not a breaking change

These changes can happen at any time. Your client must tolerate them.

  • A new field in a response object.
  • A new optional field in a request.
  • A new endpoint, or a new value in a list we already return.
  • A new event type on the progress stream. Ignore event types you do not recognize rather than failing.
  • The order of fields in a JSON object, and the exact wording of an error detail string. Match on the status code and the error type, never on prose.

What is a breaking change

  • Removing or renaming a field, an endpoint or an enum value.
  • Changing a field's type, or making an optional request field required.
  • Changing the meaning of an existing status code.

Breaking changes ship only in a new major version. v1 receives no breaking changes.

Deprecation policy

A deprecated endpoint returns these headers on every response, per RFC 9745 and RFC 8594:

For example (illustrative dates — nothing is deprecated today):

http
Deprecation: @1893456000
Sunset: Wed, 01 Jan 2031 00:00:00 GMT
Link: <https://docs.speechrevolutions.com/versioning>; rel="deprecation"
  • Deprecation — when the endpoint was deprecated. It still works.
  • Sunset — the date it stops working. Always at least 12 months after the Deprecation date for anything in a stable version.
  • Link — where to read what replaces it.

The account owner also gets an email at deprecation, three months before the sunset, and one month before it. Log a warning whenever you see a Sunset header.

The v1 API has no deprecated endpoints and no scheduled sunsets.

SDK versioning

The Python, JavaScript, Go and C# SDKs follow semantic versioning independently of the API. A major SDK release may change the SDK's interface without any API change. Pin a major version and read the changelog before you upgrade.

Security exception

If a field or behavior exposes customer data, it is changed as quickly as possible, without the notice period above, and you are notified afterwards.