Relay API Reference

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

SDK Client

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

const client = new BeepsClient({
  apiKey: process.env.BEEPS_API_KEY,
  baseURL: "https://api.beeps.dev", // Optional
  timeoutMs: 30000, // Optional: default 30s
  retries: {
    // Optional
    attempts: 3,
    backoffMs: 1000,
  },
});

Relay Methods

`client.relay.create(input)`

Create a new relay.

Parameters:

input: CreateRelayInput

Returns: Promise<Relay>

Example:

const relay = await client.relay.create({
  name: "Production Alerts",
  description: "Routes critical production incidents",
  externalKey: "prod-alerts",
});

`client.relay.list()`

List all relays in your organization.

Returns: Promise<Relay[]>

Example:

const relays = await client.relay.list();

`client.relay.lint(relayId, input?)`

Validate relay rules, schedules, and contact methods without side effects.

Parameters:

relayId: string
input?: RelayLintInput

Returns: Promise<RelayLintResult>

Example:

const result = await client.relay.lint("rly_abc123", {
  simulateAt: "2025-01-01T00:00:00Z",
  coverageDays: 7,
});

if (result.issues.length > 0) {
  console.log(result.issues);
}

`client.relay.simulate(relayId, input)`

Preview relay execution without sending notifications.

Parameters:

relayId: string
input: RelaySimulationInput

Returns: Promise<RelaySimulationResult>

Example:

const result = await client.relay.simulate("rly_abc123", {
  simulateAt: "2025-01-01T00:00:00Z",
  payload: {
    action: "triggered",
  },
  source: "sentry",
});

console.log(result.groups);

`client.relay.createSafe(input)`

Create a new relay without throwing exceptions.

Parameters:

input: CreateRelayInput

Returns: Promise<Result<Relay>>

Example:

const result = await client.relay.createSafe({
  name: "Production Alerts",
});

if (result.error) {
  console.error(result.error.message);
} else {
  console.log(result.data.id);
}

Relay Rules Methods

`client.relay.rules.create(relayId, input)`

Create a new rule for a relay.

Parameters:

relayId: string
input: CreateRelayRuleInput

Returns: Promise<RelayRule>

Example:

const rule = await client.relay.rules.create("rly_abc123", {
  name: "Notify on-call",
  ruleType: "schedule_notify",
  order: 1,
  config: {
    scheduleId: "sch_xyz789",
  },
});

`client.relay.rules.list(relayId, params?)`

List rules for a relay.

Parameters:

relayId: string
params?: ListRelayRulesParams
- enabled?: boolean - Filter by enabled status
- ruleType?: RelayRuleType - Filter by rule type

Returns: Promise<RelayRule[]>

Example:

const allRules = await client.relay.rules.list("rly_abc123");
const enabledRules = await client.relay.rules.list("rly_abc123", {
  enabled: true,
});

`client.relay.rules.get(relayId, ruleId)`

Get a specific rule.

Parameters:

relayId: string
ruleId: string

Returns: Promise<RelayRule>

Example:

const rule = await client.relay.rules.get("rly_abc123", "rul_xyz789");

`client.relay.rules.update(relayId, ruleId, input)`

Update a rule.

Parameters:

relayId: string
ruleId: string
input: UpdateRelayRuleInput

Returns: Promise<RelayRule>

Example:

const updatedRule = await client.relay.rules.update(
  "rly_abc123",
  "rul_xyz789",
  {
    name: "Updated rule name",
    enabled: false,
  }
);

`client.relay.rules.delete(relayId, ruleId)`

Delete a rule.

Parameters:

relayId: string
ruleId: string

Returns: Promise<{ success: boolean }>

Example:

await client.relay.rules.delete("rly_abc123", "rul_xyz789");

`client.relay.rules.reorder(relayId, input)`

Reorder rules.

Parameters:

relayId: string
input: ReorderRelayRulesInput

Returns: Promise<RelayRule[]>

Example:

const reordered = await client.relay.rules.reorder("rly_abc123", {
  rules: [
    { id: "rul_first", order: 1 },
    { id: "rul_second", order: 2 },
  ],
});

Safe Methods

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

client.relay.lintSafe(relayId, input?)
client.relay.simulateSafe(relayId, input)
client.relay.rules.listSafe(relayId, params?)
client.relay.rules.createSafe(relayId, input)
client.relay.rules.getSafe(relayId, ruleId)
client.relay.rules.updateSafe(relayId, ruleId, input)
client.relay.rules.deleteSafe(relayId, ruleId)
client.relay.rules.reorderSafe(relayId, input)

Types

RelayRuleType

type RelayRuleType =
  | "schedule_notify"
  | "webhook"
  | "agent"
  | "external_api" // deprecated
  | "wait" // deprecated
  | "conditional" // deprecated
  | "escalate"; // deprecated

ScheduleNotifyConfig

type ScheduleNotifyConfig = {
  scheduleId: string;
  notificationMethod?: "email" | "sms";
};

WebhookConfig

type WebhookConfig = {
  endpoint: string;
  method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
  headers?: Record<string, string>;
  payload?: Record<string, unknown>;
  timeout?: number; // Request timeout in ms (default 30000)
};

AgentConfig

type AgentConfig = {
  agentType: "devin" | "cursor";
  integrationId?: string; // References stored credentials
  endpoint?: string; // Override endpoint if needed
  config?: Record<string, unknown>; // Agent-specific config
  pollInterval?: number; // How often to poll in ms (default 30000)
  maxPollAttempts?: number; // Give up after N attempts (default 120)
};

RelayLintIssue

type RelayLintIssue = {
  severity: "error" | "warning" | "info";
  code: string;
  message: string;
  relayId?: string;
  ruleId?: string;
  scheduleId?: string;
  details?: Record<string, unknown>;
};

RelayLintResult

type RelayLintResult = {
  issues: RelayLintIssue[];
};

RelaySimulationResult

type RelaySimulationResult = {
  relayId: string;
  simulateAt: string;
  alertPreview: {
    title: string;
    message?: string;
    severity: "critical" | "high" | "medium" | "low" | "info";
    source: string;
    externalId?: string;
    metadata?: Record<string, unknown>;
  };
  groups: Array<{
    groupName: string;
    steps: Array<{
      ruleId: string;
      ruleType: "schedule_notify" | "webhook" | "agent" | string;
      name: string;
      enabled: boolean;
    }>;
  }>;
  issues: RelayLintIssue[];
};

HTTP Endpoints

Create Relay

POST /v0/relay

Request Body:

{
  "name": "Production Alerts",
  "description": "Routes critical production incidents",
  "externalKey": "prod-alerts"
}

List Relays

GET /v0/relay

Create Relay Rule

POST /v0/relay/:relayId/rules

List Relay Rules

GET /v0/relay/:relayId/rules
GET /v0/relay/:relayId/rules?enabled=true
GET /v0/relay/:relayId/rules?ruleType=webhook

Lint Relay

POST /v0/relay/:relayId/lint

Request Body:

{
  "simulateAt": "2025-01-01T00:00:00Z",
  "coverageDays": 7
}

Response:

{
  "issues": [
    {
      "severity": "warning",
      "code": "schedule.assignment_missing_contact_method",
      "message": "Schedule assignment has no verified contact method",
      "scheduleId": "sch_123",
      "details": {
        "userId": "usr_456"
      }
    }
  ]
}

Simulate Relay

POST /v0/relay/:relayId/simulate

Request Body:

{
  "simulateAt": "2025-01-01T00:00:00Z",
  "payload": {
    "action": "triggered"
  },
  "source": "sentry"
}

Response:

{
  "relayId": "rly_123",
  "simulateAt": "2025-01-01T00:00:00Z",
  "alertPreview": {
    "title": "Test Alert",
    "severity": "medium",
    "source": "sentry"
  },
  "groups": [],
  "issues": []
}

Get Relay Rule

GET /v0/relay/:relayId/rules/:ruleId

Update Relay Rule

PUT /v0/relay/:relayId/rules/:ruleId

Delete Relay Rule

DELETE /v0/relay/:relayId/rules/:ruleId

Reorder Relay Rules

PUT /v0/relay/:relayId/rules/reorder

Authentication

All API requests require authentication using your API key:

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