# Versioning and Deprecation You can rely on this policy for the [Jobs API](/jobs-v2.md), the [x402 API](/x402-v2.md), and the [Edge API](/edge-v2.md). 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](/mcp.md). ## 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](https://semver.org/spec/v2.0.0.html), and a new version in the path is a new major release. You can track releases in the changelogs: [Jobs API and x402 API](/jobs-v2/changelog.md), which ship together, and [Edge API](/edge-v2/changelog.md). ## 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](#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](https://keepachangelog.com/en/1.1.0/). 2. **Response headers.** During the notice period, every response from the deprecated version carries a `Deprecation` header ([RFC 9745](https://www.rfc-editor.org/rfc/rfc9745.html)) and a `Sunset` header ([RFC 8594](https://www.rfc-editor.org/rfc/rfc8594.html)). 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](https://dash.speechischeap.com/) 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: ```http Deprecation: @1894665600 Sunset: Mon, 15 Jul 2030 00:00:00 GMT Link: ; 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.