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
detailstring. 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):
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 theDeprecationdate 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.
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.