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
Un servicio publica un cambio
Raíz, Agenda, Cuenta o una integración publica una nueva versión de su documento OpenAPI.
La API publica un release
https://api.getarbol.comune los documentos y, si algo cambió, les da un release nuevo. Desde ese momento la API REST y el servidor MCP ya lo ofrecen.El SDK de TypeScript se publica
@arbol-ai/sdkse regenera y sale en npm con una versión nueva.La CLI se publica
@arbol-ai/clise regenera con ese SDK, se verifica y sale con una versión nueva.La documentación se sincroniza
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 1.20261104.21009.
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 | Normalmente minutos después, una versión minor por cada release que cambia la API. | El campo arbol.openapi del paquete (ver abajo). |
| CLI | Después del SDK: normalmente en menos de una hora, a veces varias horas. | arbol --version |
| SDK de 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
-
Fija versiones exactas. En tu proyecto, instala el SDK y la CLI sin rangos (
--save-exacten npm): un despliegue nunca toma una versión que no probaste. -
Mira qué release trae la versión nueva antes de actualizar:
npm view @arbol-ai/sdk arbol.openapiImprime el release y un hash del documento OpenAPI del que se generó. Compáralo con el que usas hoy.
-
Actualiza a propósito: instala la versión nueva, corre tus pruebas contra la API y despliega.
-
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.
Rangos y validación estricta
"@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.
Versión exacta y lectura tolerante
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
La referencia muestra una operación que tu SDK no tiene
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 dice «is not an operation of @arbol-ai/sdk; update the CLI»
La CLI y el SDK que tiene instalado vienen de releases distintos. Vuelve a instalarla con npm install --global @arbol-ai/cli.
Un ejemplo de Rust usa una operación que tu crate no tiene
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.
Una herramienta nueva no aparece en tu cliente MCP
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).
Tu integración empezó a fallar sin que cambiaras nada
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.