@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.chat(messages, opts?)	Start a streaming chat session. Returns a raw Response with SSE body (AI SDK Data Stream Protocol)

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

Error Handling

All methods throw AtlasError on failure:

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

    if (err.code === "rate_limited") {
      // Retry after the suggested delay
      await sleep(err.retryAfterSeconds! * 1000);
    }
  }
}

License

MIT