OpenStatus Node.js SDK (Beta)#

Official Node.js SDK for OpenStatus - the open-source monitoring platform.

Features#

• 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 {
  openstatus,
  Periodicity,
  Region,
  HTTPMethod,
  NumberComparator,
} 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 { Periodicity, Region, HTTPMethod } 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"

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