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

# Versionado y deprecación

> Cómo se versiona la API de Croma, qué puede cambiar sin aviso y cómo se anuncia el retiro de un endpoint.

Los agentes se integran una vez y luego corren sin supervisión, así que el
contrato tiene que decir de antemano qué puede cambiar y con cuánto aviso.

## Versionado

Cada ruta lleva su versión mayor: `/co/rues/entity-by-nit/v1`,
`/pe/sunat/ruc/v1`, `/global/web-search/v1`. La versión es parte de la ruta,
no un encabezado, de modo que una solicitud es inequívoca por sí sola y la
descripción OpenAPI en `https://api.croma.run/openapi` (también en
`https://usecroma.com/openapi.json`) lista todas las versiones en servicio.

Dentro de una versión mayor el contrato solo crece. Estos cambios salen sin
nueva versión y sin aviso:

* Endpoints nuevos, campos opcionales nuevos en la solicitud, campos nuevos en
  la respuesta.
* Valores nuevos en campos documentados como conjuntos abiertos (estados,
  nombres y términos legales en el idioma de la fuente).
* Fuentes nuevas detrás de un endpoint existente, si la forma de la respuesta
  no cambia.

Estos cambios rompen el contrato y exigen una nueva ruta mayor (`/v2`):

* Eliminar o renombrar un campo de solicitud o de respuesta.
* Cambiar el tipo o el significado de un campo.
* Volver obligatorio un campo de solicitud opcional.
* Cambiar un `code` de error o el sobre de error.

Los nombres de campo son `snake_case` en inglés en todos los endpoints, y todo
endpoint acepta un encabezado opcional
[`Idempotency-Key`](/es/rate-limits#reintentos-e-idempotencia); esas
convenciones también son parte del contrato.

## Deprecación

Cuando una versión de un endpoint se programa para retiro:

1. Se anuncia en el [changelog](https://usecroma.com/es/changelog) (y en su
   [feed Atom](https://usecroma.com/changelog/atom.xml)) con al menos **90
   días** de anticipación a la fecha de retiro, nombrando el sucesor.
2. Desde el anuncio, cada respuesta del endpoint en retiro lleva un encabezado
   `Deprecation` ([RFC 9745](https://www.rfc-editor.org/rfc/rfc9745)) con la
   fecha en que la deprecación entró en vigor, un encabezado `Sunset`
   ([RFC 8594](https://www.rfc-editor.org/rfc/rfc8594)) con la fecha de retiro y
   un encabezado `Link` con `rel="successor-version"` apuntando al reemplazo.
3. La descripción OpenAPI marca la operación con `deprecated: true` y su
   descripción nombra el sucesor.
4. Pasada la fecha de retiro, la ruta responde `410 Gone` con el sobre de error
   estándar (`code: "endpoint_retired"`) y el mismo encabezado `Link`, durante
   al menos 90 días más.

Hoy ningún endpoint está deprecado, así que ninguna respuesta lleva estos
encabezados todavía; un cliente que revise `Deprecation` y `Sunset` en cada
respuesta se enterará de un retiro el mismo día en que se anuncie.

## Lo que esto no cubre

* El contenido de los datos. Croma devuelve los registros oficiales tal como se
  publican; que una fuente cambie lo que publica no es un cambio de la API.
  Cada guía anota los límites propios de la fuente.
* Los límites de tasa y cupos, que son por organización y pueden cambiar con tu
  plan. Se reportan en cada respuesta; consulta [Límites de tasa](/es/rate-limits).
* El servidor MCP negocia su versión de protocolo según el Model Context
  Protocol; los nombres de las herramientas siguen los ids de los endpoints
  (`rues_entity_by_nit`) y comparten el calendario de deprecación de los
  endpoints que tienen detrás.