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
A service ships a change
Raíz, Agenda, Account or an integration publishes a new version of its OpenAPI document.
The API publishes a release
https://api.getarbol.commerges the documents and, if anything changed, gives them a new release. From then on the REST API and the MCP server offer it.The TypeScript SDK ships
@arbol-ai/sdkis regenerated and published on npm with a new version.The CLI ships
@arbol-ai/cliis regenerated with that SDK, verified and published with a new version.The docs sync
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 1.20261104.21009.
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 | Usually minutes later, one minor version per release that changes the API. | The package’s arbol.openapi field (see below). |
| CLI | After the SDK: usually within an hour, sometimes several hours. | arbol --version |
| Rust SDK | 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
-
Pin exact versions. In your project, install the SDK and the CLI without ranges (
--save-exacton npm): a deploy never picks up a version you haven’t tested. -
See which release the new version carries before updating:
npm view @arbol-ai/sdk arbol.openapiIt prints the release and a hash of the OpenAPI document it was generated from. Compare it with the one you use today.
-
Update on purpose: install the new version, run your tests against the API and deploy.
-
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.
Ranges and strict validation
"@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.
Exact version and tolerant reading
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
The reference shows an operation your SDK doesn't have
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 says «is not an operation of @arbol-ai/sdk; update the CLI»
The CLI and the SDK it has installed come from different releases. Install it again with npm install --global @arbol-ai/cli.
A Rust sample uses an operation your crate doesn't have
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.
A new tool doesn't show up in your MCP client
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).
Your integration started failing without you changing anything
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.