OpenStatus Node.js SDK#

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

Installation#

JSR#

npx jsr add @openstatus/node-sdk

npm#

npm install @openstatus/node-sdk

Deno#

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

Quick Start#

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

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

// Create a monitor
const monitor = await openstatus.monitor.v1.MonitorService.createHTTPMonitor(
  {
    name: "My API",
    url: "https://api.example.com/health",
    periodicity: "1m",
    method: "GET",
    regions: ["ams", "iad", "syd"],
    active: true,
    statusCodeAssertions: [{ comparator: "EQUAL", target: 200 }],
  },
  { headers },
);

console.log(`Monitor created: ${monitor.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": `Bearer ${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.

const { monitor } = await openstatus.monitor.v1.MonitorService
  .createHTTPMonitor(
    {
      name: "My Website",
      url: "https://example.com",
      periodicity: "1m",
      method: "GET",
      regions: ["ams", "iad", "syd"],
      active: true,
    },
    { headers },
  );

createTCPMonitor(request, options)#

Create a TCP connection monitor.

const { monitor } = await openstatus.monitor.v1.MonitorService.createTCPMonitor(
  {
    name: "Database",
    uri: "db.example.com:5432",
    periodicity: "5m",
    regions: ["ams", "iad"],
    active: true,
  },
  { headers },
);

createDNSMonitor(request, options)#

Create a DNS resolution monitor.

const { monitor } = await openstatus.monitor.v1.MonitorService.createDNSMonitor(
  {
    name: "DNS Check",
    uri: "example.com",
    periodicity: "10m",
    regions: ["ams"],
    active: true,
    recordAssertions: [{
      recordType: "A",
      comparator: "EQUAL",
      target: "93.184.216.34",
    }],
  },
  { 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.

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

deleteMonitor(request, options)#

Delete a monitor.

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

getMonitorStatus(request, options)#

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

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

// regions is an array of { region, status }
// status: ACTIVE, DEGRADED, or ERROR
for (const { region, status } of regions) {
  console.log(`${region}: ${status}`);
}

getMonitorSummary(request, options)#

Get aggregated metrics and latency percentiles for a monitor.

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

const summary = await openstatus.monitor.v1.MonitorService.getMonitorSummary(
  {
    id: "mon_123",
    timeRange: TimeRange.TIME_RANGE_7D, // 1D, 7D, or 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(`P95 latency: ${summary.p95}ms`);
console.log(`P99 latency: ${summary.p99}ms`);

Health Service#

Check API health status (no authentication required).

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

Monitor Options#

HTTP Monitor#

TCP Monitor#

DNS Monitor#

Assertions#

Status Code Assertions#

Validate HTTP response status codes.

{
  statusCodeAssertions: [
    { comparator: "EQUAL", target: 200 },
    { comparator: "LESS_THAN", target: 400 },
  ];
}

Comparators: EQUAL, NOT_EQUAL, GREATER_THAN, GREATER_THAN_OR_EQUAL, LESS_THAN, LESS_THAN_OR_EQUAL

Body Assertions#

Validate response body content.

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

Comparators: CONTAINS, NOT_CONTAINS, EQUAL, NOT_EQUAL, EMPTY, NOT_EMPTY

Header Assertions#

Validate response headers.

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

DNS Record Assertions#

Validate DNS records.

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

Record types: A, AAAA, CNAME, MX, TXT

Regions#

Monitor from 28 global locations across multiple providers:

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