Monitors
Create a monitor
Section titled “Create a monitor”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.
Required fields
Section titled “Required fields”| 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.
Optional fields
Section titled “Optional fields”| 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. |
Monitor types
Section titled “Monitor types”HTTP / HTTPS
Section titled “HTTP / HTTPS”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.
Ping ICMP
Section titled “Ping ICMP”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.
Check behavior
Section titled “Check behavior”- 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
List monitors
Section titled “List monitors”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" }]Get a monitor
Section titled “Get a monitor”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.”
Update a monitor
Section titled “Update a monitor”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.
Delete a monitor
Section titled “Delete a monitor”curl -X DELETE https://api.monitive.com/api/v1/monitors/1287 \ -H "Authorization: Bearer $MONITIVE_API_KEY"Your first monitor takes 30 seconds.
Sign in with GitHub, Google, Microsoft, or email, and your first check runs right away. 50 monitors, free, no card.