> ## Documentation Index
> Fetch the complete documentation index at: https://developers.perkstar.co.uk/llms.txt
> Use this file to discover all available pages before exploring further.

# Versioning and compatibility

> Understand Perkstar API versions, SDK releases, and safe upgrade practices.

The REST API is date-versioned. Every response includes `X-API-Version`, and the
OpenAPI document identifies the contract it describes.

## Compatibility policy

Within a published API version, Perkstar may:

* add optional response fields;
* add new endpoints or webhook event types;
* add optional request fields; and
* improve validation and error detail without changing successful behaviour.

Integrations should ignore unknown response fields and webhook event types they
do not handle. Do not model API objects as closed dictionaries unless your
decoder supports forward-compatible fields.

A breaking change requires a new version and a migration period. The current
OpenAPI description states the active deprecation policy.

## SDK versions

`@perkstar/api-client` follows semantic versioning:

* patch releases contain compatible fixes;
* minor releases add compatible functionality; and
* major releases may require code changes or pin a newer API contract.

Pin a supported version range, run contract tests in CI, and review the
[changelog](/changelog) before upgrading.

## Detecting drift

Log `X-API-Version` with request IDs. During deployment, compare the SDK's
exported `API_VERSION` with the server header and alert on an unexpected value.