Skip to main content
The @to11ai/sdk package gives TypeScript and JavaScript applications typed access to the to11 platform API. You use it to manage prompts, prompt versions, project environments, and routing rules from your own code. The SDK talks to the to11 platform API — the control plane. It does not send LLM or chat traffic. There is no .chat() method. To route model calls, you point a provider SDK (OpenAI, Anthropic, or the Vercel AI SDK) at the to11 gateway at https://gw.to11.ai/v1. See Integrations for that path. The package is published under the MPL-2.0 license. The current version is 0.4.0.

​
Installation

The package runs in Node (both ESM and CommonJS), Bun, Deno, and browser and edge runtimes. No minimum Node version is declared. Install @to11ai/sdk 0.4.0 or later. 
npm install @to11ai/sdk

​
Authentication

The SDK authenticates to the to11 API with a bearer token. It sets the standard Authorization: Bearer <to11-api-key> header for you from the credential you supply. The project is carried in the URL path, not in a header. Supply exactly one of two credential options when you construct the client:
  • apiKey — a to11 API key, for server-side use. The SDK throws if you pass apiKey in a browser context.
  • getAccessToken — an async function that returns a short-lived token, for browser and edge runtimes. The SDK calls it once per request.
Read the key from an environment variable rather than hardcoding it. 
import { createClient } from "@to11ai/sdk";

const client = createClient({
  baseUrl: "https://api.to11.ai",
  apiKey: process.env.TO11_API_KEY!,
});
Use getAccessToken instead of apiKey in any code that runs in the browser. Passing a long-lived apiKey to browser code throws, and would expose the key to end users.

​
Creating a client

createClient(options) is a factory function that returns a client. Call it directly; it is not a class, so do not use new. 
import { createClient } from "@to11ai/sdk";

const client = createClient({
  baseUrl: "https://api.to11.ai",
  apiKey: process.env.TO11_API_KEY!,
  projectId: "proj_abc123",
  env: "production",
});
The options object accepts the following fields.
OptionTypeDefaultDescription
baseUrlstring—Required. The to11 API base URL, https://api.to11.ai.
apiKeystring—A to11 API key for server-side use. Throws if used in a browser. Supply this or getAccessToken.
getAccessToken() => Promise<string>—Returns a short-lived token per request, for browser and edge runtimes. Supply this or apiKey.
projectIdstring—Required for prompts.fetch(). Validated non-empty.
envstring—Default serving environment for prompts.fetch(), for example production. Must match ^[a-z0-9-]{1,63}$.
cacheobject{ ttlSeconds: 300, maxEntries: 100 }Response cache configuration.
timeoutMsnumber30000Per-request timeout in milliseconds.
maxRetriesnumber3Maximum retry attempts for retryable failures.
The returned client exposes the namespaces prompts, projectEnvironments, and routingRules, plus the method resolveBehavior(key, codedDefault) for resolving an SDK behavior flag.

​
Resolving prompts

client.prompts.fetch(slug, options?) is the primary, environment-aware way to resolve a prompt for use at runtime. It resolves the prompt addressed by slug against the client’s projectId and env, so both must be set on the client. 
import { createClient } from "@to11ai/sdk";

const client = createClient({
  baseUrl: "https://api.to11.ai",
  apiKey: process.env.TO11_API_KEY!,
  projectId: "proj_abc123",
  env: "production",
});

const prompt = await client.prompts.fetch("welcome-message", {
  variables: { name: "Ada" },
});
console.log(prompt.messages);
client.prompts.resolve(...) is deprecated. Use fetch instead.
The prompts namespace also covers prompt lifecycle and labeling. Each method takes a single options object.
  • Prompts: create, list, get, update, archive.
  • Versions: createVersion, listVersions, getVersion.
  • Labels on a prompt: moveLabel, listLabels.
  • Project labels: listProjectLabels, createProjectLabel, getProjectLabel, updateProjectLabel, deleteProjectLabel, listProjectLabelUsages, listLabelEvents.

​
Managing routing rules

client.routingRules groups two nested resources.
  • client.routingRules.versions — create, list, get. Manages the versioned definitions of a routing rule.
  • client.routingRules.releases — set, rollback, list. Controls which rule version is released, and can roll back to a prior one.
const versions = await client.routingRules.versions.list({
  projectId: "proj_abc123",
});

await client.routingRules.releases.set({
  projectId: "proj_abc123",
  env: "production",
  versionId: versions[0].id,
});

​
Project environments

client.projectEnvironments manages the environments a project serves into. It exposes list, get, create, update, archive, and restore. Each method takes a single options object.

​
Error handling

The SDK throws typed errors. All extend To11aiError. API errors extend To11aiApiError, which carries a statusCode. Catch the specific class you care about and fall back to the base classes for the rest.
ErrorExtendsRaised when
To11aiError—Base class for all SDK errors.
To11aiApiErrorTo11aiErrorBase for API errors. Carries statusCode.
To11aiValidationErrorTo11aiApiErrorThe API rejected the request (400).
To11aiAuthErrorTo11aiApiErrorAuthentication or authorization failed (401 or 403).
To11aiRateLimitErrorTo11aiApiErrorRate limited (429). Carries retryAfterSeconds.
To11aiNetworkErrorTo11aiErrorA network failure or timeout occurred.
To11aiResponseValidationErrorTo11aiErrorA 2xx response body failed schema validation.
PromptNotFoundErrorTo11aiApiErrorThe requested prompt does not exist.
PromptLabelNotRegisteredErrorTo11aiApiErrorThe referenced prompt label is not registered.
NoActiveReleaseErrorTo11aiApiErrorNo release is active for the resolution target.
PromptPolicyViolationErrorTo11aiApiErrorA prompt policy was violated.
EnvNotFoundErrorTo11aiApiErrorThe referenced environment does not exist.
EnvNotEnabledForProviderErrorTo11aiApiErrorThe environment is not enabled for the provider.
AmbiguousEnvLabelsErrorTo11aiApiErrorThe environment labels resolve ambiguously.
RuleNotFoundErrorTo11aiApiErrorThe requested routing rule does not exist.
NoApplicableRouteErrorTo11aiApiErrorNo route applies to the request.
RuleVersionInvalidSnapshotErrorTo11aiApiErrorThe rule version snapshot is invalid.
import { createClient, PromptNotFoundError } from "@to11ai/sdk";

const client = createClient({
  baseUrl: "https://api.to11.ai",
  apiKey: process.env.TO11_API_KEY!,
  projectId: "proj_abc123",
  env: "production",
});

try {
  const prompt = await client.prompts.fetch("welcome-message");
  console.log(prompt.messages);
} catch (error) {
  if (error instanceof PromptNotFoundError) {
    // The prompt slug does not resolve in this project and environment.
  } else {
    throw error;
  }
}

​
Next steps

Python SDK

The to11 Python SDK.

API reference

The underlying HTTP API.