@beepsdev/sdk

TypeScript SDK for beeps — on-call alerting and incident response with AI agents.

beeps routes alerts from monitoring systems (Sentry, Datadog, Axiom, or custom webhooks) to on-call engineers and AI agents. The SDK lets you manage relays, schedules, alerts, and integrations programmatically.

Install

pnpm add @beepsdev/sdk

Quick start

import { BeepsClient } from "@beepsdev/sdk";

const beeps = new BeepsClient({
  apiKey: process.env.BEEPS_API_KEY!,
});

Relays

Relays are alert routing pipelines. Alerts come in through webhooks and get routed by rules you define.

const relay = await beeps.relay.create({
  name: "production on-call",
  description: "routes production alerts to the on-call engineer",
  externalKey: "mycompany::relay::production",
});

Relay rules

Rules control what happens when an alert hits a relay. Route to a schedule, fire a webhook, or dispatch an AI agent.

await beeps.relay.rules.create(relay.id, {
  name: "notify on-call engineer",
  ruleType: "schedule_notify",
  config: { scheduleId: "sch_primary" },
});

await beeps.relay.rules.create(relay.id, {
  name: "dispatch AI agent",
  ruleType: "agent",
  config: { integrationId: "int_devin" },
});

You can also lint and simulate relays to catch misconfigurations before they matter:

const lint = await beeps.relay.lint(relay.id);
const simulation = await beeps.relay.simulate(relay.id, {
  simulateAt: "2026-04-04T03:00:00Z",
});

Schedules

On-call schedules with daily or weekly rotations, member management, and overrides.

const schedule = await beeps.schedule.create({
  name: "primary rotation",
  relayId: relay.id,
  type: "weekly",
  handoffDay: "monday",
  handoffTime: "09:00",
});

await beeps.schedule.addMember(schedule.id, {
  email: "[email protected]",
});

const onCall = await beeps.schedule.getOnCall(schedule.id);

Overrides

Temporarily swap who's on-call without changing the rotation.

await beeps.schedule.createOverride(schedule.id, {
  userId: "usr_abc",
  startAt: "2026-04-05T00:00:00Z",
  endAt: "2026-04-06T00:00:00Z",
  reason: "covering while on PTO",
});

Alerts

List, respond to, and resolve alerts. See who's responding and which AI agents are working on it.

const active = await beeps.alert.listActive();

await beeps.alert.onIt("alt_123");

const responders = await beeps.alert.listResponders("alt_123");
const agents = await beeps.alert.listAgents("alt_123");

await beeps.alert.resolve("alt_123");

AI agent integrations

Connect AI agents (Devin, Cursor) and messaging platforms (Slack, Discord) to your relays. When an alert fires, beeps can dispatch an AI agent to start triaging automatically.

const integration = await beeps.integration.create({
  provider: "devin",
  name: "devin - production",
  apiKey: process.env.DEVIN_API_KEY!,
});

const jobs = await beeps.agentJob.list();
const status = await beeps.agentJob.getStatus("job_456");

Error handling

Methods throw typed errors by default. Use safe variants to get { data, error } instead.

import { ValidationError, NotFoundError } from "@beepsdev/sdk";

// throws on error
const relay = await beeps.relay.create({ ... });

// returns { data, error } — no try/catch needed
const { data, error } = await beeps.relay.createSafe({ ... });

if (error instanceof ValidationError) {
  console.error(error.message);
  console.error(error.details?.issues);
}

Error types: AuthError, ValidationError, NotFoundError, RateLimitError, ServerError, NetworkError, HttpError.

Client options

const beeps = new BeepsClient({
  apiKey: "...",
  baseURL: "https://beeps.dev",
  timeoutMs: 10000,
  retries: { attempts: 2, backoffMs: 1000 },
});

Resources

| Resource | Methods | |----------|---------| | relay | create, list, lint, simulate | | relay.rules | list, create, get, update, delete, reorder | | schedule | create, list, addMember, listMembers, removeMember, getOnCall, getAssignments | | schedule (overrides) | createOverride, listOverrides, updateOverride, cancelOverride | | alert | list, listActive, listResolved, get, onIt, resolve, assign, listResponders, listAgents, getFixContext | | integration | list, create, get, update, delete | | agentJob | list, get, getStatus | | member | list | | webhook | listByRelay | | contactMethod | list, delete |

Every method has a safe variant (e.g. createSafe) that returns { data, error } instead of throwing.

Docs

Full documentation at beeps.dev/docs.