Skip to main content

Versioning and Deprecation

You can rely on this policy for the Jobs API, the x402 API, and the Edge API. The Upload endpoints at upload.speechischeap.com belong to the Jobs and x402 APIs and follow their versions. This policy doesn't cover the MCP server.

Versions​

You set the API version in the URL path. For example, /v2/ in https://api.speechischeap.com/v2/jobs/ is version 2 of the Jobs API. Releases follow Semantic Versioning, and a new version in the path is a new major release. You can track releases in the changelogs: Jobs API and x402 API, which ship together, and Edge API.

Breaking and Non-Breaking Changes​

Code that follows the documentation keeps working within a major version. We release breaking changes as a new version in the URL path, such as /v3/, and removing an old version requires the notice described under Deprecation.

A breaking change makes code that follows the documentation stop working. Examples include:

  • Removing or renaming an endpoint, a parameter, or a response field.
  • Changing a field's type or meaning.
  • Making an optional parameter required.

Every other change is non-breaking. Non-breaking changes include adding an endpoint, an optional request parameter, a response field, or support for a new file type or language. Ignore response fields you don't recognize, because new ones can appear. A non-breaking change can ship at any time with a changelog entry.

To fix a security problem, we may change behavior without a notice period. We record the change under Security in the changelog.

Deprecation​

You receive at least six months of notice before we remove any API version. A deprecation announces that a version will be removed and sets the sunset date, the day the version stops working. The notice period runs from the announcement to the sunset date. All dates are in UTC.

  • Until the sunset date, the version keeps working.
  • After the sunset date, the version answers 410 Gone with a link to its replacement.

How We Announce a Deprecation​

You can track a deprecation across three channels:

  1. Changelog. When the notice period starts, the API's changelog gets a Deprecated entry with the sunset date. When we remove the version, it gets a Removed entry. The changelogs follow Keep a Changelog.
  2. Response headers. During the notice period, every response from the deprecated version carries a Deprecation header (RFC 9745) and a Sunset header (RFC 8594). When we have published a migration guide, each response also carries a Link header that points to it.
  3. Dashboard banner. During the notice period, the Dashboard shows a banner about the deprecation.

Log these headers in your client to catch a deprecation early. Deprecation holds the date the notice period started, as @ plus a Unix timestamp in seconds. Sunset holds the time the version stops working, as an HTTP date. The values below are examples, and MIGRATION_GUIDE_URL stands for the guide's address:

Deprecation: @1894665600
Sunset: Mon, 15 Jul 2030 00:00:00 GMT
Link: <MIGRATION_GUIDE_URL>; rel="deprecation"; type="text/html"

Migrating​

Each deprecation names the replacement version. Before the sunset date, move your requests to its URL path and apply the changes the migration guide lists.