The TypeScript SDK wraps the AiQL API and works in Node.js and the browser with full type safety.

​
Prerequisites

  • Node.js 18 or later
  • An AiQL API key from the Dashboard

​
Install

npm install aiql

​
Authenticate

Create a client with your API key. Read the key from an environment variable instead of hardcoding it. 
import { AiQL } from "aiql";

const client = new AiQL({ apiKey: process.env.AIQL_API_KEY });
To target a different environment, set the base URL: 
const client = new AiQL({
  apiKey: process.env.AIQL_API_KEY,
  baseUrl: "http://127.0.0.1:8000",
});

​
Workspaces

const workspace = await client.workspaces.create({ name: "Analytics" });

const workspaces = await client.workspaces.list();

const fetched = await client.workspaces.get(workspace.id);

const updated = await client.workspaces.update(workspace.id, {
  name: "Analytics EU",
});

await client.workspaces.delete(workspace.id);

​
Ingestions

const ingestion = await client.ingestions.create({
  workspaceId: workspace.id,
  source: "s3://my-bucket/events.jsonl",
});

const status = await client.ingestions.get(ingestion.id);

await client.ingestions.cancel(ingestion.id);

await client.ingestions.retry(ingestion.id);

​
Queries

const query = await client.queries.create({
  workspaceId: workspace.id,
  text: "count events grouped by day",
});

const result = await client.queries.get(query.id);

​
Tools

const converted = await client.tools.convert({ data: rawRecords, to: "parquet" });

const chunks = await client.tools.split({ data: document, maxTokens: 512 });

const shaped = await client.tools.shape({ data: records, schema: targetSchema });

const fields = await client.tools.extract({
  data: document,
  fields: ["name", "email"],
});

​
Error handling

The SDK throws AiQLError for failed requests. Inspect statusCode and message to handle specific cases. 
import { AiQL, AiQLError } from "aiql";

const client = new AiQL({ apiKey: process.env.AIQL_API_KEY });

try {
  await client.queries.get("missing-id");
} catch (error) {
  if (error instanceof AiQLError) {
    console.error(error.statusCode, error.message);
  }
}