Something went wrong. Try again.
[READ-ONLY] Mirror of https://github.com/openstatusHQ/openstatus. 🫖 Status page with uptime monitoring & API monitoring as code 🫖 openstatus.dev
bun drizzle-orm monitoring monitoring-as-code nextjs observability on-call open-source shadcn-ui status-page statuspage synthetic-monitoring tinybird turso uptime uptime-checker uptime-monitor
Something went wrong. Try again.
MDX
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184---category: SDKtitle: Getting Starteddescription: "Install and start using the openstatus Node.js SDK"---
## Get Your API Key
Before using the SDK, you need an API key:
1. Log in to the [openstatus dashboard](https://app.openstatus.dev/login)2. Go to **Settings** > **General** and find the **API Keys** card3. Click **Create** and copy the key
<Aside type="tip">Store your API key as an environment variable (`OPENSTATUS_API_KEY`) — never commit it to source control.</Aside>
## Installation
### npm
```bashnpm install @openstatus/sdk-node```
### JSR
```bashnpx jsr add @openstatus/sdk-node```
### Deno
```typescriptimport { createOpenStatusClient } from "jsr:@openstatus/sdk-node";```
### Bun
```bashbun add @openstatus/sdk-node```
## Quick Start
```typescriptimport { createOpenStatusClient, Periodicity, Region,} from "@openstatus/sdk-node";
const client = createOpenStatusClient({ apiKey: process.env.OPENSTATUS_API_KEY,});
// Create an HTTP monitorconst { 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 monitorsconst { 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`:
| Runtime | Version | Module Format ||--------------------|---------|---------------|| Node.js | 18+ | ESM and CJS || Deno | 2+ | ESM (native) || Bun | Latest | ESM || Cloudflare Workers | — | ESM (edge) |
### Cloudflare Workers and edge runtimes
`@connectrpc/connect-web` sets `redirect: "error"` on every request. Node, Deno, and Bun's `fetch` support that mode, so they need no setup — but Cloudflare Workers (`workerd`) doesn't, so **every** request there fails with `The redirect mode 'error' is not supported`. On Workers, pass a transport with a redirect-normalizing `fetch` (the SDK re-exports `createAuthInterceptor` and the service descriptors for this):
```typescriptimport { 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 does not implement fetch's `redirect: "error"`; normalise it. fetch: (input, init) => fetch( input, init?.redirect === "error" ? { ...init, redirect: "manual" } : init, ), }),});```
<Aside type="note">When you pass a `transport`, the `apiKey` and `baseUrl` options are ignored — configure authentication on the transport via `createAuthInterceptor`. For full control you can also import the raw service descriptors (`MonitorService`, `StatusPageService`, …) and call `createClient(MonitorService, transport)` from `@connectrpc/connect`.</Aside>
## 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.
```typescriptimport { createOpenStatusClient, NotificationProvider, Periodicity, Region,} from "@openstatus/sdk-node";
const client = createOpenStatusClient({ apiKey: process.env.OPENSTATUS_API_KEY,});
// 1. Check API healthconst health = await client.health.v1.HealthService.check({});console.log(`API status: ${health.status}`);
// 2. Create an HTTP monitorconst { 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 pageconst { 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 componentconst { component } = await client.statusPage.v1.StatusPageService .addMonitorComponent({ pageId: statusPage!.id, monitorId: monitor!.id, name: "Production API", });
// 5. Set up Slack notificationsconst { 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 statusconst { overallStatus } = await client.statusPage.v1.StatusPageService .getOverallStatus({ identifier: { case: "id", value: statusPage!.id }, });
console.log(`Overall status: ${overallStatus}`);```