TypeScript SDK

npm install @tokz/sdk

Works in Node 20+, Bun, and Deno, with no dependencies. Only decideLocal needs more: it runs on Node.js and takes two more packages.

`new Tokz(options)`

import { Tokz } from "@tokz/sdk";

const tokz = new Tokz({
  apiKey: process.env.TOKZ_API_KEY!,
  baseUrl: "https://api.tokz.dev", // optional
});

string

required

Your key, tokz_live_<id>_<secret>.

string

default:"https://api.tokz.dev"

Override for a private endpoint or local development.

function

default:"globalThis.fetch"

Inject your own fetch for proxies, instrumentation, or tests.

`tokz.decide(request, options?)`

Typed decisions about text with the OpenDecision models. See Decisions API.

import { Tokz } from "@tokz/sdk";

const tokz = new Tokz({ apiKey: process.env.TOKZ_API_KEY! });

const out = await tokz.decide({
  inputs: ["I was charged twice.", "How do I export my data?"],
  decisions: {
    queue: { type: "choice", options: ["billing", "technical", "account"] },
    urgent: { type: "bool" },
  },
  model: "opendecision-small", // optional; the default is opendecision-large-packed
});

for (const r of out.results) console.log(r.queue.best, r.urgent.best);
console.log(out.usage.billed_tokens, out.usage.cost_usd);

no-check

decide(request: { inputs: string | string[]; decisions: Record<string, Decision>; model?: string },
       options?: { signal?: AbortSignal; timeout?: number }): Promise<DecideResponse>

timeout defaults to 60000 ms. decide is never retried, because a retry could bill twice.

`tokz.decide(model, inputs, options?)`

Calls a fine tune on our servers by name. Needs 0.7+.

import { Tokz } from "@tokz/sdk";

const tokz = new Tokz({ apiKey: process.env.TOKZ_API_KEY! });

const { results, usage } = await tokz.decide("support-triage", ["I was charged twice.", "How do I export my data?"]);

for (const r of results) console.log(r.decision.best, r.decision.selected);
console.log(usage.billed_tokens);

no-check

decide(model: string, inputs: string | string[],
       options?: { signal?: AbortSignal; timeout?: number }): Promise<FineTuneResponse>

Up to 16 texts. The answer is always under decision. For a multi-label model read selected, because best names a label even when selected is empty.

`tokz.decideLocal(model, inputs, options?)`

The same model and the same result shape, run on this machine for free. Needs 0.7+ and two more packages, about 320 MB on Linux. The flag skips a GPU library it does not use.

npm i onnxruntime-node@1.26.0 tokenizers@0.23.2 --onnxruntime-node-install=skip

import { Tokz } from "@tokz/sdk";

const tokz = new Tokz({ apiKey: process.env.TOKZ_API_KEY! });

const { results } = await tokz.decideLocal("support-triage", "I was charged twice.");
console.log(results[0].decision.best);

no-check

decideLocal(model: string, inputs: string | string[],
            options?: { signal?: AbortSignal }): Promise<FineTuneResponse>

The first call downloads the model into ~/.cache/tokz and verifies its hashes. TOKZ_CACHE_DIR moves the cache. After that it works offline, and asks the server about once an hour whether the model still exists. See Fine Tune. A bundler cannot see these two packages, so name them yourself if a tool such as Next’s standalone output copies only what it traces.

`tokz.listDecisionModels(signal?)`

The public model catalog, prices and request limits (GET /v1/decide/models). No key is sent.

`tokz.health()`

Resolves { ok, latency } and never throws, so it is safe in a readiness probe.

Errors

Class	When
`TokzError`	Any failure; `.status` carries the HTTP status when there was one, `.retryAfter` the seconds from `Retry-After`
`TokzInsufficientCreditsError`	HTTP 402; `.balanceCents` carries the reported balance

import { Tokz, TokzError, TokzInsufficientCreditsError } from "@tokz/sdk";

const tokz = new Tokz({ apiKey: process.env.TOKZ_API_KEY! });

try {
  await tokz.decide({ inputs: "charged twice", decisions: { urgent: { type: "bool" } } });
} catch (err) {
  if (err instanceof TokzInsufficientCreditsError) console.warn("out of credit", err.balanceCents);
  else if (err instanceof TokzError) console.error(err.status, err.message);
  else throw err;
}

Using Python? The Python SDK has the same methods and errors.

Getting started

Decisions API

SDKs

Advanced

API reference

`new Tokz(options)`

`tokz.decide(request, options?)`

`tokz.decide(model, inputs, options?)`

`tokz.decideLocal(model, inputs, options?)`

`tokz.listDecisionModels(signal?)`

`tokz.health()`

Errors

​new Tokz(options)

​tokz.decide(request, options?)

​tokz.decide(model, inputs, options?)

​tokz.decideLocal(model, inputs, options?)

​tokz.listDecisionModels(signal?)

​tokz.health()

​Errors

`new Tokz(options)`

`tokz.decide(request, options?)`

`tokz.decide(model, inputs, options?)`

`tokz.decideLocal(model, inputs, options?)`

`tokz.listDecisionModels(signal?)`

`tokz.health()`

Errors