Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.devhelm.io/llms.txt

Use this file to discover all available pages before exploring further.

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!,
});
OptionTypeDefaultDescription
tokenstring—API token (Bearer). Required.
baseUrlstringhttps://api.devhelm.ioOverride for self-hosted or testing.
orgIdstringDEVHELM_ORG_ID env or "1"Organization ID header.
workspaceIdstringDEVHELM_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, { resolutionNote: "fixed by deploy" });

​
Create an alert channel

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

​
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 14 resources:
NamespaceCovers
client.monitorsHTTP, DNS, TCP, ICMP, MCP, Heartbeat monitors + check results, versions
client.incidentsManual and auto-detected incidents
client.alertChannelsEmail, Slack, Discord, webhook, PagerDuty, OpsGenie, Teams
client.notificationPoliciesRouting rules, schedules
client.environmentsWorkspace environments (production, staging, …)
client.secretsSecret values consumed by monitor configs
client.tagsColor-coded labels for monitors and incidents
client.resourceGroupsCompose monitors and dependencies into logical units
client.webhooksOutbound event delivery
client.apiKeysToken issuance and revocation
client.dependenciesTracked third-party services for status pages
client.deployLockAcquire / release / inspect the deploy lock
client.statusDashboard overview metrics
client.statusPagesStatus pages, components, groups, incidents, subscribers, custom domains

​
Next steps

Client reference

Every method, signature, and return type.

Error handling

Exception classes and retry patterns.