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

# TypeScript SDK

> Install the to11 TypeScript SDK, render a prompt, and send it through the gateway.

The `@to11ai/sdk` package gives TypeScript and JavaScript applications typed access to to11. You use it to render managed prompts, wire your own provider client to the to11 gateway with the right headers, and group calls into sessions, conversations, and turns for tracing.

The SDK is **header-only**: it talks to the to11 **platform API** (the control plane) for prompt and configuration data, but it never sends the model request itself — there is no `.chat()`. Your own provider client (OpenAI, Anthropic, or the Vercel AI SDK) sends the request through the to11 gateway at `https://gw.to11.ai`, and the SDK supplies the base URL, the headers, and the request shape.

The package is published under the MPL-2.0 license.

## Runtime requirements

* **Runtimes:** Node (both ESM and CommonJS), Bun, Deno, browsers, and edge runtimes. No minimum Node version is declared.
* **A provider client:** because the SDK is header-only, your app also installs the provider client that sends the model call — `openai`, `@anthropic-ai/sdk`, or the Vercel AI SDK.
* **Credentials:** a to11 API key and project id. The SDK runs server-side and reads `TO11_API_KEY` and `TO11_PROJECT_ID` from the environment. The control-plane and gateway URLs default to production (`https://api.to11.ai` and `https://gw.to11.ai`); override them with `TO11_API_URL` / `TO11_GATEWAY_URL` for a self-hosted to11. The gateway URL is the host only — no `/v1` path; the SDK adds the path each provider client expects.

## Installation

Install `@to11ai/sdk` alongside your provider client.

<CodeGroup>
  ```bash npm theme={null}
  npm install @to11ai/sdk openai
  ```

  ```bash pnpm theme={null}
  pnpm add @to11ai/sdk openai
  ```

  ```bash bun theme={null}
  bun add @to11ai/sdk openai
  ```

  ```bash yarn theme={null}
  yarn add @to11ai/sdk openai
  ```
</CodeGroup>

## The happy path

Create a client, render a prompt for the current environment, and send it through the gateway with your OpenAI client. Setting `format: "openai"` shapes the rendered prompt so you can spread it straight into the request; `to11.openaiOptions()` points the OpenAI client at the gateway; and `to11.turn().headers(prompt)` supplies the auth, trace, and provenance headers.

```ts theme={null}
import { createClient } from "@to11ai/sdk";
import OpenAI from "openai";

// Reads TO11_API_KEY and TO11_PROJECT_ID from the environment.
const to11 = createClient({ env: "production", format: "openai" });
const openai = new OpenAI(to11.openaiOptions());

const prompt = await to11.prompts.render("welcome-message", {
  variables: { name: "Ada" },
});

const res = await openai.chat.completions.create(
  { ...prompt.config, messages: prompt.messages },
  { headers: to11.turn().headers(prompt) },
);
```

That is the whole integration: `prompt.config` carries the model parameters, `prompt.messages` the rendered messages, and `turn().headers(prompt)` the headers that authenticate the gateway call and record which prompt produced the trace. The request runs on the model and provider you configured for the prompt; you never assemble a `provider::model` string or merge headers by hand.

<Note>
  Run the SDK server-side and keep your to11 API key there. It carries gateway access, so it must never reach the browser — the SDK throws if you pass a static `apiKey` in a browser context. See [Configuration](/docs/reference/typescript-sdk/configuration).
</Note>

## Where to next

<CardGroup cols={2}>
  <Card title="Configuration" icon="gear" href="/docs/reference/typescript-sdk/configuration">
    Client options, credential resolution, and the provider-client helpers.
  </Card>

  <Card title="Sessions, conversations & turns" icon="diagram-project" href="/docs/reference/typescript-sdk/sessions-and-turns">
    Group calls for tracing — from a single call to multi-agent, with full examples.
  </Card>

  <Card title="Rendering prompts" icon="download" href="/docs/reference/typescript-sdk/rendering-prompts">
    Formats, the rendered result shape, and the neutral converters.
  </Card>

  <Card title="Prompt management" icon="file-text" href="/docs/reference/typescript-sdk/prompts">
    Prompt lifecycle, versions, labels, and project environments.
  </Card>

  <Card title="Errors" icon="triangle-alert" href="/docs/reference/typescript-sdk/errors">
    The typed error classes the SDK throws, and how to catch them.
  </Card>
</CardGroup>