> ## 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.

# Versionado y política de deprecación

> Cómo woku versiona su API pública y cómo comunica cambios y deprecaciones, para que tus integraciones y agentes de IA se mantengan estables.

woku publica una API pública versionada para que puedas integrar con confianza y para que los agentes de IA sepan contra qué superficie construir.

## Versionado

La versión vive en la ruta de cada endpoint, con el prefijo `/v1/`. Una versión mayor es un contrato estable: mientras uses `/v1/`, woku no introduce cambios que rompan integraciones existentes.

* **Cambios compatibles** (no rompen y no cambian de versión): agregar endpoints nuevos, agregar campos opcionales a una respuesta, agregar valores nuevos a un enumerado o agregar parámetros opcionales. Tu integración debe ignorar los campos que no conoce.
* **Cambios incompatibles** (rompen): quitar o renombrar un campo o endpoint, cambiar un tipo o cambiar el comportamiento por defecto. Estos solo ocurren en una versión mayor nueva (por ejemplo `/v2/`), nunca dentro de `/v1/`.

La referencia siempre describe la versión vigente. La API v0 es una versión previa que se mantiene por compatibilidad y no recibe funcionalidades nuevas.

## Deprecación

Cuando un endpoint o una versión se marca para retiro, woku lo comunica de forma explícita y con anticipación:

* **Encabezados de respuesta**: las respuestas de un endpoint deprecado incluyen `Deprecation: true` y un encabezado `Sunset` con la fecha a partir de la cual dejará de responder (RFC 8594).
* **Aviso previo**: publicamos la deprecación en la documentación antes de la fecha de retiro, con una ruta de migración a la versión vigente.
* **Sin sorpresas**: no retiramos una versión mayor sin aviso y sin un reemplazo disponible.

## Recomendación para integraciones y agentes

* Construí contra `/v1/` y tratá los campos desconocidos como opcionales.
* Revisá los encabezados `Deprecation` y `Sunset` en cada respuesta y agendá tu migración antes de la fecha indicada.
* Ante la duda, la [referencia de la API](/docs/development/api) describe la superficie vigente.