Skip to content

Monitors

Terminal window
curl -X POST https://api.monitive.com/api/v1/monitors \
-H "Authorization: Bearer $MONITIVE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "api-prod",
"url": "https://example.com/",
"type": "http",
"expected_status": "200"
}'

The target hostname must resolve at creation time — the API runs an immediate test check, and unresolvable hosts are rejected up front. For http monitors, that immediate check sends the configured method, body, and headers (see Send a custom HTTP request) — a non-GET request hits the target before the first scheduled check runs.

The response wraps the monitor and its first state snapshot:

{
"monitor": {
"id": 1287,
"number": 14,
"ref": "k7q2mx-14",
"name": "api-prod",
"url": "https://example.com/",
"type": "http",
"interval_sec": 60,
"expected_status": "200",
"enabled": true,
"created_at": "2026-05-07T10:21:00Z"
},
"state": {
"status": "up",
"last_check_at": "2026-05-07T10:21:01Z",
"evidence_buffer": [
{
"region": "EU",
"status_code": 200,
"ttfb_ms": 182
}
]
}
}

Notes for integrators:

  • Unknown request fields are silently ignored — the API is forward-compatible.
  • Timestamps in responses (e.g. last_check_at) use RFC 3339 with nanosecond precision. If your client library caps at milliseconds, truncate before parsing.
Field Type Description
name string Monitor name (max 255 chars)
url string Target URL (max 2048 chars)
type string http, tcp, or ping. The API rejects dns and ssl with 400.

All string fields must be valid UTF-8 with no null bytes; URL fields must additionally be free of ASCII control characters (U+0000–U+001F and U+007F). Violations return 400 before the SSRF guard runs.

For HTTP, TCP, and ping monitors, the immediate test check populates state.status with up or down. The create response uses unknown if the probe is unavailable, the kill switch is engaged, or the URL fails the dispatch-time SSRF guard because of DNS rebinding. A disabled monitor whose test check reports down also keeps unknown until its first scheduled check after you enable it.

Field Type Default Description
expected_status string "200" Single HTTP status code as a string ("100"–"599"). Range or list values (e.g. "200-399", "200,201") are rejected — see Errors.
body_match string — Response body must contain this string (max 1024 chars). The field may be absent from responses when unset; treat absent and null identically.
interval_sec integer 60 Check interval in seconds (minimum 60)
enabled boolean true Whether the monitor is actively checking. Set false to pause without deleting.
maintenance object {"type": "none"} Maintenance window. {"type": "daily", "start_time", "end_time", "timezone"} for a recurring window, {"type": "once", "starts_at", "ends_at"} for a single span, or {"type": "none"} to clear it. On PUT, omitting the field entirely leaves the stored window unchanged — it isn’t the same as {"type": "none"}. Responses echo starts_at/ends_at normalized to UTC. See Maintenance windows for the full field list per type, validation errors, and the response shape.

Checks status code, optional body match, full timing breakdown (DNS, connect, TLS, TTFB, download).

Connects to a service port. Restricted to common service ports for abuse prevention.

Basic reachability check.

The dns type is defined in the wire format but isn’t available. The API rejects create and update requests for this type with 400.

The ssl type is defined in the wire format but isn’t available. The API rejects create and update requests for this type with 400.

  • Monitor count — 50 monitors per account on the free plan (see Pricing)
  • Check interval — every minute
  • Phase-spread scheduling — checks are spread across the interval window, not clustered at the top of the minute
  • Cross-region confirmation — any failure triggers re-checks from 2 additional regions. State flips only when 2 of 3 agree.
  • Exponential backoff — sustained-down monitors back off from 1 min to 5 min after 10 minutes of continuous downtime
  • Flap detection — monitors transitioning more than 10 times per hour are flagged as flapping
Terminal window
curl https://api.monitive.com/api/v1/monitors \
-H "Authorization: Bearer $MONITIVE_API_KEY"

The list endpoint returns every monitor on the account in a single response. There is no filtering or pagination — ?limit, ?offset, ?status, and ?type are accepted but silently ignored. Apply filters client-side.

The list response is a bare JSON array of monitor records with the current status and last_check_at flattened into each entry (no {monitor, state} wrapping). For the full state — including evidence_buffer — use GET /api/v1/monitors/{id}.

Response shape (abridged):

[
{
"id": 1287,
"number": 14,
"ref": "k7q2mx-14",
"name": "api-prod",
"url": "https://example.com/",
"type": "http",
"interval_sec": 60,
"expected_status": "200",
"enabled": true,
"created_at": "2026-05-07T10:21:00Z",
"status": "up",
"last_check_at": "2026-05-07T10:21:01Z"
}
]
Terminal window
curl https://api.monitive.com/api/v1/monitors/1287 \
-H "Authorization: Bearer $MONITIVE_API_KEY"

Response (single envelope):

{
"monitor": {
"id": 1287,
"number": 14,
"ref": "k7q2mx-14",
"name": "api-prod",
"url": "https://example.com/",
"type": "http",
"interval_sec": 60,
"expected_status": "200",
"enabled": true,
"created_at": "2026-05-07T10:21:00Z"
},
"state": {
"status": "up",
"last_check_at": "2026-05-07T10:25:43Z",
"evidence_buffer": [
{
"region": "EU",
"timestamp": "2026-05-07T10:25:43Z",
"status_code": 200,
"ttfb_ms": 174
},
{
"region": "US",
"timestamp": "2026-05-07T10:24:42Z",
"status_code": 200,
"ttfb_ms": 198
}
]
}
}

Every /monitors/{monitorID}... route accepts a ref (<account handle>-<number>, e.g. k7q2mx-14) in place of the numeric id — curl .../monitors/k7q2mx-14 is equivalent to the numeric form above.

A value that’s neither a numeric id nor a well-formed ref (e.g. /monitors/abc) returns 400 invalid monitor ID. A missing id, or a ref that doesn’t resolve or belongs to another account, returns 404 monitor not found — the same body in both cases, so a caller can’t distinguish “wrong account’s ref” from “no such id.”

Terminal window
curl -X PUT https://api.monitive.com/api/v1/monitors/1287 \
-H "Authorization: Bearer $MONITIVE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "api-prod-v2"}'

PUT accepts a partial body — fields you omit keep their current values. PATCH is not supported and returns 405.

Terminal window
curl -X DELETE https://api.monitive.com/api/v1/monitors/1287 \
-H "Authorization: Bearer $MONITIVE_API_KEY"