Monitors API

Embed
Preview of the card
<a href="https://watchtowerops.net/docs/monitors"><img src="https://watchtowerops.net/docs/_api/public/orgs/aa5959cb-1a0b-4a9a-bc9a-913e7ac31cd9/spaces/b7aac181-9916-4805-b253-becc5fd2ca62/pages/23a059ff-cb56-4472-b63f-20153a982b41/social-card.svg?v=3e7ae33eec8b" alt="Monitors API" width="600" height="315"></a>

POST /v1/projects/{prj}/monitors creates a monitor. The body is the monitor spec; unknown fields are refused with a 422 naming the field. Kinds and their config are in check types.

{
  "env_id": "env_01m72xrg...",
  "name": "formflow health",
  "kind": "http",
  "service": "formflow-web",
  "config": {"url": "https://formize.net/api/health", "method": "GET"},
  "assertions": ["[STATUS] == 200"],
  "interval_s": 60,
  "timeout_ms": 10000,
  "locations": ["default"],
  "retry": {"mode": "fixed", "max": 1, "delay_ms": 1000, "recheck": false},
  "quorum": {"min_fail": 1},
  "alert": true
}

Field

Notes

env_id, name, kind, config

Required.

interval_s

10 to 86400, default 60 (http, tcp, udp, dns, icmp and grpc may go down to 1; playwright starts at 300).

timeout_ms

100 to 60000 (browser: 120000), at most the interval, default 10000.

retry

An object, not a number: mode (none, fixed, linear, exponential), max 0 to 3, delay_ms 100 to 60000, recheck (rerun once from another data centre of the same region before counting a location down). Default {"mode":"none","max":0,"delay_ms":1000,"recheck":false}.

quorum

An object: min_fail is how many locations must fail for the round to fail (1 to the number of locations). null means 1 for one location, else the majority. With one location it has no effect.

locations

Up to 10; default ["default"]. See below.

degraded_ms, alert, enabled

A passing check slower than degraded_ms is degraded, not down; alert creates the managed alert rule (default true).

Locations

GET /v1/locations/public lists the managed locations. Today there is one: default, with no static egress IP list (egress_ips is empty), so there is nothing to allowlist yet; see static IPs. Multi-region checks and a region quorum are not available yet: quorum.min_fail only means something once a monitor runs from several locations. Private locations (private:<name>) work today and can be combined with default for a two-location quorum; see private locations.

Change a monitor

  • PUT .../monitors/{monitor} replaces the whole spec.

  • PATCH .../monitors/{monitor} is a JSON merge patch (RFC 7386) over the monitor as GET returns it: an object merges key by key, null removes a key, anything else replaces. The merged monitor is validated as for PUT. Send If-Match: <updated_at> (the value GET returns) to get 412 when someone else changed it first.

curl -sS -X PATCH "$WT_API/v1/projects/$PRJ/monitors/$MON" -H "Authorization: Bearer $WT_API_KEY" \
  -H "Content-Type: application/json" -H "If-Match: $UPDATED_AT" \
  -d '{"interval_s":120,"retry":{"max":2}}'

POST .../monitors/{monitor}/slo creates an SLO on the monitor.

Synthetic spans

Each check run is also written as an uptime.check span. These spans belong to the service watchtower-synthetics, carry wt.synthetic=true, and name the monitored service in target_service, so they never mix with the application's own spans. RED metrics, Apdex and release scores leave them out.

Updated