TypeScript SDK

Install the official SDK for type-safe access to all BrainstormRouter APIs.

Install

# or
pnpm add brainstormrouter

The SDK wraps the OpenAI SDK — chat.completions works identically. It adds typed namespaces for BrainstormRouter-specific APIs.

Quick start

import BrainstormRouter from "brainstormrouter";

const client = new BrainstormRouter({
  apiKey: "br_live_...", // or set BRAINSTORMROUTER_API_KEY env var
});

// OpenAI-compatible — works with LangChain, Vercel AI SDK, CrewAI, etc.
const response = await client.chat.completions.create({
  model: "anthropic/claude-sonnet-4",
  messages: [{ role: "user", content: "Hello!" }],
});

console.log(response.choices[0].message.content);

Configuration

const client = new BrainstormRouter({
  apiKey: "br_live_...",
  baseURL: "https://api.brainstormrouter.com", // default
  maxEstimatedCost: 0.1, // block requests over $0.10
  guardianOff: false, // set true to bypass Guardian
});

Option	Default	Description
apiKey	BRAINSTORMROUTER_API_KEY env	Your API key
baseURL	https://api.brainstormrouter.com	API endpoint
maxEstimatedCost	—	Max cost per request (USD)
guardianOff	false	Bypass Guardian Intelligence

Resource namespaces

The SDK organizes BrainstormRouter-specific APIs into typed namespaces:

Providers (BYOK)

// List supported providers
const catalog = await client.providers.catalog();

// Register your own key (encrypted at rest)
await client.providers.register("groq", { apiKey: "gsk_..." });

// Validate a key before storing
const result = await client.providers.test("openai", "sk-...");
console.log(result.valid); // true

// List your configured providers (keys masked)
const providers = await client.providers.list();

Presets

// Create a reusable routing config
await client.presets.create({
  slug: "fast-cheap",
  name: "Fast & Cheap",
  model: "openai/gpt-4o-mini",
  strategy: "price",
  fallbacks: ["google/gemini-2.0-flash"],
  max_cost_usd: 0.01,
});

// Use in completions
const response = await client.chat.completions.create({
  model: "@preset/fast-cheap",
  messages: [{ role: "user", content: "Quick question..." }],
});

Memory

// Read all memory entries
const { entries } = await client.memory.entries();

// Write a new fact
await client.memory.append("User prefers TypeScript over Python", {
  block: "human",
  pinned: true,
});

// Bootstrap memory from documents
await client.memory.init([
  { content: "Project uses Next.js 15...", source: "README.md" },
  { content: "Deploy target is AWS ECS...", source: "infra.md" },
]);

Prompts

// Create a prompt template
await client.prompts.create({
  id: "support-reply",
  template: "You are a {{tone}} support agent for {{company}}. {{memory.human}}",
  variables: { tone: "friendly", company: "Acme" },
  environment: "dev",
});

// Test with variables
const resolved = await client.prompts.test("support-reply", {
  variables: { tone: "professional" },
});
console.log(resolved.resolved_text);

// Promote to production
await client.prompts.promote("support-reply", 1, "prod");

// A/B test two versions
await client.prompts.startAbTest("support-reply", 1, 2, 0.5);

Guardrails

// Get current config
const { config } = await client.guardrails.getConfig();

// Enable PII scanning in block mode
await client.guardrails.updateConfig({
  enabled: true,
  mode: "block",
  providers: [
    { id: "builtin", enabled: true },
    { id: "pii", enabled: true },
  ],
});

// Test content against the pipeline
const result = await client.guardrails.test("My SSN is 123-45-6789");
console.log(result.result.safe); // false

Observability

// Add a webhook destination
await client.observability.addDestination({
  name: "My Webhook",
  type: "webhook",
  config: { url: "https://example.com/hooks/br" },
  event_types: ["usage", "error"],
});

// Enable broadcasting
await client.observability.setEnabled(true);

// Test a destination
await client.observability.testDestination("dest-uuid");

Governance

// Executive dashboard
const summary = await client.governance.summary();
console.log(summary.memory.compliant); // true
console.log(summary.memory.total_entries); // 42

// Compliance scan for PII in memory
const compliance = await client.governance.compliance();
if (!compliance.compliant) {
  console.warn(`${compliance.violations_found} PII violations found`);
}

// Audit trail
const audit = await client.governance.audit({ limit: 50, operation: "append" });

// Sleep-time refinement report
const report = await client.governance.sleepTimeReport();

MCP Gateway

// Register an external MCP server
const { server } = await client.mcp.registerServer({
  name: "My Tools",
  transport: "sse",
  url: "http://localhost:3001/sse",
});

// List available tools across all servers
const { tools } = await client.mcp.tools();

// Execute a tool
const result = await client.mcp.callTool(server.id, "search", {
  query: "latest metrics",
});

Error handling

All API errors throw BrainstormRouterError with typed status and type fields:

import { BrainstormRouterError } from "brainstormrouter";

try {
  await client.presets.get("nonexistent");
} catch (e) {
  if (e instanceof BrainstormRouterError) {
    console.error(e.message); // "Preset not found"
    console.error(e.status); // 404
    console.error(e.type); // "not_found"
  }
}

Framework compatibility

Since BrainstormRouter extends the OpenAI SDK, it works anywhere openai works:

// LangChain
import { ChatOpenAI } from "@langchain/openai";
const model = new ChatOpenAI({
  configuration: { baseURL: "https://api.brainstormrouter.com/v1" },
  apiKey: "br_live_...",
  model: "anthropic/claude-sonnet-4",
});

// Vercel AI SDK
import { createOpenAI } from "@ai-sdk/openai";
const provider = createOpenAI({
  baseURL: "https://api.brainstormrouter.com/v1",
  apiKey: "br_live_...",
});

See framework guides for detailed integration examples.