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` env or `"1"`	Workspace ID header.

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 17 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.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

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

​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

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