TypeScript SDK

@arbol-ai/sdk is the Arbol API for TypeScript and JavaScript. It is generated from the API’s public OpenAPI document and released under the Apache 2.0 license.

Install

npm i @arbol-ai/sdk

yarn add @arbol-ai/sdk

pnpm add @arbol-ai/sdk

bun add @arbol-ai/sdk

The package is an ES module: load it with import.

Requirements

• fetch and Temporal in the runtime: Node.js 26, Bun 1.4 or a current browser. date-time fields are Temporal.Instant and date fields are Temporal.PlainDate.
• TypeScript with "lib": ["ESNext"] in tsconfig.json.

Create a client

import { createClient } from '@arbol-ai/sdk';

const arbol = createClient({
  baseUrl: 'https://api.getarbol.com',
  token: process.env.ARBOL_API_KEY!,
});

token is sent as Authorization: Bearer <token>. It is either:

• an Arbol API key, created in Account. Keep it in a secret manager and never ship it to a browser;
• an access token for the audience https://api.getarbol.com, such as a person’s session in your app.

The SDK holds no sign-in logic: sign people in the way your application does, then create a client with the token you have. See Authentication.

Call an operation

Every operation is arbol.<service>.<resource>.<verb>(request, options?), named after its operation id: raiz.agents.create is arbol.raiz.agents.create(), and nueva-eps is arbol.nuevaEps. Requests and responses are typed from the OpenAPI document.

const { data: agent } = await arbol.raiz.agents.create({
  modality: 'text',
  name: 'Appointment reminders',
  instructions: 'You remind patients of Example Clinic about upcoming appointments.',
  language: 'es-CO',
  timeZone: 'America/Bogota',
});

const { data: appointment } = await arbol.agenda.appointments.get({
  appointmentId: 'eng_0f6b2c1e-7d4a-4c3b-9e8f-1a2b3c4d5e6f',
});
appointment.startsAt; // Temporal.Instant

A method resolves with the whole response envelope, { success: true, data, error: null, metadata }, so destructure data. The second argument takes signal to abort the call, and headers or query for this request only.

A list answers one page: the items are in data.data, and data.pageInfo.nextCursor asks for the next one.

let cursor: string | undefined;
do {
  const { data: page } = await arbol.raiz.agents.list({ status: 'active', cursor });
  for (const item of page.data) console.log(item.id, item.name);
  cursor = page.pageInfo.nextCursor ?? undefined;
} while (cursor);

Import only what you use

Each service and each resource is also an entry of the package, with its own createClient, so your application bundles only what it calls:

import { createClient } from '@arbol-ai/sdk/agenda/appointments';

const appointments = createClient({
  baseUrl: 'https://api.getarbol.com',
  token: process.env.ARBOL_API_KEY!,
});

const { data } = await appointments.get({
  appointmentId: 'eng_0f6b2c1e-7d4a-4c3b-9e8f-1a2b3c4d5e6f',
});

@arbol-ai/sdk/<service> is one service (client.<resource>.<verb>) and @arbol-ai/sdk/<service>/<resource> one resource (client.<verb>), named as the SDK names them, such as agenda/appointments or nuevaEps/affiliations. Each entry exports its types and ApiError.

Errors

A response with any status outside 2xx throws ApiError, with the status, the response and, in details, the error body the API declares: { success: false, error: { code, message, retryable, data }, metadata }. A failure to reach the API rejects with the error fetch throws.

import { ApiError, type Failure } from '@arbol-ai/sdk';

try {
  await arbol.raiz.agents.get({ agentId: 'agt_01jd8x5k2m7q9r3t6v8w0y4z1b' });
} catch (error) {
  if (!(error instanceof ApiError)) throw error;
  const failure = (error.details as { error?: Failure } | undefined)?.error;
  console.error(error.status, failure?.code, error.response.headers.get('x-request-id'));
}

Each call sends one request and is never retried. Before you repeat a write that failed without a clear answer, such as 502 OUTCOME_UNKNOWN, read the current state. See Responses and errors and Retries.

The API authorizes every call: a method in the client is not a permission.

Versions

Versions follow semver. A major version brings incompatible changes: 5.0.0, for example, adopted the final names of resources and of the ids in paths. Automatic publications raise the minor version, so pin the exact version and review each release before updating.

Each version records the API release it was generated from:

npm view @arbol-ai/sdk arbol.openapi          # the latest version
npm view @arbol-ai/sdk@5.0.0 arbol.openapi   # a particular version

It prints the release (the OpenAPI document’s info.version) and a SHA-256 hash of the document’s content. Pin the exact version and verify your integration when updating (see Versions and updates).