[← API v2 Overview](https://motordesk.com/api-docs/v2/)

# Versioning & Deprecation

The API uses path-based major versioning. This page is the compatibility contract: what we guarantee won't change within a major version, what counts as a breaking change, and how deprecations are announced and timed.

## Versioning Model

The major version lives in the path (`/api/2.0`). A new major version (e.g. `/api/3.0`) is introduced **only** for changes that cannot be made additively. Everything else ships within `2.x`. (Note: the API is served at `/api/2.0`; this documentation lives at `/api-docs/v2/`, same version, different host path.)

## Stability & the 2.0 Line

API v2 is declared **stable from 1 January 2027**. From that date the contract below is enforced and breaking changes follow the deprecation cycle. Before that date the surface may still be refined as it settles.

## The Compatibility Contract

Within a major version, these will not change: the `success`/`data`/`meta` response envelope, existing field names and types, existing error `code` values, the authentication scheme, and scope semantics.

**Non-breaking changes ship at any time** (announced in the [changelog](https://motordesk.com/api-docs/v2/changelog/), no version bump): new endpoints, new optional request parameters, new response fields, new enum values, and new error codes.

**Breaking changes** require a deprecation cycle (or a new major version): removing or renaming a field or endpoint, changing a type, making an optional field required, or removing an enum value or error code.

> ** **Build Forward-Compatible Clients.**  
> Tolerate unknown response fields and unknown enum values, and don't hard-fail on error codes you don't recognise (branch on the HTTP status). Clients that follow this rule are unaffected by non-breaking changes.

## Deprecation Lifecycle

A capability moves through three states: **Active → Deprecated → Removed (sunset)**. When something is deprecated it keeps working and is flagged in three places: an entry in the [changelog](https://motordesk.com/api-docs/v2/changelog/), `deprecated: true` on the affected operation in the [OpenAPI document](https://motordesk.com/api/2.0/openapi.json), and `Deprecation` / `Sunset` response headers (with a `Link` to the migration note) on the affected endpoint.

### Notice Periods

- **Endpoint or field**: at least **6 months** between the deprecation announcement and removal.
- **A whole major version** (e.g. retiring `2.0` once `3.0` exists): at least **12 months**, with the sunset date stated in the changelog when the successor ships.

Breaking changes and sunsets are also emailed to the businesses that own affected API keys: once when announced and again ahead of the sunset date. Additive changes are changelog-only.

## Where Changes Are Announced

| Channel | Covers |
| --- | --- |
| [Changelog](https://motordesk.com/api-docs/v2/changelog/) | Every change (the canonical record). |
| OpenAPI `deprecated` + `Deprecation`/`Sunset` headers | Machine-detectable deprecations. |
| In-app notice (Business → Settings → API) | Deprecations affecting your key. |
| Email to key owners | Breaking changes and sunsets only. |