@gavai/sdk

@gavai/sdk is the official high-level client for the gavAI public REST API. It wraps every resource in typed methods, ships request and response shapes in the same package (no separate @types install), and authenticates with a bearer token. By the end of this page you will have it installed, authenticated, and calling the 14 resource namespaces it exposes.

Install

bun add @gavai/sdk

npm install @gavai/sdk

pnpm add @gavai/sdk

yarn add @gavai/sdk

Minimal example

One file, one read call. If this prints your user_id, the SDK is wired correctly. The call below maps to .

client.ts

import { Gavai } from "@gavai/sdk";

const gv = new Gavai({
  apiKey: process.env.GAVAI_API_KEY, // gak_live_* or gak_test_*
});

const me = await gv.me.get();
console.log(me.user_id);

Run it: bun run client.ts.

Authentication

The constructor accepts exactly one token. Pass apiKey or sessionToken — never both. See Authentication for the full token lifecycle — scopes, rotation, and revocation.

The 14 resource namespaces

Every resource hangs off the Gavai instance as a typed namespace. Each namespace exposes the methods listed in the API reference for that resource.

Constructor options

Everything is passed to new Gavai({ ... }).

A composite example

This block shows the patterns you will use most: construct, inject hooks, call multiple namespaces, narrow errors by class.

composite.ts

import { Gavai, GavaiError, GavaiNetworkError } from "@gavai/sdk";

const gv = new Gavai({
  apiKey: process.env.GAVAI_API_KEY,
  baseUrl: process.env.GAVAI_BASE_URL, // optional override
  timeoutMs: 10_000,
  hooks: {
    beforeRequest: (req) => console.log("[req]", req.method, req.url),
    onError: (err) => console.error("[err]", err.message),
  },
});

try {
  const me = await gv.me.get();
  const { workspaces } = await gv.workspaces.list();

  await gv.pages.patch({
    workspace: workspaces[0].slug,
    id: "page_01H...",
    operations: [
      { op: "replace", path: "/blocks/0/props/title", value: "Hello" },
    ],
  });

  await gv.pages.publish({ workspace: workspaces[0].slug });
  console.log("Published as", me.user_id);
} catch (e) {
  if (e instanceof GavaiNetworkError) {
    // Transient — retry with backoff
  } else if (e instanceof GavaiError && e.code === "rate_limited") {
    // Read Retry-After from e.headers and back off
  } else {
    throw e;
  }
}

Errors at a glance

The SDK throws GavaiError for API-level failures and GavaiNetworkError for transport failures (DNS, connection refused, timeout). GavaiError carries status, code, message, details, and headers — headers["x-request-id"] is what you attach to a support ticket. Common code values: token_expired, insufficient_scope, rate_limited, workspace_forbidden, not_found. Full catch patterns and retry guidance live in Error handling.

Versioning

The public API is versioned by URL prefix (/v1, /v2, …). Each major SDK version tracks the matching API version — they ship together. Mixing major SDK and API versions is not supported.

JavaScript / TypeScript

Install

Minimal example

Authentication

The 14 resource namespaces

Constructor options

A composite example

Errors at a glance

Versioning

Next steps

​Install

​Minimal example

​Authentication

​The 14 resource namespaces

​Constructor options

​A composite example

​Errors at a glance

​Versioning

​Next steps

Install

Minimal example

Authentication

The 14 resource namespaces

Constructor options

A composite example

Errors at a glance

Versioning

Next steps