---
title: "Versiones y actualizaciones"
description: "Qué pasa cuando la API de Arbol cambia, cuándo se actualizan el SDK, la CLI, MCP y esta documentación, cómo saber qué versión usas y cómo actualizar sin sorpresas."
---

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

# Versiones y actualizaciones

La API de Arbol cambia seguido: un servicio agrega una operación, un campo o un valor nuevo. Esta página explica qué pasa entonces, cuándo lo ve cada cliente y qué hacer para que tu integración siga funcionando.

## Qué pasa cuando la API cambia

Raíz, Agenda, Cuenta o una integración publica una nueva versión de su documento OpenAPI.

`https://api.getarbol.com` une los documentos y, si algo cambió, les da un release nuevo. Desde ese momento la API REST y el servidor MCP ya lo ofrecen.

`@arbol-ai/sdk` se regenera y sale en npm con una versión nueva.

`@arbol-ai/cli` se regenera con ese SDK, se verifica y sale con una versión nueva.

La referencia de la API y sus ejemplos de código se regeneran desde el nuevo OpenAPI.

Un release se llama `1.AAAAMMDD.HMMSS`: la fecha y la hora, en UTC, en que se publicó, sin ceros a la izquierda en la hora. La referencia que ves en este sitio se generó del release .

## Cuándo lo ve cada cliente

| Cliente | Cuándo se actualiza | Cómo saber qué release trae |
| --- | --- | --- |
| API REST | Al publicarse el release. | El `info.version` de su OpenAPI. |
| Servidor MCP | Al publicarse el release. Las herramientas que ves dependen de los permisos de tu credencial. | Vuelve a pedir la lista de herramientas. |
| [SDK de TypeScript](/developers/sdks/typescript/) | Normalmente minutos después, una versión minor por cada release que cambia la API. | El campo `arbol.openapi` del paquete (ver abajo). |
| [CLI](/developers/cli/) | Después del SDK: normalmente en menos de una hora, a veces varias horas. | `arbol --version` |
| [SDK de Rust](/developers/sdks/rust/) | Se regenera a mano, así que puede ir varios releases atrás. | `arbol_sdk::RELEASE` |
| Esta documentación | La referencia de la API se sincroniza cada seis horas. Las guías se escriben a mano. | El release de arriba. |

Si algo no coincide, manda la API: el documento en vivo de `https://api.getarbol.com/openapi.json` es la fuente de verdad.

## Qué puede cambiar en un release

- **Lo más común**: una operación nueva, un campo nuevo en una respuesta, un campo opcional nuevo en una entrada o un valor nuevo en una lista de valores (un `enum`).
- **A veces**: un campo que cambia, una operación que se retira o un permiso (scope) que se exige distinto.

Las publicaciones automáticas normalmente suben la versión minor del SDK y la CLI; no detectan cambios de compatibilidad. Un cambio incompatible que se publica a propósito sube la versión mayor, como el SDK 5.0.0 y la CLI 3.0.0, que adoptaron los nombres definitivos de los recursos y de los ids en las rutas. Revisa cada release antes de actualizar.

## Cómo mantener tu integración al día

1. **Fija versiones exactas.** En tu proyecto, instala el SDK y la CLI sin rangos (`--save-exact` en npm): un despliegue nunca toma una versión que no probaste.

2. **Mira qué release trae la versión nueva** antes de actualizar:

   ```bash
   npm view @arbol-ai/sdk arbol.openapi
   ```

   Imprime el release y un hash del documento OpenAPI del que se generó. Compáralo con el que usas hoy.

3. **Actualiza a propósito**: instala la versión nueva, corre tus pruebas contra la API y despliega.

4. **Tolera lo nuevo**: lee solo los campos que usas e ignora los que no conoces; trata un valor desconocido de una lista como «otro», no como un error.

`"@arbol-ai/sdk": "^5.0.0"` en producción y un esquema que rechaza cualquier campo que no conoce: el día que la API agrega un campo, tu integración falla sin que cambies nada.

La versión exacta en tu `package.json`, una actualización deliberada con pruebas, y código que lee lo que necesita e ignora el resto.

## Cuando algo no coincide

Tu versión del SDK es anterior al release que la agregó. Actualiza el SDK. Mientras tanto, puedes llamarla por REST con la misma credencial: el método y la ruta están en su página de la referencia.

La CLI y el SDK que tiene instalado vienen de releases distintos. Vuelve a instalarla con `npm install --global @arbol-ai/cli`.

El crate de Rust se regenera a mano y puede ir atrás de la API. Compara `arbol_sdk::RELEASE` con el release de arriba; las operaciones agregadas desde entonces no están en el crate.

El servidor ya la ofrece, pero tu cliente guarda la lista de herramientas. Reconéctalo o vuelve a pedir la lista. Si sigue sin aparecer, revisa que tu credencial tenga uno de sus permisos (scopes).

Revisa si hubo un release nuevo (el `info.version` de la API) y lee el código de error de la respuesta: un `400` de validación suele ser un campo que cambió; un `403`, un permiso. Consulta [Respuestas y errores](/developers/concepts/responses-and-errors/).

Source: https://docs.getarbol.com/developers/concepts/versions/index.mdx