TypeScript client reference

Install algenta-sdk, construct an AlgentaClient, and learn the promise-based method surface and the typed error hierarchy before you call the engine.

The TypeScript and JavaScript client is published to npm as algenta-sdk. It wraps the HTTP API in one typed AlgentaClient, works on Node.js 18+ and modern browsers, and uses fetch with no required dependencies. The method surface itself is split across four reference pages linked at the end.

Methods are camelCase, but request bodies and query parameters stay snake_case. You call getDatasetSummary(...) and queryWithMetadata(...), and the payloads you pass and receive use fields like dataset_id, source_name, and metric_column. This mirrors the HTTP contract exactly.

Install

Install the public npm package:

npm install algenta-sdk

Construct the client

new AlgentaClient(config) takes an optional config object. If you omit apiKey, the client reads it from ALGENTA_API_KEY, then the legacy DE_API_KEY. If none is set, the constructor throws with guidance rather than failing silently.

import { AlgentaClient } from "algenta-sdk";

const client = new AlgentaClient({
  apiKey: process.env.ALGENTA_API_KEY,          // falls back to DE_API_KEY, then throws
  baseUrl: "https://api.algenta.ai",            // or http://localhost:8000 for self-host
});

const models = await client.listModels();
console.log(models);

new AlgentaClient(config) accepts an AlgentaClientConfig:

Option	Type	Default	Notes
apiKey	string	ALGENTA_API_KEY, then DE_API_KEY	Required. Read from the environment if not passed.
baseUrl	string	https://api.algenta.ai (DEFAULT_BASE_URL)	Set an explicit origin for a self-hosted engine.
timeout	number	120000	Per-request timeout in milliseconds, enforced with AbortController.
maxRetries	number	3	Retries with exponential backoff; honors Retry-After on 429.
defaultHeaders	Record<string, string>	{}	Merged into every request.

A self-hosted engine needs an explicit baseUrl. The client never silently falls back to Algenta cloud — pass http://localhost:8000 (or your own origin) and the API key provisioned by that deployment.

Calls return promises

Every method returns a Promise, so use await (or .then). Streaming methods — streamChatCompletions and streamResponses — return an AsyncGenerator, so iterate them with for await.

// Awaitable request/response.
const summary = await client.getDatasetSummary("ds_nps_scores");
console.log(summary.dataset_id, summary.name);

// Streaming method: iterate the async generator.
for await (const chunk of client.streamChatCompletions({
  messages: [{ role: "user", content: "Summarize Q3 in one line." }],
})) {
  process.stdout.write(chunk.choices?.[0]?.delta?.content ?? "");
}

Errors

All client errors extend DecisionEngineError and carry a normalized errorCode, a statusCode, the raw responseBody, and a details accessor (with validationErrors for 422 bodies). Import the subclass you want to branch on.

import {
  AlgentaClient,
  AuthenticationError,
  NotFoundError,
  RateLimitError,
  ValidationError,
} from "algenta-sdk";

try {
  await client.getDataset("does-not-exist");
} catch (err) {
  if (err instanceof NotFoundError) {
    console.error("Not found:", err.errorCode);
  } else if (err instanceof RateLimitError) {
    console.error("Rate limited; retry after", err.retryAfter, "seconds");
  } else if (err instanceof AuthenticationError) {
    console.error("Check your API key");
  } else if (err instanceof ValidationError) {
    console.error("Invalid request:", err.validationErrors);
  }
}

Error	HTTP status	Retried automatically
AuthenticationError	401	No
NotFoundError	404	No
ValidationError	422	No
RateLimitError	429	Yes, honoring Retry-After up to maxRetries
ServerError	5xx	Yes, with exponential backoff
DecisionEngineError	other	Base class for the hierarchy

Branch on err.errorCode (or instanceof), not on the human-readable message. Codes are stable; messages are not.

Where to go next

Pick the method group you need — each page tables every method with its HTTP route and runnable examples.

Simulate and query

Run Monte Carlo decisions and governed data queries.

Decisions and products

Log decision memory and call the product endpoints.

Connectors and data

Manage connectors, datasets, and repository intelligence.