@openbeam/sdk

TypeScript SDK for the OpenBeam enterprise search and AI platform.

Search across 103+ connectors, query the knowledge graph, run AI agents, and manage sync operations — all from a single client.

Install

npm i @openbeam/sdk

Quick Start

import OpenBeam from "@openbeam/sdk";

const ob = new OpenBeam({ apiKey: "op_live_..." });

// Search across all connected data sources
const results = await ob.search.documents("quarterly revenue report");
console.log(results.data);

// Ask a question with RAG-powered citations
const answer = await ob.agents.ask("Who owns the authentication service?");
console.log(answer.data.answer, answer.data.citations);

Configuration

const ob = new OpenBeam({
  apiKey: "op_live_...",         // Required — from Settings > API Keys
  baseUrl: "https://api.openbeam.work", // Optional — custom endpoint
  timeout: 30_000,              // Optional — request timeout in ms (default: 30s)
  maxRetries: 2,                // Optional — retry count for transient errors (default: 2)
});

Resources

Search

// Hybrid semantic + keyword search
const results = await ob.search.documents("deployment runbook", {
  limit: 20,
  connectorTypes: ["NOTION", "CONFLUENCE"],
  ranking: "hybrid",
});

// Semantic-only search
const semantic = await ob.search.semantic("how does auth work");

// Find similar documents
const similar = await ob.search.similar("doc_abc123");

// Recent documents (last N hours)
const recent = await ob.search.recent({ hours: 24, limit: 10 });

// Documents by author
const authored = await ob.search.byAuthor("person_xyz", { limit: 10 });

// Find people
const people = await ob.search.people("engineering manager");

Connectors

// List connected data sources
const connectors = await ob.connectors.list({ status: "active" });

// Get connector details
const detail = await ob.connectors.get("conn_abc");

// Check connector health
const health = await ob.connectors.health("conn_abc");

// List available connector types
const available = await ob.connectors.available({ authType: "OAUTH" });

// Disconnect a connector
await ob.connectors.disconnect("conn_abc");

Sync

// Trigger incremental sync
const job = await ob.sync.trigger("conn_abc", "incremental");

// Trigger full re-sync
const fullJob = await ob.sync.trigger("conn_abc", "full");

// Trigger all connectors
const all = await ob.sync.triggerAll({ type: "incremental" });

// Check sync status
const status = await ob.sync.status("conn_abc");

// View sync history
const history = await ob.sync.history("conn_abc", { limit: 10 });

// Live progress
const progress = await ob.sync.progress("conn_abc");

// Fleet health overview
const fleet = await ob.sync.health();

// Recent errors
const errors = await ob.sync.errors({ limit: 20 });

// Control operations
await ob.sync.pause("conn_abc");
await ob.sync.resume("conn_abc");
await ob.sync.cancel("conn_abc");

Actions

Execute write operations across 88+ connectors (send messages, create issues, etc.).

// Discover available actions
const actions = await ob.actions.list({ connectorType: "LINEAR" });

// Execute an action
const result = await ob.actions.execute("conn_abc", "issue_create", {
  title: "Fix login bug",
  teamId: "team_123",
  priority: 1,
});

Knowledge Graph

// Search entities (people, projects, topics)
const entities = await ob.knowledge.searchEntities("authentication", {
  type: "TOPIC",
  limit: 10,
});

// Get entity details with relations
const entity = await ob.knowledge.getEntity("entity_abc");

// Get entity relations
const relations = await ob.knowledge.getRelations("entity_abc", {
  direction: "both",
});

// Find experts on a topic
const experts = await ob.knowledge.topicExperts("topic_abc");

// Get a person's expertise areas
const expertise = await ob.knowledge.personExpertise("person_abc");

// Browse topic hierarchy
const topics = await ob.knowledge.topics({ limit: 20 });

Agents

// List available agent templates
const agents = await ob.agents.list();

// Run an agent
const result = await ob.agents.run("research", "Analyze our API latency trends");

// RAG-powered Q&A with citations
const answer = await ob.agents.ask("What is our SLA for search latency?", {
  connectorTypes: ["NOTION", "CONFLUENCE"],
  maxSources: 5,
});

// Search context database
const context = await ob.agents.contextSearch("deployment procedures");

// Read a specific context entry
const entry = await ob.agents.contextRead("openbeam://resources/team_1/...", {
  level: "2",
});

Team

// Get team info
const team = await ob.team.info();

// List members
const members = await ob.team.members();

// Invite a member
await ob.team.inviteMember("[email protected]", "MEMBER");

// Update role
await ob.team.updateRole("user_abc", "ADMIN");

// Remove member
await ob.team.removeMember("user_abc");

API Keys

// List API keys
const keys = await ob.apiKeys.list();

// Create a new key
const key = await ob.apiKeys.create("CI Pipeline", [
  "search:read",
  "connectors:read",
]);
console.log(key.key); // Only shown once

// Revoke a key
await ob.apiKeys.revoke("apikey_abc");

Error Handling

import OpenBeam, {
  AuthenticationError,
  RateLimitError,
  NotFoundError,
  PermissionError,
  ToolError,
} from "@openbeam/sdk";

try {
  await ob.search.documents("test");
} catch (error) {
  if (error instanceof AuthenticationError) {
    // Invalid or missing API key (401)
  } else if (error instanceof PermissionError) {
    // Insufficient scope (403)
  } else if (error instanceof NotFoundError) {
    // Resource not found (404)
  } else if (error instanceof RateLimitError) {
    // Rate limited (429) — retryAfter available
    console.log(`Retry after ${error.retryAfter}s`);
  } else if (error instanceof ToolError) {
    // MCP tool execution failed (422)
  }
}

Request Options

Every method accepts an options object with:

interface RequestOptions {
  signal?: AbortSignal;  // Cancel the request
  timeout?: number;      // Override default timeout (ms)
}

// Example: abort after 5s
const controller = new AbortController();
setTimeout(() => controller.abort(), 5000);

await ob.search.documents("query", { signal: controller.signal });

License

Apache-2.0