> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aiql.io/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeScript SDK

> Install and use the AiQL TypeScript client.

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](https://app.aiql.io)

## Install

<CodeGroup>
  ```bash npm theme={null}
  npm install @aiql.io/sdk
  ```

  ```bash pnpm theme={null}
  pnpm add @aiql.io/sdk
  ```

  ```bash yarn theme={null}
  yarn add @aiql.io/sdk
  ```
</CodeGroup>

## Authenticate

Create a client with your API key. Read the key from an environment variable instead of hardcoding it.

```typescript theme={null}
import { AiQL } from "@aiql.io/sdk";

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

To target a different environment, set the base URL. Pass `workspaceId` on the client to send it as the `AiQL-Workspace` header on every workspace-scoped call.

```typescript theme={null}
const client = new AiQL({
  apiKey: process.env.AIQL_API_KEY,
  baseUrl: "http://127.0.0.1:8000",
  workspaceId: "ws_3a1b",
});
```

## Workspaces

```typescript theme={null}
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

```typescript theme={null}
const ingestion = await client.ingestions.create({
  workspaceId: workspace.id,
  url: "https://example.com/report.pdf",
  metadata: { customerId: "abc" },
});

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

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

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

## Queries

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

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

## Sources

```typescript theme={null}
const chunks = await client.sources.chunks(ingestion.id, {
  workspaceId: workspace.id,
});

const graph = await client.sources.graph(ingestion.id, {
  workspaceId: workspace.id,
});
```

## Tools

```typescript theme={null}
const markdown = await client.tools.convert({
  url: "https://example.com/report.pdf",
});

const chunks = await client.tools.split({ markdown });

const schema = await client.tools.shape({ markdown });

const records = await client.tools.extract({ markdown, schema });
```

## Error handling

The SDK throws `AiqlError` for failed requests. Inspect `status` and `detail` to handle specific cases.

```typescript theme={null}
import { AiQL, AiqlError } from "@aiql.io/sdk";

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.status, error.detail);
  }
}
```