TypeScript SDK

The @devhelm/sdk package is a typed, promise-based client for the DevHelm REST API. It runs in any modern Node.js or browser environment, ships full TypeScript types, and uses Zod for runtime request/response validation.

Install

npm install @devhelm/sdk

Requires Node 18+ (for native fetch).

Initialize

import { Devhelm } from "@devhelm/sdk";

const client = new Devhelm({
  token: process.env.DEVHELM_API_TOKEN!,
});

Option	Type	Default	Description
`token`	`string`	—	API token (Bearer). Required.
`baseUrl`	`string`	`https://api.devhelm.io`	Override for self-hosted or testing.
`orgId`	`string`	`DEVHELM_ORG_ID` env or `"1"`	Organization ID header.
`workspaceId`	`string`	`DEVHELM_WORKSPACE_ID` when set	Workspace ID header. Omit it when the organization has one workspace.

Create a monitor

const monitor = await client.monitors.create({
  name: "API Health",
  type: "HTTP",
  config: {
    url: "https://api.example.com/health",
    method: "GET",
  },
  frequencySeconds: 60,
  regions: ["us-east", "eu-west"],
});

console.log(`Created monitor: ${monitor.id}`);

managedBy is optional — omit it (defaults to API server-side) or set it explicitly to one of API, DASHBOARD, CLI, TERRAFORM, or MCP to record the provenance for drift detection. Request bodies are validated against the generated Zod schemas before any HTTP I/O — invalid payloads throw DevhelmValidationError with structured field errors.

List monitors

// Auto-paginates through every page
const monitors = await client.monitors.list();

for (const monitor of monitors) {
  console.log(`${monitor.name}: ${monitor.currentStatus}`);
}

For manual pagination control:

const page = await client.monitors.listPage(0, 50);
console.log(`Total: ${page.totalElements}`);
for (const monitor of page.data) {
  // ...
}

Update or delete a monitor

// Update
const updated = await client.monitors.update(monitor.id, {
  frequencySeconds: 30,
});

// Delete
await client.monitors.delete(monitor.id);

Get check results

const results = await client.monitors.results(monitor.id, { limit: 10 });

for (const check of results.data) {
  const status = check.passed ? "OK" : "FAIL";
  console.log(`${check.region}: ${status} (${check.responseTimeMs}ms)`);
}

// Fetch the next batch
if (results.hasMore) {
  const next = await client.monitors.results(monitor.id, {
    cursor: results.nextCursor!,
    limit: 10,
  });
}

Manage incidents

const incidents = await client.incidents.list();

for (const incident of incidents) {
  if (incident.status === "OPEN") {
    console.log(`Open: ${incident.title}`);
  }
}

await client.incidents.resolve(incidentId);
// or with a resolution note:
await client.incidents.resolve(incidentId, { body: "fixed by deploy" });

Create an alert channel

const channel = await client.alertChannels.create({
  name: "Slack Alerts",
  config: {
    channelType: "slack",
    webhookUrl: process.env.SLACK_WEBHOOK_URL!,
  },
});

The channel type is the channelType discriminator inside config (slack, email, discord, pagerduty, …) — there is no top-level type field on this request.

Error handling

import {
  DevhelmError,
  DevhelmAuthError,
  DevhelmNotFoundError,
  DevhelmRateLimitError,
} from "@devhelm/sdk";

try {
  await client.monitors.get("nonexistent");
} catch (err) {
  if (err instanceof DevhelmNotFoundError) {
    console.error("Monitor not found");
  } else if (err instanceof DevhelmRateLimitError) {
    console.error(`Rate limited (request_id=${err.requestId})`);
  } else if (err instanceof DevhelmAuthError) {
    console.error("Bad token or insufficient permissions");
  } else if (err instanceof DevhelmError) {
    throw err;
  }
}

Full taxonomy in the Error handling guide.

Resource namespaces

The client exposes 19 resources:

Namespace	Covers
`client.monitors`	HTTP, DNS, TCP, ICMP, MCP, Heartbeat monitors + check results, versions
`client.incidents`	Manual and auto-detected incidents
`client.forensics`	Incident timelines, check traces, policy snapshots, rule evaluations
`client.alertChannels`	Email, Slack, Discord, webhook, PagerDuty, OpsGenie, Teams
`client.notificationPolicies`	Routing rules, schedules
`client.environments`	Workspace environments (production, staging, …)
`client.secrets`	Secret values consumed by monitor configs
`client.tags`	Color-coded labels for monitors and incidents
`client.resourceGroups`	Compose monitors and dependencies into logical units
`client.webhooks`	Outbound event delivery
`client.inboxes`	Webhook testing inboxes: capture requests your code sends and wait for them
`client.email`	Email testing: per-test addresses, inject, wait, OTP codes and links
`client.apiKeys`	Token issuance and revocation
`client.dependencies`	Tracked third-party services for status pages
`client.services`	Third-party service status catalog (search, live status, uptime, incidents)
`client.deployLock`	Acquire / release / inspect the deploy lock
`client.maintenanceWindows`	Scheduled alert-suppression windows
`client.status`	Dashboard overview metrics
`client.statusPages`	Status pages, components, groups, incidents, subscribers, custom domains

Next steps

Client reference

Every method, signature, and return type.

Error handling

Exception classes and retry patterns.

Webhook inboxes

Assert on the webhooks your code sends with client.inboxes.

Email testing

Wait for sign-up and reset emails with client.email.

Overview

Python SDK

MCP Server

AI Skills

TypeScript SDK

Install

Initialize

Create a monitor

List monitors

Update or delete a monitor

Get check results

Manage incidents

Create an alert channel

Error handling

Resource namespaces

Next steps

Client reference

Error handling

Webhook inboxes

Email testing

​Install

​Initialize

​Create a monitor

​List monitors

​Update or delete a monitor

​Get check results

​Manage incidents

​Create an alert channel

​Error handling

​Resource namespaces

​Next steps

Client reference

Error handling

Webhook inboxes

Email testing

Install

Initialize

Create a monitor

List monitors

Update or delete a monitor

Get check results

Manage incidents

Create an alert channel

Error handling

Resource namespaces

Next steps