---
title: "Versions and updates"
description: "What happens when the Arbol API changes, when the SDK, the CLI, MCP and these docs update, how to tell which version you use, and how to update without surprises."
---

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

# Versions and updates

The Arbol API changes often: a service adds an operation, a field or a new value. This page explains what happens then, when each client sees it, and what to do so your integration keeps working.

## What happens when the API changes

Raíz, Agenda, Account or an integration publishes a new version of its OpenAPI document.

`https://api.getarbol.com` merges the documents and, if anything changed, gives them a new release. From then on the REST API and the MCP server offer it.

`@arbol-ai/sdk` is regenerated and published on npm with a new version.

`@arbol-ai/cli` is regenerated with that SDK, verified and published with a new version.

The API reference and its code samples are regenerated from the new OpenAPI.

A release is named `1.YYYYMMDD.HMMSS`: the date and time, in UTC, it was published, with no leading zeros in the time. The reference on this site was generated from release .

## When each client sees it

| Client | When it updates | How to tell which release it has |
| --- | --- | --- |
| REST API | When the release is published. | The `info.version` of its OpenAPI. |
| MCP server | When the release is published. The tools you see depend on your credential's permissions. | Ask for the list of tools again. |
| [TypeScript SDK](/en/developers/sdks/typescript/) | Usually minutes later, one minor version per release that changes the API. | The package's `arbol.openapi` field (see below). |
| [CLI](/en/developers/cli/) | After the SDK: usually within an hour, sometimes several hours. | `arbol --version` |
| [Rust SDK](/en/developers/sdks/rust/) | Regenerated by hand, so it can be several releases behind. | `arbol_sdk::RELEASE` |
| These docs | The API reference syncs every six hours. The guides are written by hand. | The release above. |

If something doesn't match, the API wins: the live document at `https://api.getarbol.com/openapi.json` is the source of truth.

## What a release can change

- **Most often**: a new operation, a new field in a response, a new optional input field, or a new value in a list of values (an `enum`).
- **Sometimes**: a field that changes, an operation that's withdrawn, or a permission (scope) that's required differently.

Automatic publications normally raise the SDK and CLI minor versions; they do not detect compatibility changes. An incompatible change released on purpose raises the major version, as SDK 5.0.0 and CLI 3.0.0 did when they adopted the final names of resources and of the ids in paths. Review each release before updating.

## How to keep your integration up to date

1. **Pin exact versions.** In your project, install the SDK and the CLI without ranges (`--save-exact` on npm): a deploy never picks up a version you haven't tested.

2. **See which release the new version carries** before updating:

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

   It prints the release and a hash of the OpenAPI document it was generated from. Compare it with the one you use today.

3. **Update on purpose**: install the new version, run your tests against the API and deploy.

4. **Tolerate what's new**: read only the fields you use and ignore the ones you don't know; treat an unknown value in a list as "other", not as an error.

`"@arbol-ai/sdk": "^5.0.0"` in production and a schema that rejects any field it doesn't know: the day the API adds a field, your integration fails without you changing anything.

The exact version in your `package.json`, a deliberate update with tests, and code that reads what it needs and ignores the rest.

## When something doesn't match

Your SDK version is older than the release that added it. Update the SDK. Meanwhile, you can call it over REST with the same credential: the method and path are on its reference page.

The CLI and the SDK it has installed come from different releases. Install it again with `npm install --global @arbol-ai/cli`.

The Rust crate is regenerated by hand and can lag behind the API. Compare `arbol_sdk::RELEASE` with the release above; operations added since then aren't in the crate.

The server already offers it, but your client keeps the list of tools. Reconnect it or ask for the list again. If it still doesn't show up, check that your credential holds one of its permissions (scopes).

Check whether there was a new release (the API's `info.version`) and read the error code in the response: a validation `400` is usually a field that changed; a `403`, a permission. See [Responses and errors](/en/developers/concepts/responses-and-errors/).

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