SDK Quickstart

The @tanzanite/sdk is a lightweight, zero-dependency TypeScript SDK. It works in browsers and Node.js 18+ (it uses native fetch).

Install

npm install @tanzanite/sdk

Create a session and follow its progress

import { Tanzanite } from "@tanzanite/sdk";

// Initialize the client with your API key
const client = new Tanzanite({ apiKey: "tanzanite_your_key_here" });

// Create a session
const session = await client.createSession({
  goal: "Design a challenging game level",
  context: { projectId: "proj_1", sceneId: "scene_main" },
});

// Poll for new messages and status until the session finishes
const TERMINAL = ["complete", "failed", "cancelled"];
let after: string | undefined;

while (true) {
  const info = await session.getInfo();

  const { messages } = await session.getMessages({ after, limit: 50 });
  for (const msg of messages) {
    console.log(`[${msg.role}] ${msg.content}`);
    after = msg.roundId; // advance the cursor so we only fetch new messages
  }

  if (info.status === "waiting_human") {
    // The agent is blocked on a question — respond, then keep polling.
    // See Sessions → Human input for choice / free-text responses.
  }

  if (TERMINAL.includes(info.status)) {
    console.log("Done:", info.status, info.completionReport ?? "");
    break;
  }

  await new Promise((r) => setTimeout(r, 2000)); // poll every 2s
}

Real-time streaming is not yet available

The SDK’s WebSocket streaming methods (session.stream(), session.on(...), session.startStreaming()) are on the roadmap but not yet wired to a server endpoint, so they will not connect. Until streaming ships, follow a session by polling session.getInfo() and session.getMessages() as shown above. The event types in Streaming Events describe the planned stream.

Configuration

Option	Type	Default	Description
apiKey	string	(required)	Your Tanzanite API key
baseUrl	string	https://api.tanzanite.dev	API base URL
wsUrl	string	(derived from baseUrl)	Reserved for streaming (not yet available)
timeout	number	30000	Request timeout in milliseconds

Self-hosted API

Point the SDK at your own deployment:

const client = new Tanzanite({
  apiKey: "tanzanite_your_key_here",
  baseUrl: "https://your-self-hosted-api.example.com",
});

Requirements

• Node.js 18+ (native fetch) or any modern browser
• TypeScript 5.4+ for development

Next steps

• Sessions — lifecycle and control.
• Streaming Events — the planned event reference.