title: "Uptime Checks API" description: "Manage synthetic HTTP, TCP, and TLS expiry checks executed by your servers." last_updated: "2026-05-24"

Uptime Checks API

Uptime checks are synthetic probes (HTTP, TCP, TLS certificate expiry) executed from your own monitored servers. Each check has one or more probe servers; the agent runs the probe and POSTs results back to the server. Conceptual docs: Uptime checks.

All routes below require a bearer token.

List checks

GET/uptime-checks

Auth: bearer

Returns all uptime checks with probe server counts.

Response — 200 OK

{
  "checks": [
    {
      "id": 4,
      "user_id": 3,
      "name": "Production API",
      "check_type": "http",
      "target": "https://api.example.com/health",
      "enabled": 1,
      "expected_status_codes": "200,201,204",
      "max_latency_ms": 2000,
      "body_contains": "ok",
      "follow_redirects": 1,
      "tls_warn_days_before_expiry": 14,
      "timeout_seconds": 10,
      "alert_on_down": 1,
      "alert_on_recovery": 0,
      "alert_on_cert_expiry": 1,
      "last_status": "up",
      "last_checked_at": "2026-05-24T18:41:00Z",
      "probe_count": 2,
      "probe_servers": [
        { "id": 12, "hostname": "web-01.prod" },
        { "id": 18, "hostname": "web-02.prod" }
      ],
      "created_at": "2026-05-01T09:00:00Z"
    }
  ],
  "plan_limit": 25,
  "current_count": 1,
  "plan": "pro"
}

Create check

POST/uptime-checks

Auth: bearer

Request body

Field	Type	Required	Notes
`name`	string	yes	1-100 chars.
`check_type`	string	yes	`http`, `tcp`, or `tls_expiry`.
`target`	string	yes	For `http`: full URL (`http://` or `https://`), max 500 chars. For `tcp`/`tls_expiry`: `host:port`.
`probe_server_ids`	array	yes	1-100 server IDs that will run this probe; all must belong to your account.
`expected_status_codes`	string	no	Comma-separated codes or ranges, each `100`-`599`. E.g. `"200,201,2xx-3xx"` (numeric ranges like `200-299`). HTTP only.
`max_latency_ms`	integer	no	`1`-`60000`. Probe fails if exceeded.
`body_contains`	string	no	Up to 500 chars, no control chars. HTTP only.
`follow_redirects`	boolean	no	Default `true`. HTTP only.
`tls_warn_days_before_expiry`	integer	no	`1`-`365`. Default `14`. Used by `tls_expiry`.
`timeout_seconds`	integer	no	`1`-`60`. Default `10`.
`alert_on_down`	boolean	no	Default `true`.
`alert_on_recovery`	boolean	no	Default `false`.
`alert_on_cert_expiry`	boolean	no	Default `true`.

{
  "name": "Production API",
  "check_type": "http",
  "target": "https://api.example.com/health",
  "expected_status_codes": "200,204",
  "max_latency_ms": 2000,
  "body_contains": "ok",
  "timeout_seconds": 10,
  "probe_server_ids": [12, 18]
}

Response — 201 Created

{
  "check": {
    "id": 4,
    "name": "Production API",
    "check_type": "http",
    "target": "https://api.example.com/health",
    "enabled": 1,
    "status": null
  },
  "probe_server_ids": [12, 18]
}

Errors

400 — validation_failed with issues. Includes probe_server_ids errors (count, ownership).
402 — plan_limit_reached.

Get check

GET/uptime-checks/:id

Auth: bearer

Returns the check, probe servers, latest result per probe, last 100 results overall, and a 24-hour uptime percentage.

Response — 200 OK

{
  "check": { "id": 4, "name": "Production API", "status": "up" },
  "probe_servers": [
    { "id": 12, "hostname": "web-01.prod" },
    { "id": 18, "hostname": "web-02.prod" }
  ],
  "per_probe_latest": [
    {
      "server_id": 12,
      "hostname": "web-01.prod",
      "executed_at": "2026-05-24T18:41:00Z",
      "ok": 1,
      "status_code": 200,
      "latency_ms": 142,
      "error_kind": null,
      "error_message": null
    }
  ],
  "recent_results": [
    {
      "id": 91022,
      "check_id": 4,
      "server_id": 12,
      "hostname": "web-01.prod",
      "executed_at": "2026-05-24T18:41:00Z",
      "ok": 1,
      "status_code": 200,
      "latency_ms": 142,
      "error_kind": null,
      "error_message": null,
      "tls_days_remaining": 73
    }
  ],
  "uptime_pct_24h": 99.81
}

uptime_pct_24h is null if no probe results exist in the last 24 hours.

Errors

404 — not_found.

Update check

PUT/uptime-checks/:id

Auth: bearer

Updatable fields: name, target, enabled, timeout_seconds, expected_status_codes, max_latency_ms, body_contains, follow_redirects, tls_warn_days_before_expiry, alert_on_down, alert_on_recovery, alert_on_cert_expiry. check_type cannot be changed after creation.

You can also pass probe_server_ids (array of integers, at least 1) to replace the set of probe servers.

Response — 200 OK

{ "check": { "id": 4, "name": "Production API v2", "status": "up" } }

Errors

400 — validation_failed (includes invalid target shape, or unowned probe_server_ids).
404 — not_found.

Delete check

DELETE/uptime-checks/:id

Auth: bearer

Deletes the check, its probe assignments, and result history.

Response — 200 OK

{ "ok": true }

Errors

404 — not_found.

ℹ

Probe results are POSTed to the API by your agent on the assigned probe servers. There is no public endpoint for submitting probe results manually — they're written by the authenticated agent stream.