@useatlas/sdk

@useatlas/sdk

TypeScript SDK for the Atlas text-to-SQL agent API.

Install

bun add @useatlas/sdk

Quick Start

import { createAtlasClient } from "@useatlas/sdk";

const atlas = createAtlasClient({
  baseUrl: "https://api.example.com",
  apiKey: "my-key",
});

const result = await atlas.query("How many users signed up last week?");
console.log(result.answer);
console.log(result.sql);    // SQL queries the agent executed
console.log(result.data);   // Raw query results ({ columns, rows }[])

Authentication

Pass either apiKey (simple key auth) or bearerToken (BYOT / managed auth):

// Simple API key
const atlas = createAtlasClient({ baseUrl: "...", apiKey: "my-key" });

// Bearer token (JWT from your auth provider)
const atlas = createAtlasClient({ baseUrl: "...", bearerToken: "eyJ..." });

API Reference

Query

Method	Description
atlas.query(question, opts?)	Run a synchronous query. Returns { answer, sql, data, steps, usage }
atlas.streamQuery(question, opts?)	Stream a query as an async iterator of typed StreamEvents
atlas.chat(messages, opts?)	Start a streaming chat session. Returns a raw Response with SSE body (AI SDK UI Message Stream Protocol)

Schema

Method	Description
atlas.listTables()	List all queryable tables with column details. Returns { tables: TableInfo[] }

const { tables } = await atlas.listTables();
for (const t of tables) {
  console.log(`${t.table}: ${t.description}`);
  for (const col of t.columns) {
    console.log(`  ${col.name} (${col.type}) — ${col.description}`);
  }
}

Conversations

Method	Description
atlas.conversations.list(opts?)	List conversations (paginated)
atlas.conversations.get(id)	Get a conversation with messages
atlas.conversations.delete(id)	Delete a conversation
atlas.conversations.star(id)	Star a conversation
atlas.conversations.unstar(id)	Unstar a conversation

Scheduled Tasks

Method	Description
atlas.scheduledTasks.list(opts?)	List scheduled tasks (paginated)
atlas.scheduledTasks.get(id)	Get a task with recent runs
atlas.scheduledTasks.create(input)	Create a scheduled task
atlas.scheduledTasks.update(id, input)	Update a scheduled task
atlas.scheduledTasks.delete(id)	Delete a scheduled task
atlas.scheduledTasks.trigger(id)	Trigger immediate execution
atlas.scheduledTasks.listRuns(id, opts?)	List past runs

Admin (requires admin role)

Method	Description
atlas.admin.overview()	Dashboard overview data
atlas.admin.semantic.entities()	List semantic layer entities
atlas.admin.semantic.entity(name)	Get entity detail
atlas.admin.semantic.metrics()	List metrics
atlas.admin.semantic.glossary()	Get glossary
atlas.admin.semantic.catalog()	Get catalog
atlas.admin.semantic.stats()	Aggregate semantic stats
atlas.admin.connections()	List datasource connections
atlas.admin.testConnection(id)	Test connection health
atlas.admin.audit(opts?)	Query audit log
atlas.admin.auditStats()	Aggregate audit stats
atlas.admin.plugins()	List installed plugins
atlas.admin.pluginHealth(id)	Check plugin health

Streaming

Use streamQuery() to receive typed events as the agent works:

import type { StreamEvent } from "@useatlas/sdk";

for await (const event of atlas.streamQuery("How many users signed up last week?")) {
  switch (event.type) {
    case "text":
      process.stdout.write(event.content);
      break;
    case "tool-call":
      console.log(`Calling ${event.name}`, event.args);
      break;
    case "tool-result":
      console.log(`${event.name} returned`, event.result);
      break;
    case "result":
      console.table(event.rows); // convenience: { columns, rows } from executeSQL
      break;
    case "error":
      // Mid-stream errors carry a typed `code` and a `retryAfterSeconds`
      // delta when the server emits a structured `ChatErrorInfo` body
      // (e.g. provider rate limiting). Older servers populate only `message`.
      console.error(event.code ?? "error", event.message);
      if (event.retryable && event.retryAfterSeconds !== undefined) {
        console.warn(`Server suggests retrying in ${event.retryAfterSeconds}s`);
      }
      break;
    case "parse-error":
      console.warn("Malformed SSE frame", event.raw);
      break;
    case "finish":
      console.log(`\nDone (${event.reason})`);
      break;
  }
}

Connection Drops & Partial Results

streamQuery() uses a one-shot SSE connection over fetch. If the connection drops mid-stream:

• Events already yielded are still valid — the async generator delivers each event to your for await loop before advancing, so any text, result, or tool-result events you've already processed are safe to keep.
• The generator throws an AtlasError with code network_error and a message starting with "Stream interrupted: ...".
• There is no automatic reconnect or resume — start a new streamQuery() call to retry.

import { AtlasError } from "@useatlas/sdk";

const collected: string[] = [];

try {
  for await (const event of atlas.streamQuery("Revenue by region")) {
    if (event.type === "text") collected.push(event.content);
    if (event.type === "result") console.table(event.rows);
  }
} catch (err) {
  if (err instanceof AtlasError && err.code === "network_error") {
    console.warn("Stream dropped — partial text:", collected.join(""));
    // Decide whether to retry or use the partial data you have
  } else {
    throw err;
  }
}

Cancellation

Pass an AbortSignal to cancel the stream. The signal aborts the underlying reader, and an AbortError is thrown from the for await loop. Events yielded before cancellation are already consumed by your code.

const controller = new AbortController();

// Cancel after 10 seconds
setTimeout(() => controller.abort(), 10_000);

try {
  for await (const event of atlas.streamQuery("...", { signal: controller.signal })) {
    if (event.type === "text") process.stdout.write(event.content);
  }
} catch (err) {
  if (err instanceof Error && err.name === "AbortError") {
    console.log("Stream cancelled");
  }
}

Stream Event Types

Type	Fields	Description
text	content	Text chunk from the agent
tool-call	toolCallId, name, args	Agent is calling a tool
tool-result	toolCallId, name, result	Tool returned a result
result	columns, rows	Convenience event extracted from tool-result when executeSQL returns data. Both tool-result and result are emitted.
error	message, code?, retryable?, retryAfterSeconds?, requestId?	Mid-stream error. When the server sends a structured ChatErrorInfo body (provider_rate_limit, provider_timeout, etc.) the typed code and upstream Retry-After delta travel alongside the human-readable message. Older servers populate only message.
parse-error	raw, error	Client-side: an SSE frame contained invalid JSON. The raw data is preserved for debugging.
finish	reason	Stream completed

Context Warnings (Degraded Answer Signal)

The chat route emits data-context-warning frames whenever the agent ran past a non-fatal degradation — the org semantic layer or learned-patterns lookup failed, or the workspace is approaching its plan budget — and the run was allowed to proceed against reduced context. These are not stream events from streamQuery(); they arrive on the AI-SDK UI Message Stream channel that chat() returns. If you are routing a raw Response from atlas.chat() through your own SSE consumer, parse each data-context-warning frame body with parseContextWarning from @useatlas/types:

import { parseContextWarning, type ChatContextWarning } from "@useatlas/types";

// Inside your SSE frame handler:
if (frame.type === "data-context-warning") {
  const warning: ChatContextWarning | null = parseContextWarning(frame.data);
  if (warning) {
    console.warn(`[${warning.code}]`, warning.title, warning.detail ?? "");
    // Surface a per-message warning banner — the answer is still usable
    // but was generated against reduced context. Do NOT treat it as a
    // hard error.
  } else {
    // Log on null so a future server-side wire-shape change (unknown
    // code, missing title, wrong severity literal) is observable in dev
    // rather than silently dropped. In production, gate this behind a
    // one-shot ref so a runaway stream of malformed frames doesn't
    // flood the console — see the in-tree `useContextWarnings` hook for
    // an example dedup pattern.
    console.warn("[atlas-sdk] dropped malformed data-context-warning frame", frame.data);
  }
}

The frame's severity: "warning" discriminator separates these from data-error frames, so a single SSE consumer can route both without misclassifying a degraded answer as a failure.

Error Handling

All methods throw AtlasError on failure. See the full Error Codes Reference for every error code, HTTP status, retry guidance, and a complete retry-with-backoff example.

import { AtlasError } from "@useatlas/sdk";

try {
  await atlas.query("...");
} catch (err) {
  if (err instanceof AtlasError) {
    console.error(err.code);     // e.g. "rate_limited", "auth_error"
    console.error(err.status);   // HTTP status code
    console.error(err.message);  // Human-readable message
    console.error(err.retryable); // true if retrying may help
  }
}

AtlasError Properties

Property	Type	Description
code	AtlasErrorCode	Error code (e.g. rate_limited, network_error)
status	number	HTTP status code (0 for client-side errors like network_error)
message	string	Human-readable description
retryable	boolean	Whether retrying the same request may succeed
retryAfterSeconds	number | undefined	Server-suggested delay — only populated when the server includes retryAfterSeconds in the error response body (currently only for rate_limited). Always guard against undefined

Retry with Backoff

Use retryable for generic retry logic. For rate_limited, prefer the server-suggested delay when available, falling back to exponential backoff:

import { AtlasError } from "@useatlas/sdk";

try {
  await atlas.query("...");
} catch (err) {
  if (!(err instanceof AtlasError) || !err.retryable) throw err;

  // Use server delay if available, otherwise exponential backoff
  const delay = err.retryAfterSeconds != null
    ? err.retryAfterSeconds * 1000
    : 5000;
  await new Promise((r) => setTimeout(r, delay));
  await atlas.query("...");
}

License

MIT