Connect

TypeScript SDK

Call the REST API from TypeScript or JavaScript with a typed function for every route and operation, generated from the API's OpenAPI specification.

@verticalai.com.au/sdk is the REST API as typed functions. It is generated from the API's OpenAPI specification, so every route and every operation has a function, with typed path, query and body parameters and typed answers.

npm i @verticalai.com.au/sdk

It needs a runtime with fetch, such as Node 20 or later.

Authenticate

Create a personal access token under Settings > API tokens, with the access your code needs: View only to read, Edit to change agents and run tests. Keep it in an environment variable, never in the code.

import { createVerticalAiClient } from "@verticalai.com.au/sdk";

const client = createVerticalAiClient({ token: process.env.VAI_TOKEN! });

createVerticalAiClient takes token, and optionally baseUrl (by default https://app.verticalai.com.au/api/v1) and your own fetch.

The first call

import { createVerticalAiClient, listAgents } from "@verticalai.com.au/sdk";

const client = createVerticalAiClient({ token: process.env.VAI_TOKEN! });

const { data, error } = await listAgents({ client, path: { workspace: "acme" } });
if (error) throw new Error(`${error.code}: ${error.detail}`);

for (const agent of data.data) {
  console.log(agent.agent, agent.name, agent.published ? "published" : "draft only");
}

Every function takes client and the request's path, query, body and headers, and answers { data, error, response }. A route's function is named after its operation: GET /workspaces/{workspace}/agents is listAgents, and POST /workspaces/{workspace}/agents/{agent}/versions/publish is publishVersion. The API reference lists every operation.

An operation without its own route takes the agent in the body:

import { setGreetingMessage } from "@verticalai.com.au/sdk";

await setGreetingMessage({
  client,
  body: { agent: "acme/front-desk", greetingMessage: "Thanks for calling Acme Plumbing, this is Sam." },
});

A change lands on the agent's draft. When the latest version is published, open a draft first with createDraft.

Errors

error is the API's problem details object. Branch on error.code, which is stable, and show error.detail to a person. A change that deletes something, publishes, changes live calls at once or spends credit answers confirmation_required until you send confirm: true:

import { publishVersion } from "@verticalai.com.au/sdk";

const path = { workspace: "acme", agent: "front-desk" };

const first = await publishVersion({ client, path, body: {} });
if (first.error?.code === "confirmation_required") {
  console.log(first.error.detail);
  await publishVersion({ client, path, body: { confirm: true } });
}

Send confirm: true only once the person responsible has agreed. A test run's refusal carries its cost in error.estimate.

Pass throwOnError: true to have a failed call throw the problem details instead of returning them.

Pages

A list answers data, has_more and next_cursor. Pass next_cursor back as cursor, with the same filters, until it is null:

import { listCalls } from "@verticalai.com.au/sdk";

let cursor: string | undefined;
do {
  const { data, error } = await listCalls({
    client,
    path: { workspace: "acme", agent: "front-desk" },
    query: { limit: 50, cursor },
  });
  if (error) throw new Error(`${error.code}: ${error.detail}`);
  for (const call of data.data) console.log(call.sessionId);
  cursor = data.next_cursor ?? undefined;
} while (cursor);

Retry safely

Give a POST an Idempotency-Key so a retry after a timeout cannot run it twice. The API answers a repeat of the same request within 24 hours with the first answer. Retry safely has the rules.

import { duplicateAgent } from "@verticalai.com.au/sdk";
import { randomUUID } from "node:crypto";

const key = randomUUID();
const copy = await duplicateAgent({
  client,
  path: { workspace: "acme", agent: "front-desk" },
  body: { name: "Front desk (after hours)" },
  headers: { "Idempotency-Key": key },
});

Keep the key with the job, and send the same key when you retry it.

Rate limits

Each token may make 600 requests a minute. response?.headers.get("RateLimit") says how many are left. Over the limit, error.code is rate_limited and error.retryAfterSeconds says how long to wait.

On this page