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

# Versioning

> Learn how to target a specific version

Versioning is a major addition of the **v5 Lucca API** (latest API generation) compared with the v3 and v4 APIs (legacy generations).
It protects clients against breaking changes: **each time a breaking change is introduced, a new version is released** rather than
modifying the existing one. The previous version is marked as deprecated and a sunset (i.e. discontinuation) date is set.
Once sunset, the API version can no longer be accessed.

<Warning>
  Some v5 API endpoints are still in **beta** and may not be feature-complete. They are marked with a "BETA" badge in the API Reference.

  **Unlike stable v5 endpoints, beta endpoints are not protected against breaking changes — just like all previous v3 and v4 legacy API endpoints.**

  Once out of beta, endpoints are considered **stable** and subject to our [deprecation policy](/documentation/using-api/versioning#lifecycle-terms).
  Check the [lifecycle recap](/api-reference/latest/lifecycle) for the up-to-date status of each endpoint.
</Warning>

<Frame>
  <img alt="Versioning Strategy" class="dark:hidden" src="https://mintcdn.com/lucca/6CPlsApetP0UYjIR/assets/images/versioning-strategy-illustration-light.svg?fit=max&auto=format&n=6CPlsApetP0UYjIR&q=85&s=4960d36bbc1ae2746b678fc55f848f0a" width="1066" height="408" data-path="assets/images/versioning-strategy-illustration-light.svg" />

  <img alt="Versioning Strategy" class="hidden dark:block" src="https://mintcdn.com/lucca/6CPlsApetP0UYjIR/assets/images/versioning-strategy-illustration-dark.svg?fit=max&auto=format&n=6CPlsApetP0UYjIR&q=85&s=bd54028ca719ccff85f856d6b14bc9c9" width="1066" height="408" data-path="assets/images/versioning-strategy-illustration-dark.svg" />
</Frame>

***

## Guarantees

<CardGroup>
  <Card title="1+ year support" icon="clock">
    Once a new version is released, it won't be sunset before at least one year.
  </Card>

  <Card title="6+ months deprecation notice" icon="bell">
    Once deprecated, a version is supported for at least 6 months.
  </Card>

  <Card title="Changelog & migration guides" icon="book">
    All changes are documented. Migration guides when needed.
  </Card>
</CardGroup>

***

## Targeting a Version

All supported versions can be found in the [API Reference](/api-reference/latest). You should always pick the latest
version for any new integration. Versions are named after their release date (e.g., `2024-11-01`).

The version must be targeted through the `Api-Version` header parameter, which is absolutely
<Icon icon="circle-exclamation" iconType="regular" color="#da2f2f" /> **required**.

<CodeGroup>
  ```http HTTP theme={null}
  GET /lucca-api/leaves HTTPS/1.1
  Host: example.ilucca.net
  Api-Version: 2024-11-01
  ```
</CodeGroup>

Notes:

* If no API version exactly matches the given date, the closest prior version is chosen by the server.
* You pin the API version when creating a webhook subscription. The pinned version dictates the
  structure of the event payload.

***

## Lifecycle Terms

All new API versions are supported for **at least 12 months**.

An API version can only be sunset after a **at least 6 months deprecation period**.

A deprecated version is marked as such in this documentation.

When the server returns a deprecated response, the `Deprecation` HTTP header indicates the deprecation date;
the complementary `Sunset` header indicates the sunset date. The sunset date may be postponed,
so it may exceed the 6-month minimum.

***

## Changelog

Each version has a changelog listing all non-breaking changes. It is
available in the [Lucca API Reference](/api-reference/latest).

<Warning>
  Some changes we consider non-breaking may nonetheless break your code, depending on your implementation / language.
</Warning>

<Card title="List of breaking changes" href="../breaking-changes">
  Learn what we consider a breaking change, i.e. what triggers the release of a new API version and the deprecation of the previous one.
</Card>