← Back to index

Getting Started #

Installation #

npm #

npm install @openstatus/sdk-node

JSR #

npx jsr add @openstatus/sdk-node

Deno #

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

Bun #

bun add @openstatus/sdk-node

Quick Start #

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

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

// Create an HTTP monitor
const { monitor } = await client.monitor.v1.MonitorService.createHTTPMonitor({
  monitor: {
    name: "My API",
    url: "https://api.example.com/health",
    periodicity: Periodicity.PERIODICITY_1M,
    regions: [Region.FLY_AMS, Region.FLY_IAD, Region.FLY_SYD],
    active: true,
  },
});

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`);

Runtime Support #

The SDK talks to the API over a fetch-based Connect transport (@connectrpc/connect-web), so it runs on any runtime with a global fetch — no HTTP/2 or node:* modules required:

Cloudflare Workers and edge runtimes #

The default client works on the edge as-is. The one caveat is that @connectrpc/connect-web issues requests with redirect: "error", which workerd doesn't implement. If you hit The redirect mode 'error' is not supported, pass a transport with a redirect-tolerant fetch (the SDK re-exports createAuthInterceptor and the service descriptors for this):

import { createConnectTransport } from "@connectrpc/connect-web";
import {
  createAuthInterceptor,
  createOpenStatusClient,
} from "@openstatus/sdk-node";

const client = createOpenStatusClient({
  transport: createConnectTransport({
    baseUrl: "https://api.openstatus.dev/rpc",
    interceptors: [createAuthInterceptor(env.OPENSTATUS_API_KEY)],
    // workerd doesn't implement fetch's `redirect: "error"`; normalise it.
    fetch: (input, init) =>
      fetch(
        input,
        init?.redirect === "error" ? { ...init, redirect: "manual" } : init,
      ),
  }),
});

When you pass a transport, the apiKey and baseUrl options are ignored — configure authentication on the transport via createAuthInterceptor.

Full Workflow Example #

A complete example: create a monitor, set up a status page, add the monitor as a component, configure a Slack notification, and check overall status.

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

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

// 1. Check API health
const health = await client.health.v1.HealthService.check({});
console.log(`API status: ${health.status}`);

// 2. Create an HTTP monitor
const { monitor } = await client.monitor.v1.MonitorService.createHTTPMonitor({
  monitor: {
    name: "Production API",
    url: "https://api.example.com/health",
    periodicity: Periodicity.PERIODICITY_1M,
    regions: [Region.FLY_AMS, Region.FLY_IAD, Region.FLY_SYD],
    active: true,
  },
});

// 3. Create a status page
const { statusPage } = await client.statusPage.v1.StatusPageService
  .createStatusPage({
    title: "Example Status",
    slug: "example-status",
    description: "Status page for Example services",
  });

// 4. Add the monitor as a component
const { component } = await client.statusPage.v1.StatusPageService
  .addMonitorComponent({
    pageId: statusPage!.id,
    monitorId: monitor!.id,
    name: "Production API",
  });

// 5. Set up Slack notifications
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: [monitor!.id],
  });

// 6. Check overall status
const { overallStatus } = await client.statusPage.v1.StatusPageService
  .getOverallStatus({
    identifier: { case: "id", value: statusPage!.id },
  });

console.log(`Overall status: ${overallStatus}`);