# Versioning

Our API uses date-based versioning via the `X-API-Version` header. The value you provide—any valid date in the `YYYY-MM-DD` format—represents the exact state of the API as it existed on that day. This design allows you to pin your integration to a specific API snapshot or automatically track the latest stable behavior.

## Specifying the API version
- **Any date allowed**: You may pass any valid date in the `X-API-Version` header. The date you choose directly corresponds to the API state at that point in time.
- **Optional header**: Including the header is optional; if omitted, the API defaults to the latest stable version.

## Response details
Each API response includes an `X-API-Version` header that shows the version (date) of the API that processed your request. This ensures transparency, so you're always aware of the API state applied to your request.

## Migrating to a newer version
When migrating to a newer API version, specify the current date in the header. This deliberate action helps transition your integration to the updated API behavior.

## Versioning Policy
- **Breaking changes only**: New version dates are introduced only when breaking changes occur, requiring client-side adaptations.
- **Non-breaking updates**: Enhancements such as additional response fields are deployed without updating the API version.

## Beta features

Features marked with the Beta badge are experimental and might be changed or removed without notice.

> warn
> Our API is always evolving, therefore we recommend to regularly monitor for new version releases and update your integration accordingly.
>
> Please refer to our Telegram channel for updates: 
> [Sensay API Announcements Telegram channel](https://t.me/sensay_api).