Alert API Reference

Complete API reference for the Alert resource in the beeps SDK.

Alert Methods

`client.alert.list()`

List all alerts in your organization.

Returns: Promise<Alert[]>

Example:

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

`client.alert.listActive()`

List all active (unresolved) alerts.

Returns: Promise<Alert[]>

Example:

const activeAlerts = await client.alert.listActive();

`client.alert.listResolved()`

List all resolved alerts.

Returns: Promise<Alert[]>

Example:

const resolvedAlerts = await client.alert.listResolved();

`client.alert.get(alertId)`

Get a specific alert by ID.

Parameters:

alertId: string

Returns: Promise<Alert>

Example:

const alert = await client.alert.get("alr_abc123");

`client.alert.onIt(alertId, input?)`

Signal that a user is responding to an alert. Creates a responder record. If userId is not provided, the authenticated user is used.

Parameters:

alertId: string
input?: OnItInput

Returns: Promise<AlertResponder>

Example:

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

// Or as the authenticated user
const responder = await client.alert.onIt("alr_abc123");

`client.alert.listResponders(alertId)`

List all responders for an alert.

Parameters:

alertId: string

Returns: Promise<AlertResponder[]>

Example:

const responders = await client.alert.listResponders("alr_abc123");

`client.alert.listAgents(alertId)`

List agent jobs associated with an alert.

Parameters:

alertId: string

Returns: Promise<AgentJob[]>

Example:

const jobs = await client.alert.listAgents("alr_abc123");

`client.alert.getFixContext(alertId)`

Get a foreground fix context bundle for an alert, including responders, agent jobs, and suggested next actions.

Parameters:

alertId: string

Returns: Promise<AlertFixContext>

Example:

const fixContext = await client.alert.getFixContext("alr_abc123");
console.log(fixContext.nextActions);

`client.alert.updateResponderStatus(alertId, responderId, input)`

Update a responder’s status to done or dropped. Optionally attach a PR URL.

Parameters:

alertId: string
responderId: string
input: UpdateResponderStatusInput

Returns: Promise<AlertResponder>

Example:

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

`client.alert.resolve(alertId)`

Mark an alert as resolved.

Parameters:

alertId: string

Returns: Promise<Alert>

Example:

const alert = await client.alert.resolve("alr_abc123");

`client.alert.assign(alertId, userId)`

Assign an alert to a user.

Parameters:

alertId: string
userId: string

Returns: Promise<Alert>

Example:

const alert = await client.alert.assign("alr_abc123", "usr_bob");

Safe Methods

All methods have corresponding *Safe variants that return Result<T> instead of throwing:

client.alert.listSafe()
client.alert.listActiveSafe()
client.alert.listResolvedSafe()
client.alert.getSafe(alertId)
client.alert.onItSafe(alertId, input?)
client.alert.listRespondersSafe(alertId)
client.alert.listAgentsSafe(alertId)
client.alert.getFixContextSafe(alertId)
client.alert.updateResponderStatusSafe(alertId, responderId, input)
client.alert.resolveSafe(alertId)
client.alert.assignSafe(alertId, userId)

Example:

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

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

Types

AlertSeverity

type AlertSeverity = "critical" | "high" | "medium" | "low" | "info";

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;
};

ResolutionSource

type ResolutionSource = "user" | "monitoring_system";

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

type ResponderType = "user" | "agent";

ResponderStatus

type ResponderStatus = "on_it" | "done" | "dropped";

OnItInput

type OnItInput = {
  userId?: string;
};

UpdateResponderStatusInput

type UpdateResponderStatusInput = {
  status: "done" | "dropped";
  prUrl?: string;
};

HTTP Endpoints

List All Alerts

GET /v0/alerts

List Active Alerts

GET /v0/alerts/active

List Resolved Alerts

GET /v0/alerts/resolved

Get Alert

GET /v0/alerts/:alertId

Respond to Alert (On It)

POST /v0/alerts/:alertId/on-it

Request Body:

{
  "userId": "usr_alice"
}

List Responders

GET /v0/alerts/:alertId/responders

List Agent Jobs for Alert

GET /v0/alerts/:alertId/agents

Get Fix Context

GET /v0/alerts/:alertId/fix-context

Update Responder Status

PATCH /v0/alerts/:alertId/responders/:responderId

Request Body:

{
  "status": "done",
  "prUrl": "https://github.com/org/repo/pull/42"
}

Resolve Alert

POST /v0/alerts/:alertId/resolve

Assign Alert

POST /v0/alerts/:alertId/assign

Request Body:

{
  "userId": "usr_bob"
}

Authentication

All API requests require authentication using your API key:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.beeps.dev/v0/alerts