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

# Versioning and deprecation policy

> How woku versions its public API and how it communicates changes and deprecations, so your integrations and AI agents stay stable.

woku publishes a versioned public API so you can integrate with confidence and so AI agents know which surface to build against.

## Versioning

The version lives in each endpoint path, with the `/v1/` prefix. A major version is a stable contract: while you use `/v1/`, woku does not introduce changes that break existing integrations.

* **Compatible changes** (non-breaking, no version bump): adding new endpoints, adding optional response fields, adding new values to an enum, or adding new optional parameters. Your integration should ignore fields it does not know.
* **Breaking changes**: removing or renaming a field or endpoint, changing a type, or changing default behavior. These only happen in a new major version (for example `/v2/`), never inside `/v1/`.

The reference always describes the current version. The v0 API is a previous version kept for compatibility and does not receive new features.

## Deprecation

When an endpoint or a version is marked for retirement, woku communicates it explicitly and in advance:

* **Response headers**: responses from a deprecated endpoint include `Deprecation: true` and a `Sunset` header with the date after which it stops responding (RFC 8594).
* **Advance notice**: we publish the deprecation in the documentation before the retirement date, with a migration path to the current version.
* **No surprises**: we do not retire a major version without notice and without a replacement available.

## Recommendation for integrations and agents

* Build against `/v1/` and treat unknown fields as optional.
* Check the `Deprecation` and `Sunset` headers on every response and schedule your migration before the stated date.
* When in doubt, the [API reference](/docs/en/development/api) describes the current surface.