watchfor (Python)

Official Python SDK + CLI for WatchFor — uptime & infrastructure monitoring (monitors, alert rules, incidents, maintenance windows) over the REST API. Zero dependencies (standard library only).

There is also a TypeScript SDK, an MCP server and an A2A agent for AI agents.

Install

pip install watchfor

Quick start

from watchfor import WatchFor

wf = WatchFor(api_key="wf_live_...")  # create keys in Settings → API keys

# One-call org snapshot
print(wf.summary())

# List monitors
for m in wf.monitors.list()["data"]:
    print(m["name"], m["status"])

# Create a monitor (idempotency key optional, for safe retries)
mon = wf.monitors.create(
    {
        "name": "example.com",
        "type": "http",
        "target": "https://example.com",
        "interval": 300,
        "locations": ["<location-id>"],  # from wf.locations()
    },
    idempotency_key="create-example-1",
)

# Diagnose: firing incidents right now
for inc in wf.incidents.list(status="firing")["data"]:
    print(inc["message"], inc["severity"])

# False positive? Keep the resolved incident on record but drop it from
# uptime, SLA, reports and the status page (include() undoes it)
wf.incidents.exclude(19351, reason="Probe-side DNS hiccup")

# Irreversible: wipe a monitor's checks and incidents; uptime restarts "since reset"
wf.monitors.reset(mon["id"])

Resource namespaces: wf.monitors, wf.alert_rules, wf.incidents, wf.maintenance_windows, wf.contacts, wf.contact_groups. Top-level: wf.summary(), wf.plan(), wf.me(), wf.locations(), wf.monitor_types(), wf.incident_stats(period=...), wf.notifications(...), wf.activity(...).

Errors raise WatchForError with .status, .code and .message.

CLI

export WATCHFOR_API_KEY=wf_live_...
watchfor summary
watchfor monitors
watchfor incidents --status firing
watchfor checks <monitor_id>
watchfor report --period 30d

Auth & scopes

Keys carry a scope: read (all GET endpoints) or write (read plus create/update/delete). See authentication. The API is also reachable via OAuth 2.1 for MCP clients.

Reference

• OpenAPI spec: https://watchfor.io/openapi.json
• Guides: https://watchfor.io/docs/api

MIT License.