OpenStatus Node.js SDK (Beta)#

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

Features#

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

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

• Type-safe - Full TypeScript support with generated types from protobuf

Installation#

JSR#

npx jsr add @openstatus/sdk-node

npm#

npm install @openstatus/sdk-node

Deno#

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

Quick Start#

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

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

// Create a monitor
const { monitor } = await openstatus.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) },
        ],
      },
    },
    { headers },
  );

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

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

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

Authentication#

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

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

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

Environment Variables#

API Reference#

Monitor Service#

createHTTPMonitor(request, options)#

Create an HTTP/HTTPS monitor.

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

const { monitor } = await openstatus.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,
      },
    },
    { headers },
  );

updateHTTPMonitor(request, options)#

Update an existing HTTP monitor.

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

createTCPMonitor(request, options)#

Create a TCP connection monitor.

const { monitor } = await openstatus.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,
    },
  },
  { headers },
);

updateTCPMonitor(request, options)#

Update an existing TCP monitor.

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

createDNSMonitor(request, options)#

Create a DNS resolution monitor.

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

const { monitor } = await openstatus.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",
        },
      ],
    },
  },
  { headers },
);

updateDNSMonitor(request, options)#

Update an existing DNS monitor.

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

listMonitors(request, options)#

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

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

triggerMonitor(request, options)#

Trigger an immediate check.

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

deleteMonitor(request, options)#

Delete a monitor.

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

getMonitorStatus(request, options)#

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

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

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

// regions is an array of { region, status }
// region: Region enum value (e.g., Region.FLY_AMS)
// status: MonitorStatus.ACTIVE, MonitorStatus.DEGRADED, or MonitorStatus.ERROR
for (const { region, status } of regions) {
  console.log(`${Region[region]}: ${MonitorStatus[status]}`);
}

getMonitorSummary(request, options)#

Get aggregated metrics and latency percentiles for a monitor.

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

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

console.log(`Last ping: ${summary.lastPingAt}`);
console.log(`Success: ${summary.totalSuccessful}`);
console.log(`Degraded: ${summary.totalDegraded}`);
console.log(`Failed: ${summary.totalFailed}`);
console.log(`P50 latency: ${summary.p50}ms`);
console.log(`P75 latency: ${summary.p75}ms`);
console.log(`P90 latency: ${summary.p90}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 { ServingStatus } from "@openstatus/sdk-node";

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

Status Report Service#

Manage incident and maintenance reports with update timelines.

createStatusReport(request, options)#

Create a new status report.

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

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

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

getStatusReport(request, options)#

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

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

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

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

listStatusReports(request, options)#

List all status reports with pagination and optional filtering.

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

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

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

updateStatusReport(request, options)#

Update status report metadata (title, page components).

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

deleteStatusReport(request, options)#

Delete a status report and all its updates.

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

addStatusReportUpdate(request, options)#

Add a new update to an existing status report timeline.

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

const { statusReport } = await openstatus.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:00", // optional, defaults to current time
      notify: true,
    },
    { headers },
  );

Status Report Status#

Status Page Service#

Manage status pages, components, and subscribers.

createStatusPage(request, options)#

Create a new status page.

const { statusPage } = await openstatus.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",
    },
    { headers },
  );

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

getStatusPage(request, options)#

Get a status page by ID.

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

listStatusPages(request, options)#

List all status pages with pagination.

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

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

updateStatusPage(request, options)#

Update a status page.

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

deleteStatusPage(request, options)#

Delete a status page.

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

addMonitorComponent(request, options)#

Add a monitor-based component to a status page.

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

addStaticComponent(request, options)#

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

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

updateComponent(request, options)#

Update a component.

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

removeComponent(request, options)#

Remove a component from a status page.

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

createComponentGroup(request, options)#

Create a component group.

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

updateComponentGroup(request, options)#

Update a component group.

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

deleteComponentGroup(request, options)#

Delete a component group.

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

subscribeToPage(request, options)#

Subscribe an email to status page updates.

const { subscriber } = await openstatus.statusPage.v1.StatusPageService
  .subscribeToPage(
    {
      pageId: "page_123",
      email: "user@example.com",
    },
    { headers },
  );

unsubscribeFromPage(request, options)#

Unsubscribe from a status page.

// By email
const { success } = await openstatus.statusPage.v1.StatusPageService
  .unsubscribeFromPage(
    {
      pageId: "page_123",
      identifier: { case: "email", value: "user@example.com" },
    },
    { headers },
  );

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

listSubscribers(request, options)#

List all subscribers for a status page.

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

getStatusPageContent(request, options)#

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

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

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

getOverallStatus(request, options)#

Get the aggregated status of a status page.

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

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

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

Maintenance Service#

Manage scheduled maintenance windows.

createMaintenance(request, options)#

Create a new maintenance window.

const { maintenance } = await openstatus.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,
    },
    { headers },
  );

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

getMaintenance(request, options)#

Get a maintenance window by ID.

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

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

listMaintenances(request, options)#

List all maintenance windows with pagination and optional filtering.

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

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

updateMaintenance(request, options)#

Update a maintenance window.

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

deleteMaintenance(request, options)#

Delete a maintenance window.

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

Status Page Options#

Page Access Type#

Page Theme#

Overall Status#

Page Component Type#

Monitor Options#

HTTP Monitor#

TCP Monitor#

DNS Monitor#

Periodicity#

HTTP Methods#

Assertions#

All assertion comparators are exported as enums from the SDK.

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) },
  ];
}

NumberComparator values:

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: "" },
  ];
}

StringComparator values:

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" },
  ];
}

RecordComparator values:

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

Regions#

Monitor from 28 global locations across multiple providers. Use the Region enum:

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

// Example: Use specific regions
regions: [Region.FLY_AMS, Region.FLY_IAD, Region.KOYEB_FRA];

Fly.io Regions#

Koyeb Regions#

Railway Regions#

Error Handling#

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

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

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

Related#

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

License#

MIT