Python Client Reference

Complete reference for the devhelm Python SDK (v1.3.0). Every list/get returns a Pydantic model; every body parameter accepts either a dict or the corresponding Pydantic request class.

Client initialization

from devhelm import Devhelm

client = Devhelm(
    token="dh_live_xxxxxxxx",
    base_url="https://api.devhelm.io",
    org_id=None,
    workspace_id=None,
    timeout=30.0,
)

Parameter	Type	Default	Description
`token`	`str`	`""`	API token. Falls back to the `DEVHELM_API_TOKEN` env var when empty.
`base_url`	`str`	`https://api.devhelm.io`	API base URL.
`org_id`	`str \| None`	`None`	Sets `x-phelm-org-id`. Falls back to `DEVHELM_ORG_ID` env var, then `"1"`.
`workspace_id`	`str \| None`	`None`	Sets `x-phelm-workspace-id` when set or when `DEVHELM_WORKSPACE_ID` is set. Omit it when the organization has one workspace.
`timeout`	`float`	`30.0`	Per-request timeout in seconds.

Devhelm() with no arguments reads DEVHELM_API_TOKEN and, when set, DEVHELM_WORKSPACE_ID. Leave the workspace unset when the organization has one workspace. DEVHELM_API_URL is not read; pass base_url. The client is built on httpx.Client. It is synchronous and thread-safe; share one instance across threads (see concurrency patterns).

Resource namespaces

The client exposes 19 resources. List/get/delete signatures return Pydantic DTOs from devhelm.types; mutations accept RequestBody[...] (dict or model instance).

client.monitors

Method	Signature	Returns
`list(**filters)`	`(...) -> list[MonitorDto]`	Auto-fetches all pages
`list_page(page, size, **filters)`	`(int, int, ...) -> Page[MonitorDto]`	Single page
`get(id)`	`(int \| str) -> MonitorDto`
`create(body)`	`(RequestBody[CreateMonitorRequest]) -> MonitorDto`
`update(id, body)`	`(int \| str, RequestBody[UpdateMonitorRequest]) -> MonitorDto`
`delete(id)`	`(int \| str) -> None`
`pause(id)`	`(int \| str) -> MonitorDto`
`resume(id)`	`(int \| str) -> MonitorDto`
`test(id)`	`(int \| str) -> AssertionTestResultDto`
`results(id, cursor?, limit?)`	`(int \| str, str?, int?) -> CursorPage[CheckResultDto]`	Cursor pagination
`versions(id, page=0, size=20)`	`(int \| str, int, int) -> Page[MonitorVersionDto]`

Both list() and list_page() accept optional server-side filter kwargs: enabled, type, managed_by, tags (comma-separated), search, and environment_id.

client.incidents

Method	Signature	Returns
`list()`	`() -> list[IncidentDto]`
`list_page(page, size)`	`(int, int) -> Page[IncidentDto]`
`get(id)`	`(int \| str) -> IncidentDetailDto`
`create(body)`	`(RequestBody[CreateManualIncidentRequest]) -> IncidentDetailDto`
`resolve(id, body=None)`	`(int \| str, RequestBody[ResolveIncidentRequest]?) -> IncidentDetailDto`	Body optional

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

client.alert_channels

Method	Signature
`list()`	`() -> list[AlertChannelDto]`
`list_page(page, size)`	`(int, int) -> Page[AlertChannelDto]`
`get(id)`	`(int \| str) -> AlertChannelDto`
`create(body)`	`(RequestBody[CreateAlertChannelRequest]) -> AlertChannelDto`
`update(id, body)`	`(int \| str, RequestBody[UpdateAlertChannelRequest]) -> AlertChannelDto`
`delete(id)`	`(int \| str) -> None`
`test(id)`	`(int \| str) -> TestChannelResult`

client.notification_policies

Method	Signature
`list()` / `list_page(page, size)`	`list[NotificationPolicyDto]` / `Page[NotificationPolicyDto]`
`get(id)`	`NotificationPolicyDto`
`create(body)` / `update(id, body)`	`NotificationPolicyDto`
`delete(id)` / `test(id)`	`None` / `None`

client.tags

Method	Signature
`list()` / `list_page(page, size)`	`list[TagDto]` / `Page[TagDto]`
`get(id)`	`TagDto`
`create(body)` / `update(id, body)`	`TagDto`
`delete(id)`	`None`

client.environments

Method	Signature
`list()` / `list_page(page, size)`	`list[EnvironmentDto]` / `Page[EnvironmentDto]`
`get(slug)`	`EnvironmentDto`
`create(body)` / `update(slug, body)`	`EnvironmentDto`
`delete(slug)`	`None`

client.secrets

Method	Signature
`list()` / `list_page(page, size)`	`list[SecretDto]` / `Page[SecretDto]` (metadata only — values are never returned)
`create(body)` / `update(key, body)`	`SecretDto`
`delete(key)`	`None`

client.resource_groups

Method	Signature
`list()` / `list_page(page, size)`	`list[ResourceGroupDto]` / `Page[ResourceGroupDto]`
`get(id)`	`ResourceGroupDto`
`create(body)` / `update(id, body)`	`ResourceGroupDto`
`delete(id)`	`None`
`add_member(group_id, body)`	`ResourceGroupMemberDto`
`remove_member(group_id, member_id)`	`None`

client.webhooks

Method	Signature
`list()` / `list_page(page, size)`	`list[WebhookEndpointDto]` / `Page[WebhookEndpointDto]`
`get(id)` / `create(body)` / `update(id, body)`	`WebhookEndpointDto`
`delete(id)`	`None`
`test(id)`	`WebhookTestResult`

client.inboxes

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

Method	Signature	Notes
`list(*, search=None)`	`-> list[Inbox]`	Auto-fetches all pages
`list_page(page, size, *, search=None)`	`-> Page[Inbox]`
`activity(inbox_ids)`	`(list[str]) -> list[InboxActivity]`	24 hourly buckets (`hour`, `event_count`). An empty list makes no call
`get(id)`	`(str) -> Inbox`
`create(*, name, status=None, http_response=None, cors=None, retention_days=None, max_events=None)`	`-> Inbox`	Keyword-only
`update(id, body)`	`(str, RequestBody[UpdateWebhookInboxRequest]) -> Inbox`	`httpResponse` merges per field; `headers` replaces the whole map
`delete(id)`	`(str) -> None`	Deletes the inbox and its events
`wait(id, *, timeout_ms=30000, received_after=None, http=None)`	`-> Event`	Oldest match; raises on 408

Inbox has id (a UUID), name, status, http_url, public_token, http_response, cors, retention_days, max_events, created_at, and updated_at, plus:

Member	Signature	Notes
`wait(*, timeout_ms=30000, received_after=None, http=None)`	`-> Event`	Same as `client.inboxes.wait(str(inbox.id), ...)`
`update(body)` / `delete()`	`-> Inbox` / `-> None`
`events.list(*, cursor=None, limit=None, method=None, path=None)`	`-> CursorPage[ListedEvent]`	Newest first. `path` is a case-sensitive substring
`events.get(event_id)`	`(str) -> Event`	Body clipped at 256 KB
`events.delete(event_id)` / `events.clear()`	`-> None`	One event / every event

ListedEvent (a list row) has raw() -> bytes for the exact body bytes, save(path) -> Path, and delete(). Event (from get or wait) adds text() and json() over body. Wait returns the full body, not clipped. Wait arguments:

Argument	Type	Default	Notes
`received_after`	`datetime \| None`	`None`; server looks back 60 seconds	Matches `receivedAt >= received_after`. Pass it for a cursor, such as the previous event’s `received_at` plus 1 ms
`timeout_ms`	`int`	`30000`	Clamped at `120000`. A timeout raises `DevhelmApiError` with code `WAIT_TIMEOUT`
`http`	dict or `WaitHttpMatchers`	`None`	`{"method": ..., "pathPrefix": ...}`. Without `method`, `OPTIONS` requests are skipped

import httpx

inbox = client.inboxes.create(name="orders-test")
httpx.post(f"{inbox.http_url}/orders", json={"id": 42})
event = inbox.wait(http={"pathPrefix": "/orders"})
assert event.json() == {"id": 42}
inbox.delete()

In 1.10.0, Inbox has no last_event_at, and events have no body_truncated or raw_url. Use raw() for the exact bytes and body for the text. Verify signatures against raw(), not text(): text() is decoded UTF-8.

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	Notes
`address(*, label=None, domain=None)`	`-> Address`	Local part is `label-<8 hex>`. Without `domain`, finds or creates the assigned domain
`wait(*, to, timeout_ms=30000, received_after=None, subject_contains=None)`	`-> Message`	`to` is the full address
`wait_local_part(local_part, *, domain, timeout_ms=30000, received_after=None, subject_contains=None)`	`-> Message`
`domains.list(*, search=None)`	`-> list[Domain]`
`domains.list_page(page, size, *, search=None)`	`-> Page[Domain]`
`domains.activity(domain_ids)`	`(list[str]) -> list[DomainActivity]`	24 hourly buckets (`hour`, `message_count`)
`domains.get(name)`	`(str) -> Domain`	By domain name, not ID
`domains.create(*, name=None)`	`-> Domain`	No `name`: assigned domain. With `name`: custom domain
`domains.update(name, body)`	`(str, RequestBody[UpdateEmailDomainRequest]) -> Domain`	`status`: `disabled`, or `active` for an assigned domain
`domains.verify(name)`	`(str) -> Domain`	Checks DNS for a custom domain
`domains.delete(name)`	`(str) -> None`	Deletes every message on the domain

Wait takes received_after (omit it for the server lookback of 60 seconds), timeout_ms (default 30000, clamped at 120000), and subject_contains (case-insensitive). Address has email, domain, and local_part, plus:

Member	Signature	Notes
`wait(*, timeout_ms=30000, received_after=None, subject_contains=None)`	`-> Message`
`receive(*, from_, subject=None, text=None, html=None, headers=None)`	`-> InjectEmailMessageResponse`	Inject. Returns `event_id`, `received_at`, `inbox` on 202. `headers` is `dict[str, list[str]]`
`clear()`	`-> None`	Deletes every message for this address
`messages.list(*, cursor=None, limit=None, q=None)`	`-> CursorPage[Message]`	`q` matches subject, sender, or local part
`messages.get(message_id)`	`(str) -> Message`

Message has id, inbox, received_at, from_, to, subject, headers, body_preview, text, html, body_truncated, raw_url, otp, links, sha256, and attachments, plus raw() -> bytes (the .eml), save(path), source() -> MessageSource (source, truncated), delete(), list_otp(), and list_links(). Wait and get fill text and html, clipped at 256 KB. Do not rely on attachments today: inject cannot attach files and real mail does not list them yet.

address = client.email.address(label="signup")
address.receive(
    from_="noreply@example.com",
    subject="Your code",
    text="Your verification code is 482913",
)
message = address.wait()
assert message.text and "482913" in message.text
assert message.otp and message.otp[0].value == "482913"
address.clear()

client.api_keys

Method	Signature
`list()` / `list_page(page, size)`	`list[ApiKeyDto]` / `Page[ApiKeyDto]`
`create(body)`	`ApiKeyCreateResponse` (full key value returned once)
`revoke(id)` / `delete(id)`	`None` / `None`

There is no get(id) — fetch the list and filter, or store the ID from create().

client.dependencies

Method	Signature
`list()` / `list_page(page, size)`	`list[ServiceSubscriptionDto]` / `Page[ServiceSubscriptionDto]`
`get(id)`	`ServiceSubscriptionDto`
`track(slug, *, component_id?, alert_sensitivity?)`	`ServiceSubscriptionDto`
`update_alert_sensitivity(subscription_id, alert_sensitivity)`	`ServiceSubscriptionDto`
`delete(id)`	`None`

alert_sensitivity is one of ALL, INCIDENTS_ONLY, MAJOR_ONLY, or AWARENESS (the API default). component_id subscribes to a single component instead of the whole service.

client.deploy_lock

Method	Signature
`acquire(body)`	`DeployLockDto` (body must include `lockedBy`; `ttlMinutes` optional, default 30, max 60)
`current()`	`DeployLockDto \| None`
`release(lock_id)` / `force_release()`	`None` / `None`

client.maintenance_windows

Method	Signature
`list(monitor_id?, status?)`	`list[MaintenanceWindowDto]`
`list_page(page, size, ...)`	`Page[MaintenanceWindowDto]`
`get(id)`	`MaintenanceWindowDto`
`create(body)` / `update(id, body)`	`MaintenanceWindowDto`
`cancel(id)`	`None` (alerts resume immediately)

client.services

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

Method	Signature
`list(...)`	`CursorPage[ServiceCatalogDto]` (filters: `query`, `category`, `cursor`, `limit`)
`get(slug_or_id, summary?)`	`ServiceDetailDto`
`live_status(slug_or_id)`	`ServiceLiveStatusDto`
`categories()` / `summary()`	`list[CategoryDto]` / `GlobalStatusSummaryDto`
`components(slug_or_id)`	`list[ServiceComponentDto]`
`uptime(slug_or_id, period?)`	`ServiceUptimeResponse`
`component_uptime(slug_or_id, component_id, period?)`	per-component uptime history
`batch_component_uptime(slug_or_id, period?)`	`BatchComponentUptimeDto`
`day(slug_or_id, date)`	`ServiceDayDetailDto`
`incidents(...)` / `incident(slug_or_id, incident_id)`	`Page[ServiceIncidentDto]` / `ServiceIncidentDetailDto`
`maintenances(slug_or_id, status?)`	`list[ScheduledMaintenanceDto]`

client.status

Method	Signature
`overview()`	`DashboardOverviewDto`

client.status_pages

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

Method	Signature
`list()`	`list[StatusPageDto]`
`get(id)` / `create(body)` / `update(id, body)`	`StatusPageDto`
`delete(id)`	`None`
`reorder_layout(id, body)`	`None`

Sub-namespaces:

client.status_pages.components.list(page_id)
client.status_pages.components.create(page_id, body) / .update(page_id, comp_id, body) / .delete(page_id, comp_id) / .reorder(page_id, body)

client.status_pages.groups.list(page_id) / .create / .update / .delete

client.status_pages.incidents.list(page_id) / .get / .create / .update
client.status_pages.incidents.post_update(page_id, incident_id, body)
client.status_pages.incidents.publish(page_id, incident_id)
client.status_pages.incidents.dismiss(page_id, incident_id)
client.status_pages.incidents.delete(page_id, incident_id)

client.status_pages.subscribers.list(page_id) / .add / .remove

client.status_pages.domains.list(page_id) / .add / .verify / .remove

client.forensics

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

Method	Signature	Returns
`incident_timeline(id)`	`(int \| str) -> IncidentTimelineDto`	State transitions, triggering evals, active policy snapshot
`check_trace(check_id)`	`(str) -> CheckTraceDto`	Everything recorded for a single check execution
`policy_snapshot(hash_hex)`	`(str) -> PolicySnapshotDto`	Fetch policy snapshot by SHA-256 hash
`monitor_rule_evaluations(monitor_id, rule_type?, region?, only_matched?, from_?, to?, page=0, size=50)`	`... -> Page[RuleEvaluationDto]`	Paginated rule evaluations
`monitor_transitions(monitor_id, from_?, to?, page=0, size=50)`	`... -> Page[IncidentStateTransitionDto]`	Paginated state transitions

Pagination types

from devhelm import Page, CursorPage

Page

Attribute	Type	Description
`data`	`list[T]`	Items in this page
`has_next`	`bool`	Whether more pages exist
`has_prev`	`bool`	Whether previous pages exist
`total_elements`	`int \| None`	Server-reported total
`total_pages`	`int \| None`	Server-reported page count

CursorPage

Attribute	Type	Description
`data`	`list[T]`	Items in this page
`next_cursor`	`str \| None`	Cursor for the next page
`has_more`	`bool`	Whether more items exist

Pydantic models

Every request and response is a pydantic.BaseModel. The full set is re-exported from devhelm:

from devhelm import (
    CreateMonitorRequest, UpdateMonitorRequest, MonitorDto,
    CreateManualIncidentRequest, ResolveIncidentRequest, IncidentDetailDto,
    CreateAlertChannelRequest, AlertChannelDto,
    # ...
)

req = CreateMonitorRequest.model_validate({
    "name": "API Health",
    "type": "HTTP",
    "config": {"url": "https://api.example.com/health"},
    "frequencySeconds": 60,
})

The full DTO/request inventory is in devhelm/__init__.py.

Next steps

Error handling

Exception types and retry patterns.

Concurrency patterns

Run the sync client concurrently in threads or asyncio.

Overview

TypeScript SDK

Python SDK

MCP Server

AI Skills

Python Client Reference

Client initialization

Resource namespaces

client.monitors

client.incidents

client.alert_channels

client.notification_policies

client.tags

client.environments

client.secrets

client.resource_groups

client.webhooks

client.inboxes

client.email

client.api_keys

client.dependencies

client.deploy_lock

client.maintenance_windows

client.services

client.status

client.status_pages

client.forensics

Page

CursorPage

Pydantic models

Next steps

Error handling

Concurrency patterns

​Client initialization

​Resource namespaces

​client.monitors

​client.incidents

​client.alert_channels

​client.notification_policies

​client.tags

​client.environments

​client.secrets

​client.resource_groups

​client.webhooks

​client.inboxes

​client.email

​client.api_keys

​client.dependencies

​client.deploy_lock

​client.maintenance_windows

​client.services

​client.status

​client.status_pages

​client.forensics

​Pagination types

​Page

​CursorPage

​Pydantic models

​Next steps

Error handling

Concurrency patterns

Client initialization

Resource namespaces

client.monitors

client.incidents

client.alert_channels

client.notification_policies

client.tags

client.environments

client.secrets

client.resource_groups

client.webhooks

client.inboxes

client.email

client.api_keys

client.dependencies

client.deploy_lock

client.maintenance_windows

client.services

client.status

client.status_pages

client.forensics

Pagination types

Page

CursorPage

Pydantic models

Next steps