Versioning and deprecation

Integrations outlive the decisions that shaped them. This page says what we will and will not change under you, so you can decide how much to pin.

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 can land at any time, and your client must tolerate them. Treat this list as the contract it is — code written to break on any of these is code that will break.

• 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 recognise 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.

Anything in this list goes into a new major version. We do not make breaking changes to v1.

Deprecation policy

When something is on its way out, you find out from the API itself rather than from a blog post you did not read. A deprecated endpoint returns two headers on every response, per RFC 9745 and RFC 8594:

Deprecation: @1780272000
Sunset: Sat, 01 Aug 2026 00:00:00 GMT
Link: <https://docs.speechrevolutions.com/versioning>; rel="deprecation"

• Deprecation — when it became deprecated. It still works.
• Sunset — the date it stops working. Never less than 12 months after the Deprecation date for anything in a stable version.
• Link — where to read what replaces it.

We will also email the account owner at deprecation, at three months, and at one month. Log a warning when you see a Sunset header and you will never be surprised by one.

SDK versioning

The Python, JavaScript, Go and C# SDKs follow semantic versioning independently of the API. A major SDK release may change its own surface without any API change; pin a major version and read the changelog before moving.

Security exception

One thing overrides all of the above: if a field or behaviour is actively exposing customer data, we will change it as fast as we can and tell you afterwards. A twelve month notice period on a data leak protects nobody.