WatchFor

The WatchFor REST API — manage monitors, incidents and maintenance windows programmatically with simple Bearer-authenticated JSON endpoints.

The WatchFor API is a predictable REST API over HTTPS: JSON in, JSON out, Bearer API keys, and stable versioning in the path.

https://watchfor.io/api/v1

Quick start

Create an API key in Settings → API keys (the full key is shown once).
Call any endpoint with the key in the Authorization header:

curl https://watchfor.io/api/v1/me \
  -H "Authorization: Bearer wf_live_YOUR_KEY"

{
  "object": "api_key_identity",
  "organization": {
    "id": "6f0a…",
    "name": "Acme Cloud",
    "slug": "acme-cloud"
  },
  "scope": "read"
}

List your monitors:

curl "https://watchfor.io/api/v1/monitors?limit=10" \
  -H "Authorization: Bearer wf_live_YOUR_KEY"

Conventions

Versioning — the version lives in the path (/api/v1). Breaking changes only ever ship as a new version; v1 responses may gain new fields, never lose or repurpose existing ones.
Timestamps — always ISO 8601 in UTC (2026-08-24T10:00:00.000Z).
Lists — wrapped in { "object": "list", "data": [...], "has_more": … }. Monitors paginate with an opaque next_cursor; incidents use limit/offset.
Errors — a stable machine-readable envelope; see Errors & rate limits.
Scopes — keys are read or write; mutating endpoints require write. See Authentication.

OpenAPI

The machine-readable contract lives at GET /api/v1/openapi.json — import it into Postman/Insomnia or point a client generator at it. No API key needed to fetch the spec.

Resources

Resource	Endpoints
Monitors	create, list, get, update, pause, resume, delete, check-now, bulk, uptime, checks, alert-rules
Locations	list
Monitor types reference	per-type metrics + config fields (also `GET /meta/monitor-types`)
Incidents	list, get, acknowledge, resolve, mark-maintenance, stats
Organization summary	`GET /v1/summary` — see below
Maintenance windows	list, get, create, update, delete
Contacts	contacts + groups: create, list, get, update, delete
Status pages	create, list, get, update, delete + announcements
Plan & limits	get plan, limits, usage + who is on call
MCP server	connect AI agents — 26 tools over the same API

Heartbeat check-ins don't need an API key — each heartbeat monitor has its own unique ping URL. See heartbeat monitoring.

Organization summary

GET /v1/summary — a one-call snapshot of the whole workspace, built for wallboards, chat bots and scripts that would otherwise stitch together several list calls:

curl https://watchfor.io/api/v1/summary \
  -H "Authorization: Bearer wf_live_YOUR_KEY"

{
  "object": "summary",
  "monitors": { "total": 42, "up": 40, "down": 1, "paused": 1, "unknown": 0, "health_score": 97 },
  "incidents": { "firing": 1, "firing_critical": 1, "firing_warning": 0, "acknowledged": 0, "started_24h": 3 },
  "open_maintenance_windows": 0
}

health_score is the percentage of non-paused, non-new monitors that are up — the same number the dashboard shows. A monitor with an active incident counts as down even if its stored status hasn't refreshed yet. For period statistics (MTTR, most unstable monitors) see incident statistics.

API overview

Quick start

Conventions

OpenAPI

Resources

Organization summary

On this page