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

# TypeScript SDK

> Install and use the DevHelm TypeScript SDK to manage monitors, incidents, and alerts programmatically

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

```bash theme={null}
npm install @devhelm/sdk
```

Requires Node 18+ (for native `fetch`).

## Initialize

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
// 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:

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

## Update or delete a monitor

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

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

## Get check results

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
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](/sdk/typescript/error-handling).

## 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 |

## Next steps

<CardGroup cols={2}>
  <Card title="Client reference" icon="book" href="/sdk/typescript/client-reference">
    Every method, signature, and return type.
  </Card>

  <Card title="Error handling" icon="triangle-exclamation" href="/sdk/typescript/error-handling">
    Exception classes and retry patterns.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.