# Versioning and changes

Every module API carries its major version in the path: `/api/desk/v1`. Within a version, changes
are **backwards compatible**:

| Compatible (may happen any time) | Breaking (only in a new version) |
|---|---|
| new endpoints | removing or renaming an endpoint or field |
| new optional request fields and parameters | new required request fields |
| new response fields | changing a field's type or meaning |
| new enum values, event types and error codes | removing enum values |
| new optional headers | changing authentication |

Build your client to tolerate the left column: ignore unknown response fields, handle unknown enum
values and error codes gracefully (fall back to the HTTP status).

## Deprecation policy

Breaking changes get a new version prefix (`/api/desk/v2`). The previous version stays available for
**at least six months** after the new one is released. Deprecated endpoints are marked `deprecated`
in the OpenAPI documents and in this reference, and every deprecation is announced in the
changelog first.

## Where to follow changes

- The product changelog: [docs.mbcom.cloud/changelog](https://docs.mbcom.cloud/changelog) – searchable and
  filterable by kind and month.
- The OpenAPI documents of this site (`/openapi/<module>.yaml`) always describe what is deployed.
  Diff them in your CI (for example with `oasdiff breaking`) to be warned early.
- The `info.version` of a document changes with every release of its contract.
