Skip to content
beeps.dev beeps.dev

Managing Alerts

Manage alerts throughout their lifecycle.

Listing All Alerts

Section titled “Listing All Alerts”
import { BeepsClient } from "@beepsdev/sdk";


const client = new BeepsClient({
  accessToken: process.env.BEEPS_ACCESS_TOKEN,
});


const alerts = await client.alert.list();


console.log(`Found ${alerts.length} total alerts`);
alerts.forEach((alert) => {
  console.log(`[${alert.severity}] ${alert.title}`);
});

Listing Active Alerts

Section titled “Listing Active Alerts”
const activeAlerts = await client.alert.listActive();


console.log(`${activeAlerts.length} active alerts need attention`);

Safe Method

Section titled “Safe Method”
const result = await client.alert.listActiveSafe();


if (result.error) {
  console.error("Failed to list alerts:", result.error.message);
} else {
  console.log(`Active alerts: ${result.data.length}`);
}

Listing Resolved Alerts

Section titled “Listing Resolved Alerts”
const resolvedAlerts = await client.alert.listResolved();


console.log(`${resolvedAlerts.length} alerts have been resolved`);

Getting a Specific Alert

Section titled “Getting a Specific Alert”
const alert = await client.alert.get("alr_abc123");


console.log(`Title: ${alert.title}`);
console.log(`Severity: ${alert.severity}`);
console.log(`Status: ${alert.resolvedAt ? "Resolved" : "Active"}`);

Responding to an Alert

Section titled “Responding to an Alert”

Signal that you're working on an alert. This creates a responder record.

const responder = await client.alert.onIt("alr_abc123", {
  userId: "usr_alice",
});


console.log(`${responder.userId} is on it (status: ${responder.status})`);
console.log(`Joined at ${responder.joinedAt}`);

If userId is not provided, the authenticated user is used:

const responder = await client.alert.onIt("alr_abc123");

Safe Method

Section titled “Safe Method”
const result = await client.alert.onItSafe("alr_abc123", {
  userId: "usr_alice",
});


if (result.error) {
  console.error("Failed to respond:", result.error.message);
} else {
  console.log(`Responder joined: ${result.data.id}`);
}

Listing Responders

Section titled “Listing Responders”
const responders = await client.alert.listResponders("alr_abc123");


responders.forEach((r) => {
  console.log(`${r.userId || r.integrationId} — ${r.status}`);
  if (r.prUrl) {
    console.log(`  PR: ${r.prUrl}`);
  }
});

Safe Method

Section titled “Safe Method”
const result = await client.alert.listRespondersSafe("alr_abc123");


if (result.error) {
  console.error("Failed to list responders:", result.error.message);
} else {
  console.log(`${result.data.length} responders`);
}

Updating Responder Status

Section titled “Updating Responder Status”

Mark a responder as done or dropped. You can optionally attach a PR URL when completing work.

const updated = await client.alert.updateResponderStatus(
  "alr_abc123",
  "rsp_def456",
  {
    status: "done",
    prUrl: "https://github.com/org/repo/pull/42",
  },
);


console.log(`Responder status: ${updated.status}`);
console.log(`Completed at: ${updated.completedAt}`);

Safe Method

Section titled “Safe Method”
const result = await client.alert.updateResponderStatusSafe(
  "alr_abc123",
  "rsp_def456",
  { status: "done" },
);


if (result.error) {
  console.error("Failed to update:", result.error.message);
} else {
  console.log("Responder marked as done");
}

Assigning an Alert

Section titled “Assigning an Alert”
const assigned = await client.alert.assign("alr_abc123", "usr_bob");


console.log(`Alert assigned to ${assigned.assignedToUserId}`);

Safe Method

Section titled “Safe Method”
const result = await client.alert.assignSafe("alr_abc123", "usr_bob");


if (result.error) {
  console.error("Failed to assign:", result.error.message);
} else {
  console.log(`Assigned to ${result.data.assignedToUserId}`);
}

Snoozing an Alert

Section titled “Snoozing an Alert”

Temporarily silence an alert without resolving it. The alert stays active, but paging and notifications are paused until the snooze window expires, after which they resume automatically. Useful when a fix is in flight and you don't want responders re-paged in the meantime.

const snoozed = await client.alert.snooze("alr_abc123", { minutes: 30 });


console.log(`Alert snoozed until ${snoozed.snoozedUntil}`);

Safe Method

Section titled “Safe Method”
const result = await client.alert.snoozeSafe("alr_abc123", { minutes: 30 });


if (result.error) {
  console.error("Failed to snooze:", result.error.message);
} else {
  console.log(`Snoozed until ${result.data.snoozedUntil}`);
}

Resolving an Alert

Section titled “Resolving an Alert”
const resolved = await client.alert.resolve("alr_abc123");


console.log(`Alert resolved at ${resolved.resolvedAt}`);

Safe Method

Section titled “Safe Method”
const result = await client.alert.resolveSafe("alr_abc123");


if (result.error) {
  console.error("Failed to resolve:", result.error.message);
} else {
  console.log("Alert resolved");
}

Type Definitions

Section titled “Type Definitions”

Alert

Section titled “Alert”
type Alert = {
  id: string;
  organizationId: string;
  webhookId: string;
  title: string;
  message: string | null;
  severity: AlertSeverity;
  source: string;
  externalId: string | null;
  metadata: Record<string, unknown> | null;
  assignedToUserId: string | null;
  resolvedAt: string | null;
  resolvedBy: ResolutionSource | null;
  resolvedByUserId: string | null;
  resolvedByProvider: string | null;
  createdAt: string;
  updatedAt: string;
};

AlertSeverity

Section titled “AlertSeverity”
type AlertSeverity = "critical" | "high" | "medium" | "low" | "info";

ResolutionSource

Section titled “ResolutionSource”
type ResolutionSource = "user" | "monitoring_system";

AlertResponder

Section titled “AlertResponder”
type AlertResponder = {
  id: string;
  alertId: string;
  organizationId: string;
  responderType: ResponderType;
  userId: string | null;
  integrationId: string | null;
  agentSessionId: string | null;
  status: ResponderStatus;
  prUrl: string | null;
  joinedAt: string;
  completedAt: string | null;
};

ResponderType

Section titled “ResponderType”
type ResponderType = "user" | "agent";

ResponderStatus

Section titled “ResponderStatus”
type ResponderStatus = "on_it" | "done" | "dropped";

OnItInput

Section titled “OnItInput”
type OnItInput = {
  userId?: string;
};

UpdateResponderStatusInput

Section titled “UpdateResponderStatusInput”
type UpdateResponderStatusInput = {
  status: "done" | "dropped";
  prUrl?: string;
};

SnoozeInput

Section titled “SnoozeInput”
type SnoozeInput = {
  minutes: number;
};

Common Patterns

Section titled “Common Patterns”

Complete Alert Workflow

Section titled “Complete Alert Workflow”
const alertId = "alr_abc123";
const userId = "usr_alice";


const alert = await client.alert.get(alertId);
console.log(`New alert: ${alert.title}`);


const responder = await client.alert.onIt(alertId, { userId });
console.log(`On it: ${responder.status}`);


await client.alert.assign(alertId, userId);
console.log("Assigned to self");


console.log("Working on the issue...");


await client.alert.updateResponderStatus(alertId, responder.id, {
  status: "done",
  prUrl: "https://github.com/org/repo/pull/42",
});
console.log("Responder done");


await client.alert.resolve(alertId);
console.log("Resolved");

Filter Alerts by Severity

Section titled “Filter Alerts by Severity”
const active = await client.alert.listActive();


const critical = active.filter((a) => a.severity === "critical");
const high = active.filter((a) => a.severity === "high");


console.log(`Critical: ${critical.length}`);
console.log(`High: ${high.length}`);

Alert Dashboard

Section titled “Alert Dashboard”
const active = await client.alert.listActive();


const stats = {
  total: active.length,
  assigned: active.filter((a) => a.assignedToUserId).length,
  critical: active.filter((a) => a.severity === "critical").length,
};


console.log("Alert Dashboard:");
console.log(`Total Active: ${stats.total}`);
console.log(`Assigned: ${stats.assigned}`);
console.log(`Critical: ${stats.critical}`);

My Assigned Alerts

Section titled “My Assigned Alerts”
const userId = "usr_alice";
const active = await client.alert.listActive();


const myAlerts = active.filter((a) => a.assignedToUserId === userId);


console.log(`You have ${myAlerts.length} assigned alerts:`);
myAlerts.forEach((alert) => {
  console.log(`- [${alert.severity}] ${alert.title}`);
});

Troubleshooting

Section titled “Troubleshooting”

Alerts not appearing? See Troubleshooting - Alerts Not Appearing.