TypeScript Client Reference

Complete reference for the @devhelm/sdk TypeScript SDK.

Client initialization

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

// Reads DEVHELM_WORKSPACE_ID; the token must be passed explicitly.
const client = new Devhelm({ token: process.env.DEVHELM_API_TOKEN! });

Configuration options

Property	Type	Required	Default	Description
`token`	string	Yes	—	API key (Bearer). Not read from the environment: pass `process.env.DEVHELM_API_TOKEN!`
`baseUrl`	string	—	`https://api.devhelm.io`	API base URL. `DEVHELM_API_URL` is not read
`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

The SDK is ESM only: use import, not require.

Resource namespaces

client.monitors

Method	Signature	Returns
`list()`	`() => Promise<MonitorDto[]>`	Auto-fetches all pages
`listPage(page, size)`	`(number, number) => Promise<Page<MonitorDto>>`	Single page
`get(id)`	`(string \| number) => Promise<MonitorDto>`
`create(body)`	`(CreateMonitorRequest) => Promise<MonitorDto>`
`update(id, body)`	`(string \| number, UpdateMonitorRequest) => Promise<MonitorDto>`
`delete(id)`	`(string \| number) => Promise<void>`
`pause(id)`	`(string \| number) => Promise<MonitorDto>`
`resume(id)`	`(string \| number) => Promise<MonitorDto>`
`test(id)`	`(string \| number) => Promise<MonitorTestResultDto>`
`results(id, options?)`	`(string \| number, { cursor?, limit? }) => Promise<CursorPage<CheckResultDto>>`	Cursor pagination
`versions(id, options?)`	`(string \| number, { page?, size? }) => Promise<Page<MonitorVersionDto>>`

client.incidents

Method	Signature	Returns
`list()`	`() => Promise<IncidentDto[]>`
`listPage(page, size)`	`(number, number) => Promise<Page<IncidentDto>>`
`get(id)`	`(string \| number) => Promise<IncidentDetailDto>`
`create(body)`	`(CreateManualIncidentRequest) => Promise<IncidentDetailDto>`
`resolve(id, body?)`	`(string \| number, ResolveIncidentRequest?) => Promise<IncidentDetailDto>`	Body optional

Incidents have no delete method — they are resolved, not deleted.

client.alertChannels

Method	Signature	Returns
`list()`	`() => Promise<AlertChannelDto[]>`
`listPage(page, size)`	`(number, number) => Promise<Page<AlertChannelDto>>`
`get(id)`	`(string \| number) => Promise<AlertChannelDto>`
`create(body)`	`(CreateAlertChannelRequest) => Promise<AlertChannelDto>`
`update(id, body)`	`(string \| number, UpdateAlertChannelRequest) => Promise<AlertChannelDto>`
`delete(id)`	`(string \| number) => Promise<void>`
`test(id)`	`(string \| number) => Promise<TestChannelResult>`

client.notificationPolicies

Method	Signature	Returns
`list()`	`() => Promise<NotificationPolicyDto[]>`
`listPage(page, size)`	`(number, number) => Promise<Page<NotificationPolicyDto>>`
`get(id)`	`(string \| number) => Promise<NotificationPolicyDto>`
`create(body)`	`(CreateNotificationPolicyRequest) => Promise<NotificationPolicyDto>`
`update(id, body)`	`(string \| number, UpdateNotificationPolicyRequest) => Promise<NotificationPolicyDto>`
`delete(id)`	`(string \| number) => Promise<void>`
`test(id)`	`(string \| number) => Promise<void>`

client.tags

Method	Signature	Returns
`list()`	`() => Promise<TagDto[]>`
`listPage(page, size)`	`(number, number) => Promise<Page<TagDto>>`
`get(id)`	`(string \| number) => Promise<TagDto>`
`create(body)`	`(CreateTagRequest) => Promise<TagDto>`
`update(id, body)`	`(string \| number, UpdateTagRequest) => Promise<TagDto>`
`delete(id)`	`(string \| number) => Promise<void>`

client.environments

Method	Signature	Returns
`list()`	`() => Promise<EnvironmentDto[]>`
`listPage(page, size)`	`(number, number) => Promise<Page<EnvironmentDto>>`
`get(slug)`	`(string) => Promise<EnvironmentDto>`	By slug
`create(body)`	`(CreateEnvironmentRequest) => Promise<EnvironmentDto>`
`update(slug, body)`	`(string, UpdateEnvironmentRequest) => Promise<EnvironmentDto>`
`delete(slug)`	`(string) => Promise<void>`

client.secrets

Method	Signature	Returns
`list()`	`() => Promise<SecretDto[]>`	Metadata only
`listPage(page, size)`	`(number, number) => Promise<Page<SecretDto>>`
`create(body)`	`(CreateSecretRequest) => Promise<SecretDto>`
`update(key, body)`	`(string, UpdateSecretRequest) => Promise<SecretDto>`
`delete(key)`	`(string) => Promise<void>`

client.resourceGroups

Method	Signature	Returns
`list()`	`() => Promise<ResourceGroupDto[]>`
`listPage(page, size)`	`(number, number) => Promise<Page<ResourceGroupDto>>`
`get(id)`	`(string \| number) => Promise<ResourceGroupDto>`
`create(body)`	`(CreateResourceGroupRequest) => Promise<ResourceGroupDto>`
`update(id, body)`	`(string \| number, UpdateResourceGroupRequest) => Promise<ResourceGroupDto>`
`delete(id)`	`(string \| number) => Promise<void>`
`addMember(groupId, body)`	`(string \| number, AddResourceGroupMemberRequest) => Promise<void>`
`removeMember(groupId, memberId)`	`(string \| number, string \| number) => Promise<void>`

client.webhooks

Method	Signature	Returns
`list()`	`() => Promise<WebhookEndpointDto[]>`
`listPage(page, size)`	`(number, number) => Promise<Page<WebhookEndpointDto>>`
`get(id)`	`(string \| number) => Promise<WebhookEndpointDto>`
`create(body)`	`(CreateWebhookEndpointRequest) => Promise<WebhookEndpointDto>`
`update(id, body)`	`(string \| number, UpdateWebhookEndpointRequest) => Promise<WebhookEndpointDto>`
`delete(id)`	`(string \| number) => Promise<void>`
`test(id)`	`(string \| number) => Promise<WebhookTestResult>`

client.inboxes

Webhook testing inboxes: URLs that capture the requests your code sends. client.webhooks is the opposite direction. See Webhook inboxes.

Method	Signature	Returns
`list(opts?)`	`({ search? }) => Promise<Inbox[]>`	Auto-fetches all pages
`listPage(page, size, opts?)`	`(number, number, { search? }) => Promise<Page<Inbox>>`	Single page
`activity(inboxIds)`	`(string[]) => Promise<InboxActivity[]>`	24 hourly buckets of `{ hour, eventCount }`. An empty list makes no call
`get(id)`	`(string) => Promise<Inbox>`
`create(body)`	`(CreateWebhookInboxRequest) => Promise<Inbox>`
`update(id, body)`	`(string, UpdateWebhookInboxRequest) => Promise<Inbox>`	`httpResponse` merges per field; `headers` replaces the whole map
`delete(id)`	`(string) => Promise<void>`	Deletes the inbox and its events
`wait(id, opts?)`	`(string, WaitInboxOptions) => Promise<Event>`	Oldest match; throws on 408

Inbox is the inbox DTO (httpUrl, publicToken, status, httpResponse, cors, retentionDays, maxEvents, …) plus these members:

Member	Signature	Notes
`wait(opts?)`	`(WaitInboxOptions) => Promise<Event>`	Same as `client.inboxes.wait(inbox.id, opts)`
`update(body)` / `delete()`	`Promise<Inbox>` / `Promise<void>`
`events.list(opts?)`	`({ cursor?, limit?, method?, path? }) => Promise<CursorPage<ListedEvent>>`	Newest first. `path` is a case-sensitive substring
`events.get(eventId)`	`(string) => Promise<Event>`	Body clipped at 256 KB
`events.delete(eventId)` / `events.clear()`	`Promise<void>`	One event / every event

ListedEvent (a list row) has raw(): Promise<File> for the exact body bytes and delete(). Event (from get or wait) adds text() and json() over body. Wait returns the full body, not clipped. WaitInboxOptions:

Option	Type	Default	Notes
`receivedAfter`	ISO 8601 string	omitted; server looks back 60 seconds	Matches `receivedAt >= receivedAfter`. Pass it for a cursor, such as the previous event’s `receivedAt` plus 1 ms
`timeoutMs`	number	`30000`	Clamped at `120000`. A timeout throws `DevhelmApiError` with code `WAIT_TIMEOUT`
`http.method`	string	—	Without it, `OPTIONS` requests are skipped
`http.pathPrefix`	string	—	Case-sensitive prefix on the path after the token

const inbox = await client.inboxes.create({ name: "orders-test" });
await fetch(`${inbox.httpUrl}/orders`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ id: 42 }),
});
const event = await inbox.wait({ http: { pathPrefix: "/orders" } });
console.log(event.method, event.json());
await inbox.delete();

In 1.9.0, lastEventAt on Inbox and bodyTruncated and rawUrl on events are returned at runtime but are not declared in the types; they read as unknown.

client.email

Email testing: per-test addresses on the workspace’s assigned domain, inject, and wait. This is separate from email alert channels. See Email testing.

Method	Signature	Returns
`address(opts?)`	`({ label?, domain? }) => Promise<Address>`	Local part is `label-<8 hex>`. Without `domain`, finds or creates the assigned domain
`wait(opts)`	`(WaitEmailOptions & { to: string }) => Promise<Message>`	`to` is the full address
`waitLocalPart(localPart, opts)`	`(string, WaitEmailOptions & { domain: string }) => Promise<Message>`
`domains.list(opts?)`	`({ search? }) => Promise<Domain[]>`
`domains.listPage(page, size, opts?)`	`(number, number, { search? }) => Promise<Page<Domain>>`
`domains.activity(domainIds)`	`(string[]) => Promise<DomainActivity[]>`	24 hourly buckets of `{ hour, messageCount }`
`domains.get(name)`	`(string) => Promise<Domain>`	By domain name, not ID
`domains.create(body?)`	`({ name? }) => Promise<Domain>`	No `name`: assigned domain. With `name`: custom domain
`domains.update(name, body)`	`(string, UpdateEmailDomainRequest) => Promise<Domain>`	`status`: `disabled`, or `active` for an assigned domain
`domains.verify(name)`	`(string) => Promise<Domain>`	Checks DNS for a custom domain
`domains.delete(name)`	`(string) => Promise<void>`	Deletes every message on the domain

WaitEmailOptions takes receivedAfter (omit it for the server lookback of 60 seconds), timeoutMs (default 30000, clamped at 120000), and subjectContains (case-insensitive). Address has email, domain, and localPart, plus:

Member	Signature	Notes
`wait(opts?)`	`(WaitEmailOptions) => Promise<Message>`	`text` and `html` are filled, clipped at 256 KB
`receive(body)`	`({ from, subject?, text?, html?, headers? }) => Promise<InjectEmailMessageResponse>`	Inject. Returns `{ eventId, receivedAt, inbox }` on 202. `headers` is `Record<string, string[]>`
`clear()`	`() => Promise<void>`	Deletes every message for this address
`messages.list(opts?)`	`({ cursor?, limit?, q? }) => Promise<CursorPage<Message>>`	`q` matches subject, sender, or local part
`messages.get(messageId)`	`(string) => Promise<Message>`	Adds `text` and `html`, clipped at 256 KB

Message carries otp, links, subject, from, to, headers, bodyPreview, and sha256, plus raw(): Promise<File> (the .eml), source(): Promise<{ source, truncated }>, delete(), listOtp(), and listLinks(). Do not rely on attachments today: inject cannot attach files and real mail does not list them yet.

const address = await client.email.address({ label: "signup" });
await address.receive({
  from: "noreply@example.com",
  subject: "Your code",
  text: "Your verification code is 482913",
});
const message = await address.wait();
console.log(message.text, message.otp?.[0]?.value);
await address.clear();

client.apiKeys

Method	Signature	Returns
`list()`	`() => Promise<ApiKeyDto[]>`
`listPage(page, size)`	`(number, number) => Promise<Page<ApiKeyDto>>`
`create(body)`	`(CreateApiKeyRequest) => Promise<ApiKeyCreateResponse>`	Full key only at creation
`revoke(id)`	`(string \| number) => Promise<void>`
`delete(id)`	`(string \| number) => Promise<void>`

client.dependencies

Method	Signature	Returns
`list()`	`() => Promise<ServiceSubscriptionDto[]>`
`listPage(page, size)`	`(number, number) => Promise<Page<ServiceSubscriptionDto>>`
`get(id)`	`(string \| number) => Promise<ServiceSubscriptionDto>`
`track(slug, options?)`	`(string, ServiceSubscribeRequest?) => Promise<ServiceSubscriptionDto>`	`options`: `componentId`, `alertSensitivity`
`updateAlertSensitivity(id, sensitivity)`	`(string \| number, string) => Promise<ServiceSubscriptionDto>`	`ALL`, `INCIDENTS_ONLY`, `MAJOR_ONLY`, `AWARENESS`
`delete(id)`	`(string \| number) => Promise<void>`

client.services

Read-only access to the third-party service status catalog (GitHub, Stripe, AWS, …).

Method	Signature
`list(options?)`	`(ServiceListFilters) => Promise<CursorPage<ServiceCatalogDto>>`
`get(slugOrId, options?)`	`(string, { summary? }) => Promise<ServiceDetailDto>`
`liveStatus(slugOrId)`	`(string) => Promise<ServiceLiveStatusDto>`
`categories()` / `summary()`	`Promise<CategoryDto[]>` / `Promise<GlobalStatusSummaryDto>`
`components(slugOrId, options?)`	`(string, { groupId? }) => Promise<ServiceComponentDto[]>`
`uptime(slugOrId, options?)`	`Promise<ServiceUptimeResponse>`
`componentUptime(slugOrId, componentId, options?)`	per-component uptime history
`batchComponentUptime(slugOrId, options?)`	`Promise<BatchComponentUptimeDto>`
`day(slugOrId, date)`	`(string, string) => Promise<ServiceDayDetailDto>`
`incidents(options?)` / `incident(slugOrId, incidentId)`	`Promise<Page<ServiceIncidentDto>>` / `Promise<ServiceIncidentDetailDto>`
`maintenances(slugOrId, options?)`	`Promise<ScheduledMaintenanceDto[]>`

client.maintenanceWindows

Method	Signature
`list(filters?)`	`(MaintenanceWindowFilters) => Promise<MaintenanceWindowDto[]>`
`listPage(...)`	`Promise<Page<MaintenanceWindowDto>>`
`get(id)`	`(string) => Promise<MaintenanceWindowDto>`
`create(body)` / `update(id, body)`	`Promise<MaintenanceWindowDto>`
`cancel(id)`	`(string) => Promise<void>`

client.deployLock

Method	Signature	Returns
`acquire(body)`	`(AcquireDeployLockRequest) => Promise<DeployLockDto>`	409 if held
`current()`	`() => Promise<DeployLockDto \| null>`
`release(lockId)`	`(string) => Promise<void>`
`forceRelease()`	`() => Promise<void>`

client.status

Method	Signature	Returns
`overview()`	`() => Promise<DashboardOverviewDto>`

client.statusPages

The largest namespace; root operations plus five sub-namespaces.

Method	Signature
`list()`	`() => Promise<StatusPageDto[]>`
`get(id)`	`(string \| number) => Promise<StatusPageDto>`
`create(body)`	`(CreateStatusPageRequest) => Promise<StatusPageDto>`
`update(id, body)`	`(string \| number, UpdateStatusPageRequest) => Promise<StatusPageDto>`
`delete(id)`	`(string \| number) => Promise<void>`
`reorderLayout(id, body)`	`(string \| number, ReorderPageLayoutRequest) => Promise<void>`

Sub-namespaces (each takes pageId as the first arg):

client.statusPages.components.list(pageId)
client.statusPages.components.create(pageId, body)
client.statusPages.components.update(pageId, componentId, body)
client.statusPages.components.delete(pageId, componentId)
client.statusPages.components.reorder(pageId, body)

client.statusPages.groups.list(pageId)
client.statusPages.groups.create(pageId, body)
client.statusPages.groups.update(pageId, groupId, body)
client.statusPages.groups.delete(pageId, groupId)

client.statusPages.incidents.list(pageId, options?)
client.statusPages.incidents.get(pageId, incidentId)
client.statusPages.incidents.create(pageId, body)
client.statusPages.incidents.update(pageId, incidentId, body)
client.statusPages.incidents.postUpdate(pageId, incidentId, body)
client.statusPages.incidents.publish(pageId, incidentId, body?)
client.statusPages.incidents.dismiss(pageId, incidentId)
client.statusPages.incidents.delete(pageId, incidentId)

client.statusPages.subscribers.list(pageId)
client.statusPages.subscribers.add(pageId, body)
client.statusPages.subscribers.remove(pageId, subscriberId)

client.statusPages.domains.list(pageId)
client.statusPages.domains.add(pageId, body)
client.statusPages.domains.verify(pageId, domainId)
client.statusPages.domains.remove(pageId, domainId)

client.forensics

Read-only audit trail for the detection engine. See Incident Forensics for the conceptual overview.

Method	Signature	Returns
`incidentTimeline(id)`	`(string \| number) => Promise<IncidentTimelineDto>`	State transitions, triggering evals, active policy snapshot
`checkTrace(checkId)`	`(string) => Promise<CheckTraceDto>`	Everything recorded for a single check execution
`policySnapshot(hashHex)`	`(string) => Promise<PolicySnapshotDto>`	Fetch policy snapshot by SHA-256 hash
`monitorRuleEvaluations(id, filters?)`	`(string \| number, RuleEvaluationFilters) => Promise<Page<RuleEvaluationDto>>`	Paginated rule evaluations
`monitorTransitions(id, filters?)`	`(string \| number, TransitionFilters) => Promise<Page<IncidentStateTransitionDto>>`	Paginated state transitions

RuleEvaluationFilters accepts ruleType, region, onlyMatched, from, to, page, and size. TransitionFilters accepts from, to, page, and size.

Exported types

All DTO and request types are re-exported from the package root:

import type {
  MonitorDto,
  CreateMonitorRequest,
  IncidentDto,
  AlertChannelDto,
  Page,
  CursorPage,
} from "@devhelm/sdk";

Types are generated from the OpenAPI specification, so they always match the current API.

Overview

TypeScript SDK

Python SDK

MCP Server

AI Skills

TypeScript Client Reference

Client initialization

Configuration options

Resource namespaces

client.monitors

client.incidents

client.alertChannels

client.notificationPolicies

client.tags

client.environments

client.secrets

client.resourceGroups

client.webhooks

client.inboxes

client.email

client.apiKeys

client.dependencies

client.services

client.maintenanceWindows

client.deployLock

client.status

client.statusPages

client.forensics

Exported types

Next steps

Error handling

Pagination

​Client initialization

​Configuration options

​Resource namespaces

​client.monitors

​client.incidents

​client.alertChannels

​client.notificationPolicies

​client.tags

​client.environments

​client.secrets

​client.resourceGroups

​client.webhooks

​client.inboxes

​client.email

​client.apiKeys

​client.dependencies

​client.services

​client.maintenanceWindows

​client.deployLock

​client.status

​client.statusPages

​client.forensics

​Exported types

​Next steps

Error handling

Pagination

Client initialization

Configuration options

Resource namespaces

client.monitors

client.incidents

client.alertChannels

client.notificationPolicies

client.tags

client.environments

client.secrets

client.resourceGroups

client.webhooks

client.inboxes

client.email

client.apiKeys

client.dependencies

client.services

client.maintenanceWindows

client.deployLock

client.status

client.statusPages

client.forensics

Exported types

Next steps