> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.basement.chat/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.basement.chat/_mcp/server.

# TypeScript SDK

The package is [`@basementai/gateway`](https://www.npmjs.com/package/@basementai/gateway). The source is on [GitHub](https://github.com/Get-Basement/gateway-typescript).

## Install

```bash
npm install @basementai/gateway
```

## Create the client

```typescript
import { BasementGatewayClient } from "@basementai/gateway";

const basement = new BasementGatewayClient({
  apiKey: process.env.BASEMENT_API_KEY,
});
```

When you do not give `apiKey`, the client reads the `BASEMENT_API_KEY` environment variable.

## Call the Gateway

Each tool is a method. Arguments and answers are typed.

```typescript
// Documents
const { docs } = await basement.docs.list();
const doc = await basement.docs.read({ docId: docs[0].id });

await basement.docs.edit({
  docId: doc.id,
  oldText: "Prices are in USD",
  newText: "Prices are in BRL",
  changeSummary: "Currency",
});

// Search, and read a part of a text
const { results } = await basement.search({ query: "pricing" });
const found = await basement.text.find({ docId: doc.id, query: "discount" });

// Tasks
const { taskId } = await basement.tasks.create({ title: "Review the Q4 pricing" });
await basement.tasks.update({ taskId, status: "done" });

// Connected services
const { connected } = await basement.services.list();
const issue = await basement.services.execute({
  toolSlug: "jira__getJiraIssue",
  arguments: { issueIdOrKey: "OPS-12" },
});
```

## Handle errors

A call that the Gateway refuses throws a `BasementGatewayError` with the HTTP status and the error body.

```typescript
import { BasementGatewayError } from "@basementai/gateway";

try {
  await basement.tasks.create({ title: "Review the Q4 pricing" });
} catch (error) {
  if (error instanceof BasementGatewayError) {
    console.log(error.statusCode); // 403
    console.log(error.body);       // { error: { code: "forbidden", message: "Role lacks write access" } }
  }
}
```

See [Errors and limits](/sdks/errors-and-limits) for each status.

## Timeouts and retries

A call times out after 60 seconds. The client tries a call again, up to 2 more times, when it gets `408`, `429` or a `5xx` status. Change both for the client or for one call:

```typescript
const basement = new BasementGatewayClient({
  apiKey: process.env.BASEMENT_API_KEY,
  timeoutInSeconds: 30,
  maxRetries: 0,
});

await basement.docs.list({ timeoutInSeconds: 10, maxRetries: 3 });
```

## Another address

The client talks to `https://mcp.basement.chat`. To use another deployment, give `baseUrl`:

```typescript
const basement = new BasementGatewayClient({
  apiKey: process.env.BASEMENT_API_KEY,
  baseUrl: "http://127.0.0.1:3214",
});
```