# API versioning

The `/v1` contract grows without requiring existing clients to change.

## Requests

New operations and optional request fields are additive. Existing allowed enum values remain accepted; adding request enum values is additive. A new required request field, a narrower accepted value, a removed operation, or another incompatible change requires `/v2`.

## Responses

New response fields are additive. Ignore fields you do not use. Response enums are extensible, including webhook event types and error codes: the documented values are known values, not a complete set. Accept unknown values and use a safe fallback rather than an exhaustive switch that throws. The `@moq/pro` response types accept future values; request enums still describe the values the server currently accepts.

The [OpenAPI contract](/api.json) marks these sets with `x-extensible-enum`. Removing a response field or changing its type incompatibly requires `/v2`.

## Deprecation

Every announced deprecation appears in the [deprecation ledger](/api-deprecations), with the affected operations, replacement, announcement date, deprecation date and sunset date. Affected responses send `Deprecation`, `Sunset` and a `Link` with `rel="deprecation"` pointing to that entry.

`Deprecation` uses an `@`-prefixed Unix timestamp ([RFC 9745](https://www.rfc-editor.org/rfc/rfc9745.html)); `Sunset` uses an HTTP date ([RFC 8594](https://www.rfc-editor.org/rfc/rfc8594.html)). Deprecation announces migration; it does not change an operation's behavior. An incompatible replacement belongs in `/v2`, and an announced date does not make a breaking `/v1` change additive.