Talkory Node.js SDK

Installation

The SDK targets Node.js 18+ (or any runtime with a global fetch, such as Bun or Deno), has zero runtime dependencies (built on the platform's native fetch), and ships as a dual ESM/CJS package with bundled TypeScript declarations.

npm install talkory

Works with either module system out of the box:

// ESM / TypeScript
import { Talkory } from "talkory";

// CommonJS
const { Talkory } = require("talkory");

Quickstart

Every method is async and returns a typed Promise: result.consensus is the synthesized answer, result.commonAnswer is the content every model agreed on, and result.confidence is a 0-100 score.

import { Talkory } from "talkory";

const client = new Talkory(); // reads TALKORY_API_KEY from the environment

const result = await client.queries.run("Best commuter motorcycles under $5000?");
console.log(result.consensus);      // synthesized consensus answer
console.log(result.commonAnswer);   // what the models agreed on
console.log(result.confidence);     // 0-100
console.log(result.charged);        // USD charged for this run

queries.run() waits for every model plus the consensus before resolving (can take a few minutes); its default timeout is 130 minutes.

Authentication

Create a key at app.talkory.ai → Settings → API Keys, then either set it as an environment variable or pass it explicitly:

export TALKORY_API_KEY="tk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

import { Talkory } from "talkory";

// reads TALKORY_API_KEY automatically
const client = new Talkory();

// or pass a key explicitly
const client2 = new Talkory({ apiKey: "tk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" });

Streaming

client.queries.stream() returns an AsyncGenerator you consume with for await...of, yielding typed events as each model responds live, ending with a done event carrying the consensus.

for await (const event of client.queries.stream("Compare Python web frameworks in 2026")) {
  if (event.type === "model_chunk") {
    process.stdout.write(event.chunk);
  } else if (event.type === "done") {
    console.log("\n\nConsensus:", event.consensus);
  }
}

Events are a discriminated union on type: query_created, model_stream_start, model_chunk, model_result, model_error, round1_done, round2_start, round2_done, consensus_start, and done - TypeScript narrows the event's fields automatically once you check event.type. Any future event type your SDK version doesn't know about arrives as an UnknownEvent instead of throwing, so streams keep working across versions.

Choosing models & options

run(), create() and stream() all accept the same options object.

// default set (5 models)
await client.queries.run("...");

// explicitly include the opt-in model
await client.queries.run("...", { models: ["gpt", "claude", "kimi"] });

const result = await client.queries.run("Is a heat pump worth it in Delhi?", {
  models: ["gpt", "claude"], // subset (max 10)
  recursive: true,           // round-2 self-review before consensus
  country: "in",             // localization
});

Deferred consensus, generated later (idempotent - cached re-calls charge $0):

const result = await client.queries.run("...", { consensus: false });
const later = await client.queries.consensus(result.id);

models.list()

client.models.list() is a free call that returns the models the server has configured, as an array of ModelInfo objects:

const models = await client.models.list(); // free

Only models configured on the server are returned - a model missing from this list cannot be queried.

So the opt-in models are the ones you have to ask for by name:

const optIn = (await client.models.list()).filter((m) => m.default === false);

Key features

1. Async-first, no callbacks. Every call is a Promise or AsyncGenerator - await a result, or for await...of a stream.
2. Auto-paginating history. client.queries.list() is an async generator that walks every page for you via nextCursor.
3. Fire-and-forget. create() returns instantly with an id; call wait() later, with gentle backoff polling built in.
4. Typed errors. Every documented API error maps to a specific error class carrying code, status, and requestId.
5. Wallet safety. Paid POST requests are never auto-retried, so a network blip can't double-charge your wallet. Free idempotent GETs retry automatically on 429/500/503, honoring Retry-After.
6. Dual ESM/CJS. Works with both import and require, with bundled, correct TypeScript declarations either way.

Client reference

const result = await client.queries.run("Best commuter motorcycles under $5000?", {
  models: ["gpt", "claude", "gemini"],
  recursive: false,
});
console.log(result.consensus, result.commonAnswer, result.confidence, result.charged);

for await (const event of client.queries.stream("Compare Python web frameworks in 2026")) {
  if (event.type === "model_chunk") {
    process.stdout.write(event.chunk);
  } else if (event.type === "model_result") {
    console.log(`\n${event.modelId} scored ${event.score}`);
  } else if (event.type === "done") {
    console.log("\n\nConsensus:", event.consensus);
  }
}

const run = await client.queries.create("Best commuter bikes under $5000?");
console.log(run.id); // save this - the run continues even if you disconnect

const result = await client.queries.wait(run.id);
console.log(result.consensus);

const result = await client.queries.run("Best NAS for home use?", { consensus: false });
const consensus = await client.queries.consensus(result.id);
console.log(consensus.consensus, consensus.confidence);

const query = await client.queries.retrieve("7f9e4c2a-1b8f-4a21-9d3c-e77aa53b6c10");
console.log(query.status);

for await (const q of client.queries.list({ limit: 50 })) {
  console.log(q.id, q.prompt, q.charged);
}

console.log((await client.health.check()).status);
console.log(await client.models.list());
console.log((await client.wallet.get()).balance);
console.log((await client.usage.get({ from: "2026-06-01" })).requests.total);

Error handling

Every documented API error maps to a typed error class extending TalkoryError, carrying code, status, message, and requestId, so you can branch with instanceof or log the request id for support.

import { InsufficientBalanceError, RateLimitError, TalkoryError } from "talkory";

try {
  const result = await client.queries.run("Best commuter motorcycles under $5000?");
} catch (err) {
  if (err instanceof RateLimitError) {
    await sleep((err.retryAfter ?? 30) * 1000); // seconds
  } else if (err instanceof InsufficientBalanceError) {
    // top up at app.talkory.ai
  } else if (err instanceof TalkoryError) {
    console.error(err.code, err.status, err.requestId);
  } else {
    throw err;
  }
}

Security

FAQ

Need a key? Head to your API settings. Prefer REST or Python? See the API documentation or Python SDK docs. Package details and release history live on npm ↗, and the source is on GitHub ↗.