API

Checks

Scheduled uptime monitors through the API: create, edit, pause or resume them, settle per-run credits, inspect runs, and deliver email + signed webhook alerts.

On this page

Create a check
Per-run credit settlement
Manage, edit and remove checks
Results and incidents
Webhooks

Create a check

POST/v1/checks

Answers 201 with the created check.

Field	What it is
`name`	Display label for the monitor.
`type`	`http`, `tcp_connect` or `icmp_ping`.
`target`	Hostname or IP address to monitor.
`port`, `family`	Optional port and `ipv4` or `ipv6`.
`method`, `path`	For HTTP checks (`HEAD` on all targets; `GET` unlocked on verified targets).
`interval_seconds`	`300` by default; `60` and `30` unlocked once the target is verified.
`locations`	1 to 3 two-letter ISO country codes, or `["ANY"]`.
`alert_email`	Boolean (`true` by default). Emails the account address on outage and recovery state changes.
`webhook_url`, `webhook_secret`	HTTPS port-443 endpoint notified on state transitions, and the HMAC secret signing each delivery.

Request body

{
  "name": "Checkout API",
  "type": "http",
  "method": "GET",
  "target": "api.example.com",
  "path": "/healthz",
  "interval_seconds": 60,
  "locations": ["DE", "US"],
  "alert_email": true,
  "webhook_url": "https://hooks.example.com/hopbits",
  "webhook_secret": "whsec_example_32_char_signing_key"
}

An account can run up to 200 active checks. Returned check objects include alert_email, webhook_url, has_webhook_secret (boolean; raw secrets are never echoed back), credits_per_run, and skipped_reason (empty when running normally).

Per-run credit settlement

Each scheduled check cycle charges 1 credit per stored probe result (credits_per_run indicates the vantages configured per run). If your account has 0 available credits when a check is due, the cycle is skipped with skipped_reason: "insufficient_credits" without mutating quorum state or firing false outage alerts.

Manage, edit and remove checks

GET/v1/checks

Lists your checks.

GET/v1/checks/{id}

Returns one check.

PATCH/v1/checks/{id}

Updates any subset of { paused, name, interval_seconds, locations, method, path, webhook_url, webhook_secret, alert_email }. Pass "webhook_url": "" to clear an existing webhook.

PATCH /v1/checks/{id} request body

{
  "name": "Checkout API (EU + US)",
  "interval_seconds": 30,
  "locations": ["DE", "NL", "US"],
  "alert_email": true,
  "paused": false
}

POST/v1/checks/{id}/test-webhook

Sends a signed check.test webhook event to the check's configured webhook_url so you can verify connectivity and HMAC signature handling immediately.

DELETE/v1/checks/{id}

Deletes the check. Answers 204.

Results and incidents

GET/v1/checks/{id}/results

Latest scheduled runs (50 by default, up to 200 with ?limit=).

GET/v1/checks/{id}/incidents

Outage and degradation windows with start time, affected region, duration, and resolution timestamp.

A check's status is one of healthy, degraded, down, insufficient_data and paused.

Webhooks

Configure webhook_url (HTTPS on port 443) to receive state-change callbacks within seconds. Your endpoint has 5 seconds to respond with 2xx.

Event	When
`check.down`	Regional quorum confirmed the target is unreachable.
`check.degraded`	Target is failing from a subset of regions or exceeding thresholds.
`check.up`	Target recovered and passed quorum.
`check.test`	Triggered manually via `POST /v1/checks/{id}/test-webhook`.

Every delivery carries X-Hopbits-Event, X-Hopbits-Timestamp, and X-Hopbits-Signature:

Signature header

X-Hopbits-Signature: t=<unix time>,v1=<hex>

v1 is the hex HMAC-SHA-256 of <timestamp>.<body> keyed with webhook_secret.