API Reference

This is the complete TypeScript API reference for switchboard-ai-sdk. For a narrative walkthrough, start with the Getting Started guide.

Top-Level Exports

import {
  // Core SDK
  configure,
  discover,
  connect,

  // Server
  startSwitchboardServer,
  createSwitchboardServer,

  // Server functional helpers
  chatWithTool,
  checkAllToolsHealth,
  checkToolHealth,
  discoverTools,
  startToolAuth,

  // Errors
  ToolNotFoundError,
  ToolUnavailableError,
  ToolAuthError,
  ProviderExecutionError,
  TimeoutError,
} from "switchboard-ai-sdk";

---

configure(config)

Sets process-level provider configuration. Call once at startup. Values persist until configure() is called again.

function configure(config: ProviderConfig): void;

ProviderConfig

type ProviderConfig = {
  ollamaHost?: string;
  ollamaModel?: string;
  codexModel?: string;
  codexSandbox?: "read-only" | "workspace-write" | "danger-full-access";
  claudeCodeModel?: string;
  claudeCodeMaxTurns?: number;
  opencodeModel?: string;
};

---

discover()

Scans the local machine for installed AI tools and returns metadata for each.

function discover(): Promise<DiscoveredTool[]>;

DiscoveredTool

type DiscoveredTool = {
  id: "claude-code" | "codex" | "ollama" | "opencode";
  name: string;
  type: "agent" | "runtime" | "server" | "unknown";
  available: boolean;
  version?: string;
  capabilities: Capability[];
  models?: string[];
  defaultModel?: string;
  metadata?: Record<string, unknown>;
};

Capability

type Capability =
  | "chat"
  | "completion"
  | "model-list"
  | "agent-task"
  | "code-analysis"
  | "code-edit"
  | "health-check"
  | "embeddings";

---

connect(providerId)

Connects to a specific AI tool by provider ID.

function connect(providerId: ProviderId): Promise<ConnectedTool>;

ProviderId

type ProviderId = "claude-code" | "codex" | "ollama" | "opencode";

ConnectedTool

type ConnectedTool = {
  id: "claude-code" | "codex" | "ollama" | "opencode";
  name: string;
  type: "agent" | "runtime" | "server" | "unknown";
  capabilities: Capability[];
  models?: string[];
  defaultModel?: string;

  health(
    options?: ToolOperationOptions
  ): Promise<boolean>;

  checkAuth?(
    options?: ToolOperationOptions
  ): Promise<AuthCheckResult>;

  startAuth?(
    options?: ToolOperationOptions
  ): Promise<AuthStartResult>;

  chat(
    input: ChatInput,
    options?: ToolOperationOptions
  ): Promise<ToolResult>;
};

ToolOperationOptions

type ToolOperationOptions = {
  signal?: AbortSignal;
  timeoutMs?: number;
};

ChatInput

type ChatInput = {
  messages: Array<{
    role: "system" | "user" | "assistant";
    content: string;
  }>;
  model?: string;
};

ToolResult

type ToolResult = {
  message: {
    role: "assistant";
    content: string;
  };
  usage?: Record<string, number>;
  metadata?: Record<string, unknown>;
};

Auth Check Result

type AuthCheckResult = {
  authSupported: boolean;
  authenticated: boolean | null;
  authStatus: "authenticated" | "unauthenticated" | "not_supported" | "unknown";
  reason?: string;
  command?: string;
  output?: string;
};

Auth Start Result

type AuthStartResult = {
  status: "already_authenticated" | "started" | "unsupported" | "failed";
  authenticated: boolean | null;
  command: string;
  message?: string;
  instructions?: string;
  output?: string;
};

---

startSwitchboardServer(options)

Starts a local HTTP server that exposes the SDK over HTTP.

function startSwitchboardServer(
  options: SwitchboardServerOptions
): Promise<StartedSwitchboardServer>;

SwitchboardServerOptions

type SwitchboardServerOptions = {
  host?: string;
  port?: number;
  maxTimeoutMs?: number;
};

StartedSwitchboardServer

type StartedSwitchboardServer = {
  host: string;
  port: number;
  url: string;
  close: () => Promise<void>;
};

---

createSwitchboardServer(options)

Creates but does not start the HTTP server. Useful when you need to configure before starting.

function createSwitchboardServer(
  options: SwitchboardServerOptions
): Server;

// The returned Node.js http.Server must be started with .listen()
const server = createSwitchboardServer({ port: 3000 });
server.listen(3000, "127.0.0.1");

---

Server Endpoint Types

ChatToolRequest

type ChatToolRequest = {
  messages: Array<{
    role: "system" | "user" | "assistant";
    content: string;
  }>;
  model?: string;
  timeoutMs?: number;
};

ChatToolResponse

type ChatToolResponse = {
  toolId: string;
  type: string;
  model?: string;
  warnings?: string[];
  result: ToolResult;
  latencyMs: number;
};

DiscoverResponse

type DiscoverResponse = {
  tools: DiscoveredTool[];
};

HealthResponse

type UsageLimits = {
  status: "available" | "not_available" | "unknown";
  source?: "local_session";
  plan?: string;
  windows?: {
    five_hour?: {
      usedPercentage: number;
      remainingPercentage: number;
      resetsAt: string;
    };
    seven_day?: {
      usedPercentage: number;
      remainingPercentage: number;
      resetsAt: string;
    };
  };
  reason?: string;
};

type HealthResponse = {
  toolId: string;
  status: "healthy" | "unavailable" | "timeout" | "error";
  available: boolean;
  authSupported: boolean;
  authenticated: boolean | null;
  authStatus: "authenticated" | "unauthenticated" | "not_supported" | "unknown";
  usageLimits: UsageLimits;
  version?: string;
  reason?: string;
  latencyMs: number;
  checkedAt: string;
};

AggregateHealthResponse

type AggregateHealthResponse = {
  status: "ok";
  version: string;
  uptimeMs: number;
  tools: HealthResponse[];
};

ConfigResponse

type ConfigResponse = {
  config: ProviderConfig;
};

UpdateConfigRequest

type UpdateConfigRequest = ProviderConfig;

ToolAuthResponse

type ToolAuthResponse = {
  toolId: string;
  status: "already_authenticated" | "started" | "unsupported" | "failed";
  authenticated: boolean | null;
  command: string;
  instructions?: string;
  output?: string;
  checkedAt: string;
};

---

Error Classes

All error classes extend Error.

ToolNotFoundError

Thrown when the requested provider ID is not known or not installed.

class ToolNotFoundError extends Error {
  constructor(toolId: string);
}

ToolUnavailableError

Thrown when a provider is installed but currently unreachable.

class ToolUnavailableError extends Error {
  constructor(toolId: string, reason?: string);
}

ToolAuthError

Thrown when a provider requires authentication that hasn't been completed.

class ToolAuthError extends Error {
  constructor(toolId: string, message?: string);
}

ProviderExecutionError

Thrown when a provider accepted the request but failed to produce a valid response.

class ProviderExecutionError extends Error {
  constructor(toolId: string, reason?: string);
}

TimeoutError

Thrown when an operation exceeds the specified or default timeout.

class TimeoutError extends Error {
  constructor(message?: string);
}