> For the complete documentation index, see [llms.txt](https://docs.raalabs.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.raalabs.io/getting-started/versioning.md).

# Versioning

The Raa Labs Time Series API aims to be predictable and uses a versioning strategy to ensure stability and transparency for all users.

A new version is released when a breaking change occurs. When a new version is released, the previous version is supported for **six months** before deactivation. Raa Labs staff will notify you in advance.

Each API version comes with a migration guide explaining changes and upgrade suggestions. All current and past API versions can be found under [Versions](/getting-started/changelog/versions.md) in the changelog.

## Breaking Changes

The following changes are considered breaking changes and trigger a new release:

* Removing or changing an HTTP route or method
* Changing authentication or authorization
* Removing or changing required input parameters
* Changes to the response format

All other additive changes are considered backwards compatible, and will be made available within the latest version only. These updates can be found under [Updates](/getting-started/changelog/updates.md) in the changelog.

## Versioning Format

* **Header-based versioning**: API versions are specified using a custom HTTP header
* **Date-based identifiers**: Versions are identified by a date with format `YYYY-MM-DD` (e.g., `2025-10-31`).

The header takes the following form:

```json
"x-api-version": "2025-10-31"
```

Use the `x-api-version` header to target a specific API version. Our approach to this API is to make it easy and quick to use. The `x-api-version` header is therefore **optional**. If omitted, the API will default to the latest version.

{% hint style="info" %}
**Note:** The latest version changes when a new version is released. It is therefore recommended to use the `x-api-version` header in production scenarios.
{% endhint %}

## Beta Versions

We release versions marked as `Beta` versions. Beta versions are under development, and the implementation and response formats might change. Beta versions can be added and removed without prior notification, and should not be used in production environments.