DevHelm Python SDK

Typed Python client for the DevHelm monitoring API — monitors, incidents, alerting, and more.

Installation

pip install devhelm

Quick Start

from devhelm import Devhelm

client = Devhelm(token="your-api-token")

# List all monitors
monitors = client.monitors.list()
for m in monitors:
    print(f"{m.name} — {m.type}")

# Create a monitor
monitor = client.monitors.create({
    "name": "My API Health",
    "type": "HTTP",
    "config": {"url": "https://api.example.com/health", "method": "GET"},
    "frequencySeconds": 60,
    "regions": ["us-east"],
    # `managedBy` records who reconciles drift on this resource. Use
    # "DASHBOARD" (the default for one-off SDK scripts), "CLI" if the
    # monitor lives in a `devhelm.yml` you re-deploy, or "TERRAFORM"
    # if it lives in `.tf` you re-apply.
    "managedBy": "DASHBOARD",
})

# Get a single monitor
monitor = client.monitors.get(monitor.id)

# Inbound testing. `webhooks` stays outbound alert delivery.
inbox = client.inboxes.create(name="stripe")
event = inbox.wait(timeout_ms=30_000, http={"method": "POST"})
payment = event.json()
raw = event.raw()

to = client.email.address(label="signup")
message = to.wait(timeout_ms=60_000, subject_contains="code")
code = message.otp[0].value if message.otp else None
pdf = message.attachments[0].bytes() if message.attachments else None

# Pause / resume
client.monitors.pause(monitor.id)
client.monitors.resume(monitor.id)

# Delete
client.monitors.delete(monitor.id)

Configuration

from devhelm import Devhelm

client = Devhelm(
    token="your-api-token",            # required (or DEVHELM_API_TOKEN env var)
    org_id="1",                        # optional — see notes below
    workspace_id="1",                  # optional — see notes below
    base_url="https://api.devhelm.io", # optional, defaults to production
)

Environment variables are used as fallbacks when constructor arguments are not provided:

Resources

The client exposes the following resource modules:

Pagination

List methods auto-paginate by default. For manual page control:

# Auto-paginate (fetches all pages)
all_monitors = client.monitors.list()

# Manual page control
page = client.monitors.list_page(page=0, size=20)
print(page.data)       # list of monitors
print(page.has_next)   # True if more pages
print(page.has_prev)   # True if previous page exists

# Cursor pagination (for check results)
results = client.monitors.results(monitor_id, limit=50)
print(results.data)
print(results.next_cursor)
print(results.has_more)

Error Handling

The SDK raises three top-level error types (see 040-codegen-policies.md):

• DevhelmValidationError — local request/response shape validation failed.
• DevhelmApiError — the API returned a non-2xx status. Subclassed by HTTP class for ergonomics: DevhelmAuthError (401/403), DevhelmNotFoundError (404), DevhelmConflictError (409), DevhelmRateLimitError (429), DevhelmServerError (5xx).
• DevhelmTransportError — the request never reached a server response (connection refused, timeout, TLS failure, etc.).

Every DevhelmApiError carries:

• status — the HTTP status code
• code — coarse machine-readable category (e.g. NOT_FOUND, RATE_LIMITED); switch on this, not the human-readable message
• request_id — the per-request id from the X-Request-Id response header; always include this in support tickets

from devhelm import Devhelm, DevhelmAuthError, DevhelmError

client = Devhelm(token="bad-token")

try:
    client.monitors.list()
except DevhelmAuthError as e:
    print(f"Auth failed: {e.message} (HTTP {e.status}, request_id={e.request_id})")
except DevhelmError as e:
    print(f"API error [{e.code}]: {e.message}")

Development

# Install dependencies
uv sync

# Run tests
make test

# Lint + format check
make lint

# Type check
make typecheck

# Regenerate types from OpenAPI spec
make typegen

License

MIT