@openstatus/sdk-node

v0.1.4

Published

14 hours ago

SDK for openstatus.

0High
0Medium
0Low

maximiliankaske

thibaultleouay

OpenStatus Node.js SDK

Official Node.js SDK for OpenStatus - The open-source status page with uptime monitoring.

Features

Monitoring

HTTP Monitoring - Monitor websites and APIs with customizable assertions
TCP Monitoring - Check database connections and other TCP services
DNS Monitoring - Verify DNS records and resolution
Global Regions - Monitor from 28 locations worldwide

Status Page

Status Pages - Create and manage public status pages with custom domains
Page Components - Add monitor-based or static components with grouping
Subscribers - Manage email subscriptions for status updates
Status Reports - Manage incident reports with update timelines
Maintenance Windows - Schedule and manage planned maintenance periods

Notifications

12 Providers - Slack, Discord, Email, PagerDuty, Opsgenie, Telegram, and more
Webhook Support - Custom webhooks with headers for any integration
Monitor Alerts - Get notified when monitors go down or recover

Developer Experience

Type-safe - Full TypeScript support with generated types from protobuf
Multiple Runtimes - Works with Node.js, Deno, and Bun

Installation

npm

npm install @openstatus/sdk-node

JSR

npx jsr add @openstatus/sdk-node

Deno

import { createOpenStatusClient } from "jsr:@openstatus/sdk-node";

Quick Start

import {
  createOpenStatusClient,
  HTTPMethod,
  NumberComparator,
  Periodicity,
  Region,
} from "@openstatus/sdk-node";

// Create a client with your API key
const client = createOpenStatusClient({
  apiKey: process.env.OPENSTATUS_API_KEY,
});

// Create a monitor
const { monitor } = await client.monitor.v1.MonitorService.createHTTPMonitor({
  monitor: {
    name: "My API",
    url: "https://api.example.com/health",
    periodicity: Periodicity.PERIODICITY_1M,
    method: HTTPMethod.HTTP_METHOD_GET,
    regions: [Region.FLY_AMS, Region.FLY_IAD, Region.FLY_SYD],
    active: true,
    statusCodeAssertions: [
      { comparator: NumberComparator.EQUAL, target: BigInt(200) },
    ],
  },
});

console.log(`Monitor created: ${monitor?.id}`);

// List all monitors
const { httpMonitors, tcpMonitors, dnsMonitors, totalSize } = await client
  .monitor.v1.MonitorService.listMonitors({});

console.log(`Found ${totalSize} monitors`);

Authentication

All API requests require an API key. Get yours from the OpenStatus dashboard.

Recommended: Configure client once

import { createOpenStatusClient } from "@openstatus/sdk-node";

const client = createOpenStatusClient({
  apiKey: process.env.OPENSTATUS_API_KEY,
});

// No need to pass headers on each call
await client.monitor.v1.MonitorService.listMonitors({});

Alternative: Manual headers

import { openstatus } from "@openstatus/sdk-node";

const headers = {
  "x-openstatus-key": process.env.OPENSTATUS_API_KEY,
};

// Pass headers to each service method
await openstatus.monitor.v1.MonitorService.listMonitors({}, { headers });

Environment Variables

| Variable | Description | Default | | -------------------- | ----------------------- | -------------------------------- | | OPENSTATUS_API_KEY | Your OpenStatus API key | Required | | OPENSTATUS_API_URL | Custom API endpoint | https://api.openstatus.dev/rpc |

SDK Reference

Note: All examples below assume you've created a client:
const client = createOpenStatusClient({
  apiKey: process.env.OPENSTATUS_API_KEY,
});

Monitor Service

Manage HTTP, TCP, and DNS monitors.

`createHTTPMonitor(request)`

Create an HTTP/HTTPS monitor.

import {
  createOpenStatusClient,
  HTTPMethod,
  Periodicity,
  Region,
} from "@openstatus/sdk-node";

const { monitor } = await client.monitor.v1.MonitorService.createHTTPMonitor({
  monitor: {
    name: "My Website",
    url: "https://example.com",
    periodicity: Periodicity.PERIODICITY_1M,
    method: HTTPMethod.HTTP_METHOD_GET,
    regions: [Region.FLY_AMS, Region.FLY_IAD, Region.FLY_SYD],
    active: true,
  },
});

`updateHTTPMonitor(request)`

Update an existing HTTP monitor.

const { monitor } = await client.monitor.v1.MonitorService.updateHTTPMonitor({
  id: "mon_123",
  monitor: {
    name: "Updated Name",
    active: false,
  },
});

`createTCPMonitor(request)`

Create a TCP connection monitor.

const { monitor } = await client.monitor.v1.MonitorService.createTCPMonitor({
  monitor: {
    name: "Database",
    uri: "db.example.com:5432",
    periodicity: Periodicity.PERIODICITY_5M,
    regions: [Region.FLY_AMS, Region.FLY_IAD],
    active: true,
  },
});

`updateTCPMonitor(request)`

Update an existing TCP monitor.

const { monitor } = await client.monitor.v1.MonitorService.updateTCPMonitor({
  id: "mon_123",
  monitor: {
    name: "Updated Database Monitor",
  },
});

`createDNSMonitor(request)`

Create a DNS resolution monitor.

import { Periodicity, RecordComparator, Region } from "@openstatus/sdk-node";

const { monitor } = await client.monitor.v1.MonitorService.createDNSMonitor({
  monitor: {
    name: "DNS Check",
    uri: "example.com",
    periodicity: Periodicity.PERIODICITY_10M,
    regions: [Region.FLY_AMS],
    active: true,
    recordAssertions: [
      {
        record: "A",
        comparator: RecordComparator.EQUAL,
        target: "93.184.216.34",
      },
    ],
  },
});

`updateDNSMonitor(request)`

Update an existing DNS monitor.

const { monitor } = await client.monitor.v1.MonitorService.updateDNSMonitor({
  id: "mon_123",
  monitor: {
    name: "Updated DNS Check",
  },
});

`listMonitors(request)`

List all monitors with pagination. Returns monitors grouped by type.

const { httpMonitors, tcpMonitors, dnsMonitors, nextPageToken, totalSize } =
  await client.monitor.v1.MonitorService.listMonitors({
    pageSize: 10,
    pageToken: "",
  });

`getMonitor(request)`

Get a single monitor by ID. Returns the monitor configuration (HTTP, TCP, or DNS).

const { monitor } = await client.monitor.v1.MonitorService.getMonitor({
  id: "mon_123",
});

// Handle the monitor type
if (monitor?.config.case === "http") {
  console.log(`HTTP Monitor: ${monitor.config.value.name}`);
} else if (monitor?.config.case === "tcp") {
  console.log(`TCP Monitor: ${monitor.config.value.name}`);
} else if (monitor?.config.case === "dns") {
  console.log(`DNS Monitor: ${monitor.config.value.name}`);
}

`triggerMonitor(request)`

Trigger an immediate check.

const { success } = await client.monitor.v1.MonitorService.triggerMonitor({
  id: "mon_123",
});

`deleteMonitor(request)`

Delete a monitor.

const { success } = await client.monitor.v1.MonitorService.deleteMonitor({
  id: "mon_123",
});

`getMonitorStatus(request)`

Get the current status of a monitor across all configured regions.

import { MonitorStatus, Region } from "@openstatus/sdk-node";

const { id, regions } = await client.monitor.v1.MonitorService.getMonitorStatus(
  { id: "mon_123" },
);

for (const { region, status } of regions) {
  console.log(`${Region[region]}: ${MonitorStatus[status]}`);
}

`getMonitorSummary(request)`

Get aggregated metrics and latency percentiles for a monitor.

import { TimeRange } from "@openstatus/sdk-node";

const summary = await client.monitor.v1.MonitorService.getMonitorSummary({
  id: "mon_123",
  timeRange: TimeRange.TIME_RANGE_7D,
  regions: [], // optional: filter by specific regions
});

console.log(`Last ping: ${summary.lastPingAt}`);
console.log(`Success: ${summary.totalSuccessful}`);
console.log(`Failed: ${summary.totalFailed}`);
console.log(`P50 latency: ${summary.p50}ms`);
console.log(`P95 latency: ${summary.p95}ms`);
console.log(`P99 latency: ${summary.p99}ms`);

Health Service

Check API health status (no authentication required).

import { openstatus, ServingStatus } from "@openstatus/sdk-node";

const { status } = await openstatus.health.v1.HealthService.check({});
console.log(ServingStatus[status]); // "SERVING"

Status Report Service

Manage incident reports with update timelines.

`createStatusReport(request)`

Create a new status report.

import { StatusReportStatus } from "@openstatus/sdk-node";

const { statusReport } = await client.statusReport.v1.StatusReportService
  .createStatusReport({
    title: "API Degradation",
    status: StatusReportStatus.INVESTIGATING,
    message: "We are investigating reports of increased latency.",
    date: "2024-01-15T10:30:00Z",
    pageId: "page_123",
    pageComponentIds: ["comp_456"],
    notify: true,
  });

console.log(`Status report created: ${statusReport?.id}`);

`getStatusReport(request)`

Get a status report by ID (includes full update timeline).

import { StatusReportStatus } from "@openstatus/sdk-node";

const { statusReport } = await client.statusReport.v1.StatusReportService
  .getStatusReport({
    id: "sr_123",
  });

console.log(`Title: ${statusReport?.title}`);
console.log(`Status: ${StatusReportStatus[statusReport?.status ?? 0]}`);

for (const update of statusReport?.updates ?? []) {
  console.log(`${update.date}: ${update.message}`);
}

`listStatusReports(request)`

List all status reports with pagination and optional filtering.

import { StatusReportStatus } from "@openstatus/sdk-node";

const { statusReports, totalSize } = await client.statusReport.v1
  .StatusReportService.listStatusReports({
    limit: 10,
    offset: 0,
    statuses: [StatusReportStatus.INVESTIGATING, StatusReportStatus.IDENTIFIED],
  });

console.log(`Found ${totalSize} status reports`);

`updateStatusReport(request)`

Update status report metadata.

const { statusReport } = await client.statusReport.v1.StatusReportService
  .updateStatusReport({
    id: "sr_123",
    title: "Updated Title",
    pageComponentIds: ["comp_456", "comp_789"],
  });

`deleteStatusReport(request)`

Delete a status report and all its updates.

const { success } = await client.statusReport.v1.StatusReportService
  .deleteStatusReport({
    id: "sr_123",
  });

`addStatusReportUpdate(request)`

Add a new update to an existing status report timeline.

import { StatusReportStatus } from "@openstatus/sdk-node";

const { statusReport } = await client.statusReport.v1.StatusReportService
  .addStatusReportUpdate({
    statusReportId: "sr_123",
    status: StatusReportStatus.IDENTIFIED,
    message: "The issue has been identified as a database connection problem.",
    date: "2024-01-15T11:00:00Z", // optional, defaults to current time
    notify: true,
  });

Status Page Service

Manage status pages, components, and subscribers.

`createStatusPage(request)`

Create a new status page.

const { statusPage } = await client.statusPage.v1.StatusPageService
  .createStatusPage({
    title: "My Service Status",
    slug: "my-service",
    description: "Status page for My Service",
    homepageUrl: "https://example.com",
    contactUrl: "https://example.com/contact",
  });

console.log(`Status page created: ${statusPage?.id}`);

`getStatusPage(request)`

Get a status page by ID.

const { statusPage } = await client.statusPage.v1.StatusPageService
  .getStatusPage({
    id: "page_123",
  });

`listStatusPages(request)`

List all status pages with pagination.

const { statusPages, totalSize } = await client.statusPage.v1.StatusPageService
  .listStatusPages({ limit: 10, offset: 0 });

console.log(`Found ${totalSize} status pages`);

`updateStatusPage(request)`

Update a status page.

const { statusPage } = await client.statusPage.v1.StatusPageService
  .updateStatusPage({
    id: "page_123",
    title: "Updated Title",
    description: "Updated description",
  });

`deleteStatusPage(request)`

Delete a status page.

const { success } = await client.statusPage.v1.StatusPageService
  .deleteStatusPage({
    id: "page_123",
  });

`addMonitorComponent(request)`

Add a monitor-based component to a status page.

const { component } = await client.statusPage.v1.StatusPageService
  .addMonitorComponent({
    pageId: "page_123",
    monitorId: "mon_456",
    name: "API Server",
    description: "Main API endpoint",
    order: 1,
  });

`addStaticComponent(request)`

Add a static component (not linked to a monitor).

const { component } = await client.statusPage.v1.StatusPageService
  .addStaticComponent({
    pageId: "page_123",
    name: "Third-party Service",
    description: "External dependency",
    order: 2,
  });

`updateComponent(request)`

Update a component.

const { component } = await client.statusPage.v1.StatusPageService
  .updateComponent({
    id: "comp_123",
    name: "Updated Component Name",
    order: 3,
  });

`removeComponent(request)`

Remove a component from a status page.

const { success } = await client.statusPage.v1.StatusPageService
  .removeComponent({
    id: "comp_123",
  });

`createComponentGroup(request)`

Create a component group.

const { group } = await client.statusPage.v1.StatusPageService
  .createComponentGroup({
    pageId: "page_123",
    name: "Core Services",
  });

`updateComponentGroup(request)`

Update a component group.

const { group } = await client.statusPage.v1.StatusPageService
  .updateComponentGroup({
    id: "group_123",
    name: "Updated Group Name",
  });

`deleteComponentGroup(request)`

Delete a component group.

const { success } = await client.statusPage.v1.StatusPageService
  .deleteComponentGroup({
    id: "group_123",
  });

`subscribeToPage(request)`

Subscribe an email to status page updates.

const { subscriber } = await client.statusPage.v1.StatusPageService
  .subscribeToPage({
    pageId: "page_123",
    email: "[email protected]",
  });

`unsubscribeFromPage(request)`

Unsubscribe from a status page.

// By email
const { success } = await client.statusPage.v1.StatusPageService
  .unsubscribeFromPage({
    pageId: "page_123",
    identifier: { case: "email", value: "[email protected]" },
  });

// Or by subscriber ID
const { success: success2 } = await client.statusPage.v1.StatusPageService
  .unsubscribeFromPage({
    pageId: "page_123",
    identifier: { case: "id", value: "sub_456" },
  });

`listSubscribers(request)`

List all subscribers for a status page.

const { subscribers, totalSize } = await client.statusPage.v1.StatusPageService
  .listSubscribers({
    pageId: "page_123",
    limit: 50,
    offset: 0,
    includeUnsubscribed: false,
  });

`getStatusPageContent(request)`

Get full status page content including components, groups, and active reports.

const content = await client.statusPage.v1.StatusPageService
  .getStatusPageContent({
    identifier: { case: "slug", value: "my-service" },
  });

console.log(`Page: ${content.statusPage?.title}`);
console.log(`Components: ${content.components.length}`);
console.log(`Active reports: ${content.statusReports.length}`);

`getOverallStatus(request)`

Get the aggregated status of a status page.

import { OverallStatus } from "@openstatus/sdk-node";

const { overallStatus, componentStatuses } = await client.statusPage.v1
  .StatusPageService.getOverallStatus({
    identifier: { case: "id", value: "page_123" },
  });

console.log(`Overall: ${OverallStatus[overallStatus]}`);
for (const { componentId, status } of componentStatuses) {
  console.log(`  ${componentId}: ${OverallStatus[status]}`);
}

Maintenance Service

Manage scheduled maintenance windows.

`createMaintenance(request)`

Create a new maintenance window.

const { maintenance } = await client.maintenance.v1.MaintenanceService
  .createMaintenance({
    title: "Database Upgrade",
    message: "We will be upgrading our database infrastructure.",
    from: "2024-01-20T02:00:00Z",
    to: "2024-01-20T04:00:00Z",
    pageId: "page_123",
    pageComponentIds: ["comp_456"],
    notify: true,
  });

console.log(`Maintenance created: ${maintenance?.id}`);

`getMaintenance(request)`

Get a maintenance window by ID.

const { maintenance } = await client.maintenance.v1.MaintenanceService
  .getMaintenance({
    id: "maint_123",
  });

console.log(`Title: ${maintenance?.title}`);
console.log(`From: ${maintenance?.from}`);
console.log(`To: ${maintenance?.to}`);

`listMaintenances(request)`

List all maintenance windows with pagination and optional filtering.

const { maintenances, totalSize } = await client.maintenance.v1
  .MaintenanceService.listMaintenances({
    limit: 10,
    offset: 0,
    pageId: "page_123", // optional filter
  });

console.log(`Found ${totalSize} maintenance windows`);

`updateMaintenance(request)`

Update a maintenance window.

const { maintenance } = await client.maintenance.v1.MaintenanceService
  .updateMaintenance({
    id: "maint_123",
    title: "Extended Database Upgrade",
    to: "2024-01-20T06:00:00Z",
  });

`deleteMaintenance(request)`

Delete a maintenance window.

const { success } = await client.maintenance.v1.MaintenanceService
  .deleteMaintenance({
    id: "maint_123",
  });

Notification Service

Manage notification channels for monitor alerts. Supports 12 providers including Slack, Discord, Email, PagerDuty, and custom webhooks.

`createNotification(request)`

Create a new notification channel.

import { NotificationProvider } from "@openstatus/sdk-node";

const { notification } = await client.notification.v1.NotificationService
  .createNotification({
    name: "Slack Alerts",
    provider: NotificationProvider.SLACK,
    data: {
      data: {
        case: "slack",
        value: { webhookUrl: "https://hooks.slack.com/services/..." },
      },
    },
    monitorIds: ["mon_123", "mon_456"],
  });

console.log(`Notification created: ${notification?.id}`);

`getNotification(request)`

Get a notification channel by ID.

import { NotificationProvider } from "@openstatus/sdk-node";

const { notification } = await client.notification.v1.NotificationService
  .getNotification({
    id: "notif_123",
  });

console.log(`Name: ${notification?.name}`);
console.log(`Provider: ${NotificationProvider[notification?.provider ?? 0]}`);

`listNotifications(request)`

List all notification channels with pagination.

const { notifications, totalSize } = await client.notification.v1
  .NotificationService.listNotifications({ limit: 10, offset: 0 });

console.log(`Found ${totalSize} notification channels`);

`updateNotification(request)`

Update a notification channel.

const { notification } = await client.notification.v1.NotificationService
  .updateNotification({
    id: "notif_123",
    name: "Updated Slack Alerts",
    monitorIds: ["mon_123", "mon_456", "mon_789"],
  });

`deleteNotification(request)`

Delete a notification channel.

const { success } = await client.notification.v1.NotificationService
  .deleteNotification({
    id: "notif_123",
  });

`sendTestNotification(request)`

Send a test notification to verify configuration.

import { NotificationProvider } from "@openstatus/sdk-node";

const { success, errorMessage } = await client.notification.v1
  .NotificationService.sendTestNotification({
    provider: NotificationProvider.SLACK,
    data: {
      data: {
        case: "slack",
        value: { webhookUrl: "https://hooks.slack.com/services/..." },
      },
    },
  });

if (success) {
  console.log("Test notification sent successfully");
} else {
  console.log(`Test failed: ${errorMessage}`);
}

`checkNotificationLimit(request)`

Check if the workspace has reached its notification limit.

const { limitReached, currentCount, maxCount } = await client.notification.v1
  .NotificationService.checkNotificationLimit({});

console.log(`${currentCount}/${maxCount} notification channels used`);

Provider Configuration Examples

{
  provider: NotificationProvider.SLACK,
  data: {
    data: {
      case: "slack",
      value: { webhookUrl: "https://hooks.slack.com/services/..." }
    }
  }
}

{
  provider: NotificationProvider.DISCORD,
  data: {
    data: {
      case: "discord",
      value: { webhookUrl: "https://discord.com/api/webhooks/..." }
    }
  }
}

{
  provider: NotificationProvider.EMAIL,
  data: {
    data: {
      case: "email",
      value: { email: "[email protected]" }
    }
  }
}

{
  provider: NotificationProvider.PAGERDUTY,
  data: {
    data: {
      case: "pagerduty",
      value: { integrationKey: "your-integration-key" }
    }
  }
}

import { OpsgenieRegion } from "@openstatus/sdk-node";

{
  provider: NotificationProvider.OPSGENIE,
  data: {
    data: {
      case: "opsgenie",
      value: { apiKey: "your-api-key", region: OpsgenieRegion.US }
    }
  }
}

{
  provider: NotificationProvider.TELEGRAM,
  data: {
    data: {
      case: "telegram",
      value: { chatId: "123456789" }
    }
  }
}

{
  provider: NotificationProvider.GOOGLE_CHAT,
  data: {
    data: {
      case: "googleChat",
      value: { webhookUrl: "https://chat.googleapis.com/v1/spaces/..." }
    }
  }
}

{
  provider: NotificationProvider.GRAFANA_ONCALL,
  data: {
    data: {
      case: "grafanaOncall",
      value: { webhookUrl: "https://oncall.example.com/..." }
    }
  }
}

{
  provider: NotificationProvider.NTFY,
  data: {
    data: {
      case: "ntfy",
      value: {
        topic: "my-alerts",
        serverUrl: "https://ntfy.sh", // optional, defaults to ntfy.sh
        token: "tk_..." // optional auth token
      }
    }
  }
}

{
  provider: NotificationProvider.SMS,
  data: {
    data: {
      case: "sms",
      value: { phoneNumber: "+1234567890" }
    }
  }
}

{
  provider: NotificationProvider.WHATSAPP,
  data: {
    data: {
      case: "whatsapp",
      value: { phoneNumber: "+1234567890" }
    }
  }
}

{
  provider: NotificationProvider.WEBHOOK,
  data: {
    data: {
      case: "webhook",
      value: {
        endpoint: "https://api.example.com/webhook",
        headers: [
          { key: "Authorization", value: "Bearer token" },
          { key: "X-Custom-Header", value: "value" }
        ]
      }
    }
  }
}

Reference

Monitor Options

HTTP Monitor

| Option | ---------------------- | name | url | periodicity | method | body | headers | timeout | retry | followRedirects | regions | active | public | degradedAt | description | statusCodeAssertions | bodyAssertions | headerAssertions | openTelemetry | Type | Required | Description | | ------------------- | -------- | ------------------------------------------- | | string | Yes | Monitor name (max 256 chars) | | string | Yes | URL to monitor (max 2048 chars) | | Periodicity | Yes | Check interval | | HTTPMethod | No | HTTP method (default: GET) | | string | No | Request body | | Headers[] | No | Custom headers { key, value }[] | | bigint | No | Timeout in ms (default: 45000, max: 120000) | | bigint | No | Retry attempts (default: 3, max: 10) | | boolean | No | Follow redirects (default: true) | | Region[] | No | Regions for checks | | boolean | No | Enable monitoring (default: false) | | boolean | No | Public visibility (default: false) | | bigint | No | Latency threshold (ms) for degraded status | | string | No | Monitor description (max 1024 chars) | | array | No | Status code assertions | | array | No | Body assertions | | array | No | Header assertions | | OpenTelemetryConfig | No | OpenTelemetry export configuration |

TCP Monitor

| Option | Type | Required | Description | | --------------- | ------------------- | -------- | ------------------------------------------- | | name | string | Yes | Monitor name (max 256 chars) | | uri | string | Yes | host:port to monitor (max 2048 chars) | | periodicity | Periodicity | Yes | Check interval | | timeout | bigint | No | Timeout in ms (default: 45000, max: 120000) | | retry | bigint | No | Retry attempts (default: 3, max: 10) | | regions | Region[] | No | Regions for checks | | active | boolean | No | Enable monitoring (default: false) | | public | boolean | No | Public visibility (default: false) | | degradedAt | bigint | No | Latency threshold (ms) for degraded status | | description | string | No | Monitor description (max 1024 chars) | | openTelemetry | OpenTelemetryConfig | No | OpenTelemetry export configuration |

DNS Monitor

| Option | Type | Required | Description | | ------------------ | ------------------- | -------- | ------------------------------------------- | | name | string | Yes | Monitor name (max 256 chars) | | uri | string | Yes | Domain to resolve (max 2048 chars) | | periodicity | Periodicity | Yes | Check interval | | timeout | bigint | No | Timeout in ms (default: 45000, max: 120000) | | retry | bigint | No | Retry attempts (default: 3, max: 10) | | regions | Region[] | No | Regions for checks | | active | boolean | No | Enable monitoring (default: false) | | public | boolean | No | Public visibility (default: false) | | degradedAt | bigint | No | Latency threshold (ms) for degraded status | | description | string | No | Monitor description (max 1024 chars) | | recordAssertions | array | No | DNS record assertions | | openTelemetry | OpenTelemetryConfig | No | OpenTelemetry export configuration |

Assertions

Status Code Assertions

Validate HTTP response status codes using NumberComparator.

import { NumberComparator } from "@openstatus/sdk-node";

{
  statusCodeAssertions: [
    { comparator: NumberComparator.EQUAL, target: BigInt(200) },
    { comparator: NumberComparator.LESS_THAN, target: BigInt(400) },
  ];
}

Body Assertions

Validate response body content using StringComparator.

import { StringComparator } from "@openstatus/sdk-node";

{
  bodyAssertions: [
    { comparator: StringComparator.CONTAINS, target: '"status":"ok"' },
    { comparator: StringComparator.NOT_EMPTY, target: "" },
  ];
}

Header Assertions

Validate response headers using StringComparator.

import { StringComparator } from "@openstatus/sdk-node";

{
  headerAssertions: [
    {
      key: "content-type",
      comparator: StringComparator.CONTAINS,
      target: "application/json",
    },
  ];
}

DNS Record Assertions

Validate DNS records using RecordComparator.

import { RecordComparator } from "@openstatus/sdk-node";

{
  recordAssertions: [
    {
      record: "A",
      comparator: RecordComparator.EQUAL,
      target: "93.184.216.34",
    },
    { record: "CNAME", comparator: RecordComparator.CONTAINS, target: "cdn" },
  ];
}

Supported record types: A, AAAA, CNAME, MX, TXT

Regions

Monitor from 28 global locations across multiple providers.

import { Region } from "@openstatus/sdk-node";

regions: [Region.FLY_AMS, Region.FLY_IAD, Region.KOYEB_FRA];

Fly.io Regions (18)

| Enum Value | Location | | ---------- | --------------- | | FLY_AMS | Amsterdam | | FLY_ARN | Stockholm | | FLY_BOM | Mumbai | | FLY_CDG | Paris | | FLY_DFW | Dallas | | FLY_EWR | Newark | | FLY_FRA | Frankfurt | | FLY_GRU | São Paulo | | FLY_IAD | Washington D.C. | | FLY_JNB | Johannesburg | | FLY_LAX | Los Angeles | | FLY_LHR | London | | FLY_NRT | Tokyo | | FLY_ORD | Chicago | | FLY_SJC | San Jose | | FLY_SIN | Singapore | | FLY_SYD | Sydney | | FLY_YYZ | Toronto |

Koyeb Regions (6)

| Enum Value | Location | | ----------- | ------------- | | KOYEB_FRA | Frankfurt | | KOYEB_PAR | Paris | | KOYEB_SFO | San Francisco | | KOYEB_SIN | Singapore | | KOYEB_TYO | Tokyo | | KOYEB_WAS | Washington |

Railway Regions (4)

| Enum Value | Location | | ------------------------- | -------------- | | RAILWAY_US_WEST2 | US West | | RAILWAY_US_EAST4 | US East | | RAILWAY_EUROPE_WEST4 | Europe West | | RAILWAY_ASIA_SOUTHEAST1 | Asia Southeast |

Enums

Periodicity

| Value | Description | | ----------------- | ----------- | | PERIODICITY_30S | Every 30s | | PERIODICITY_1M | Every 1m | | PERIODICITY_5M | Every 5m | | PERIODICITY_10M | Every 10m | | PERIODICITY_30M | Every 30m | | PERIODICITY_1H | Every 1h |

HTTPMethod

| Value | Description | | --------------------- | ----------- | | HTTP_METHOD_GET | GET | | HTTP_METHOD_POST | POST | | HTTP_METHOD_HEAD | HEAD | | HTTP_METHOD_PUT | PUT | | HTTP_METHOD_PATCH | PATCH | | HTTP_METHOD_DELETE | DELETE | | HTTP_METHOD_TRACE | TRACE | | HTTP_METHOD_CONNECT | CONNECT | | HTTP_METHOD_OPTIONS | OPTIONS |

MonitorStatus

| Value | Description | | ---------- | -------------------------- | | ACTIVE | Monitor is healthy | | DEGRADED | Latency threshold exceeded | | ERROR | Monitor is failing |

TimeRange

| Value | Description | | ---------------- | ------------ | | TIME_RANGE_1D | Last 1 day | | TIME_RANGE_7D | Last 7 days | | TIME_RANGE_14D | Last 14 days |

StatusReportStatus

| Value | Description | | --------------- | -------------------------------- | | INVESTIGATING | Actively investigating the issue | | IDENTIFIED | Root cause has been identified | | MONITORING | Fix deployed, monitoring | | RESOLVED | Issue fully resolved |

OverallStatus

| Value | Description | | ---------------- | --------------------------- | | OPERATIONAL | All systems operational | | DEGRADED | Performance is degraded | | PARTIAL_OUTAGE | Some systems are down | | MAJOR_OUTAGE | Major systems are down | | MAINTENANCE | Scheduled maintenance | | UNKNOWN | Status cannot be determined |

NotificationProvider

| Value | Description | | ---------------- | ------------------- | | DISCORD | Discord webhook | | EMAIL | Email notification | | GOOGLE_CHAT | Google Chat webhook | | GRAFANA_ONCALL | Grafana OnCall | | NTFY | Ntfy push service | | PAGERDUTY | PagerDuty | | OPSGENIE | Opsgenie | | SLACK | Slack webhook | | SMS | SMS notification | | TELEGRAM | Telegram bot | | WEBHOOK | Custom webhook | | WHATSAPP | WhatsApp |

OpsgenieRegion

| Value | Description | | ----- | ----------- | | US | US region | | EU | EU region |

PageAccessType

| Value | Description | | -------------------- | ----------------------- | | PUBLIC | Publicly accessible | | PASSWORD_PROTECTED | Requires password | | AUTHENTICATED | Requires authentication |

PageTheme

| Value | Description | | -------- | ------------------- | | SYSTEM | Follow system theme | | LIGHT | Light theme | | DARK | Dark theme |

PageComponentType

| Value | Description | | --------- | ------------------------- | | MONITOR | Linked to a monitor | | STATIC | Static component (manual) |

NumberComparator

| Value | Description | | ----------------------- | --------------------- | | EQUAL | Equal to target | | NOT_EQUAL | Not equal to target | | GREATER_THAN | Greater than target | | GREATER_THAN_OR_EQUAL | Greater than or equal | | LESS_THAN | Less than target | | LESS_THAN_OR_EQUAL | Less than or equal |

StringComparator

| Value | Description | | ----------------------- | --------------------------- | | CONTAINS | Contains target string | | NOT_CONTAINS | Does not contain target | | EQUAL | Equal to target | | NOT_EQUAL | Not equal to target | | EMPTY | Value is empty | | NOT_EMPTY | Value is not empty | | GREATER_THAN | Lexicographically greater | | GREATER_THAN_OR_EQUAL | Lexicographically >= target | | LESS_THAN | Lexicographically less | | LESS_THAN_OR_EQUAL | Lexicographically <= target |

RecordComparator

| Value | Description | | -------------- | ----------------------- | | EQUAL | Equal to target | | NOT_EQUAL | Not equal to target | | CONTAINS | Contains target string | | NOT_CONTAINS | Does not contain target |

Error Handling

The SDK uses Connect RPC. Errors include a code and message:

import { ConnectError } from "@connectrpc/connect";

try {
  await client.monitor.v1.MonitorService.deleteMonitor({ id: "invalid" });
} catch (error) {
  if (error instanceof ConnectError) {
    console.error(`Error ${error.code}: ${error.message}`);
  }
}

OpenStatus - Open-source monitoring platform
Documentation - Full API documentation
Status Page - OpenStatus service status

License

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

OpenStatus Node.js SDK

Table of Contents

Features

Monitoring

Status Page

Notifications

Developer Experience

Installation

npm

JSR

Deno

Quick Start

Authentication

Recommended: Configure client once

Alternative: Manual headers

Environment Variables

SDK Reference

Monitor Service

createHTTPMonitor(request)

updateHTTPMonitor(request)

createTCPMonitor(request)

updateTCPMonitor(request)

createDNSMonitor(request)

updateDNSMonitor(request)

listMonitors(request)

getMonitor(request)

triggerMonitor(request)

deleteMonitor(request)

getMonitorStatus(request)

getMonitorSummary(request)

Health Service

Status Report Service

createStatusReport(request)

getStatusReport(request)

listStatusReports(request)

updateStatusReport(request)

deleteStatusReport(request)

addStatusReportUpdate(request)

Status Page Service

createStatusPage(request)

getStatusPage(request)

listStatusPages(request)

updateStatusPage(request)

deleteStatusPage(request)

addMonitorComponent(request)

addStaticComponent(request)

updateComponent(request)

removeComponent(request)

createComponentGroup(request)

updateComponentGroup(request)

deleteComponentGroup(request)

subscribeToPage(request)

unsubscribeFromPage(request)

listSubscribers(request)

getStatusPageContent(request)

getOverallStatus(request)