SDK reference for @zindexzero/sdk

Install

It runs on Node 18+ or any modern browser. It's plain ESM (modern JavaScript modules) with no dependencies.

npm i @zindexzero/sdk

In the browser, you can skip the install and load it from a CDN: https://esm.sh/@zindexzero/sdk (see Browser & mobile).

Get a key

You need a key to use the SDK. Without one, it does nothing, and only we give out keys. Sign up at zindexzero.org/start. Once we approve you, you can make keys from your account. New keys work right away, with a limit of 1,000 requests a month. You can turn a key off at any time.

chat()

This is the main call. Pass a string, or a turn with attachments. You can also pass earlier turns. You get back the reply plus details about the call.

import { Ziz } from "@zindexzero/sdk";

const ziz = new Ziz({ apiKey: process.env.ZIZ_KEY! }); // ziz_live_…

// simplest form
const { text } = await ziz.chat("Summarize this contract");

// full turn: media (vision keys) + prior turns
const res = await ziz.chat(
  { text: "What's in this?", attachments: [{ type: "image", format: "png", data: b64 }] },
  [{ role: "user", text: "earlier message" }],
);
console.log(res.modelId, res.escalated, res.usage);

Response

usage only counts tokens. It never shows cost. Your cost in dollars (with the +20% markup already added) comes from account.usage().

Knowledge base (RAG)

RAG means Zero looks things up in your own documents before it answers. On a secret key with RAG turned on, upload your documents. Chat then answers only from your account's content. Each account's documents sit behind their own access rights, so a lookup can never cross into another account's data.

// add text or a base64 file (pdf/docx/csv/xlsx/html/txt/md)
await ziz.docs.add({ text: "Internal policy…", title: "Policy" });
await ziz.docs.add({ file: { data: b64, format: "pdf", name: "handbook.pdf" } });

// list + delete
const { documents } = await ziz.docs.list();  // [{ docId, title, format, createdAt, chunks }]
await ziz.docs.delete(documents[0].docId);

Browser & mobile

An app in a browser or on a phone can be picked apart, so it must never hold a ziz_live_ secret key. You have two safe choices:

1 · Publishable key (chat only)

import { Ziz } from "@zindexzero/sdk";
const ziz = new Ziz({ apiKey: "ziz_pub_…" }); // safe to ship; locked to your origins
const { text } = await ziz.chat("Hello");

2 · Hosted proxy (all features)

A proxy is a server that passes your calls along. We keep your secret key on our server, and your app calls the proxy by its registered name (its slug). In a browser, the page's Origin(your site's address) decides who gets in. Native apps send an app token.

import { ZizHosted } from "@zindexzero/sdk";

const zh = new ZizHosted({ client: "acme" });        // browser: Origin is the gate
// const zh = new ZizHosted({ client: "acme", appToken: "hat_…" }); // native

const { text } = await zh.chat("Summarize my docs");
await zh.docs.add({ text: "Internal note…", title: "note" });

From a CDN

<script type="module">
  import { ZizHosted } from "https://esm.sh/@zindexzero/sdk";
  const zh = new ZizHosted({ client: "acme" });
  console.log(await zh.chat("hi"));
</script>

React & React Native

useZero keeps track of the chat for you: the messages, sending, and status. It works with any client (Ziz, ZizHosted). React is a peer dependency, so you install React yourself.

import { useMemo } from "react";
import { ZizHosted } from "@zindexzero/sdk";
import { useZero } from "@zindexzero/sdk/react";

function Chat() {
  const client = useMemo(() => new ZizHosted({ client: "acme" }), []);
  const { messages, send, status, error, reset } = useZero(client);
  // render messages; call send(text) on submit; status: "idle" | "sending"
}

Account tools (server only)

Sign in with your ZiZ account to manage keys, features, personas, limits, usage, and your style profile from code. You don't need a dashboard. This code holds your account login, so never ship it in a browser bundle.

import { signIn } from "@zindexzero/sdk";

const account = await signIn({ email: process.env.ZIZ_EMAIL!, password: process.env.ZIZ_PW! });

const { keys } = await account.keys.list();
const { key } = await account.keys.create({ kind: "secret", label: "prod server" });
await account.keys.setFeature(key, { smart: true, vision: true });
await account.keys.setPersona(key, "You are Acme's warm, concise support agent.");

const { totalCostUsd } = await account.usage(); // +20% marked up server-side

Type reference

ZizKeyView

This is how a key looks when your account tools list it. It never shows the raw key or its hash.

Errors

Both error types have a .url. Your app can use it to send the user to sign up or sign in again.

Limits & cost

Our server enforces these limits and has the final say. ZIZ_LIMITS holds a copy so your code can check them too.

Cost: chat().usage only counts tokens. Dollar amounts come only from account.usage() or GET /v1/portal/usage, with the +20% service fee already added. The SDK has no price list built in.