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