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`. Falls back to `DEVHELM_WORKSPACE_ID` env var, then `"1"`.
`timeout`	`float`	`30.0`	Per-request timeout in seconds.

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