> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developer.crehana.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.crehana.com/_mcp/server.

# Versionado y deprecaciones

La versión va en la ruta: todas las operaciones de la API pública están bajo
`/api/v5/rest/`. Mientras ese número no cambie, lo que ya funciona sigue
funcionando.

No hay que mandar ningún header de versión. No hay versiones por fecha ni por
organización: en un momento dado hay una sola API pública, y es la que
describe este portal.

## Qué se considera un cambio compatible

Estos cambios pueden aparecer en cualquier momento, y tu integración tiene que
tolerarlos:

* **Campos nuevos en una respuesta.** Parseá el JSON ignorando lo que no
  conocés; no valides que la respuesta tenga *exactamente* las claves que
  esperabas.
* **Parámetros opcionales nuevos** en un endpoint que ya existía.
* **Endpoints nuevos**, y secciones nuevas en la referencia.
* **Cambios en `message` y `detail`.** Son textos para que los lea una persona.
  Ramificá por el status HTTP, como dice la guía de
  [errores](/documentacion/conceptos/errores).

## Qué no cambia en silencio

Nada que pueda romper una integración andando: quitar un campo de la respuesta,
volver requerido un parámetro que era opcional, cambiar el tipo de un campo,
mover una ruta o retirar un endpoint.

Todo eso se publica en el [changelog](/changelog) antes o el mismo día en que
sale. Si un cambio afecta el contrato y no está ahí, es un error nuestro —
contános.

## El camino de una deprecación

Un endpoint no desaparece de un día para el otro. Pasa por tres etapas, y en
todas sigue respondiendo igual:

#### Se marca como deprecado

Aparece con la etiqueta **Deprecated** en la referencia, y su página dice
cuál es el reemplazo. La llamada sigue funcionando exactamente como antes.

#### Sale del portal

Deja de listarse, para que nadie que recién empieza construya sobre él. Se
anuncia en el changelog, con la tabla de qué usar en su lugar. Las
integraciones que ya lo usan no se enteran de nada: la llamada sigue
respondiendo.

#### Se retira

Recién acá deja de responder, y se anuncia antes en el changelog.

> **Note**
>
> La consecuencia práctica: si un endpoint que usás quedó marcado como deprecado,
> no es una urgencia. Pero tampoco lo dejes para siempre — migrá cuando toques esa
> parte del código, porque los reemplazos suelen traer paginación y la envoltura
> estándar, que el viejo no tenía.

## Cómo enterarte

El [changelog](/changelog) es la fuente. Lista endpoints nuevos, deprecaciones,
cambios de comportamiento y de formato de respuesta; los cambios internos que no
alteran el contrato no se listan, así que lo que hay ahí es todo lo que te puede
afectar.

Tiene un botón **Subscribe via RSS** arriba a la derecha: si tu equipo ya lee
feeds en Slack o en un lector, es la forma más barata de no tener que venir a
mirar.