API reference

GET /account

Current account, plan limits and usage · any scope

Works with any scope. Useful before creating monitors (check remaining capacity).

GET /monitors

List monitors · scope monitors:read

POST /monitors

Create a Heartbeat or HTTP Check monitor · scope monitors:write

Send Idempotency-Key to make retries safe: repeating the request with the same key and body returns the original response (header Idempotent-Replayed: true) instead of creating a second monitor. Keys are kept for 24 hours.

If external_id is already used by another monitor of the account, nothing is created and the response is 409 MONITOR_ALREADY_EXISTS with details.monitor_id — read or update that monitor instead. Unlike Idempotency-Key (kept 24 hours), this protection is permanent.

For Heartbeat monitors the response contains heartbeat.ping_url — store it now, it is shown only once (tokens are stored hashed; use rotate-token to get a new one). A replay of the same request with the same Idempotency-Key within 24 hours returns the same response, ping URL included; replays are stored encrypted and deleted when the 24 hours pass.

Request body — MonitorCreate

{
    "type": "heartbeat",
    "external_id": "production:bank-import",
    "name": "Bank import",
    "timezone": "Europe/Warsaw",
    "schedule": {
        "preset": "daily",
        "days": [
            1,
            2,
            3,
            4,
            5
        ],
        "start": "06:00",
        "end": "07:00"
    },
    "calendar": {
        "skip_holidays": true
    }
}

{
    "type": "http",
    "name": "Production API",
    "timezone": "Europe/Warsaw",
    "schedule": {
        "preset": "custom",
        "days": [
            1,
            2,
            3,
            4,
            5,
            6,
            7
        ],
        "windows": [
            {
                "start": "07:00"
            },
            {
                "start": "19:00"
            }
        ]
    },
    "http": {
        "url": "https://api.example.com/health",
        "expected_status": "2xx",
        "headers": [
            {
                "name": "X-API-Key",
                "value": "secret-key"
            }
        ]
    },
    "recovery": {
        "enabled": true,
        "interval_minutes": 15
    }
}

GET /monitors/{id}

Get a monitor · scope monitors:read

PATCH /monitors/{id}

Update a monitor · scope monitors:write

Partial update. Top-level fields and fields inside calendar, http, notifications and recovery replace the current values; schedule and arrays (e.g. http.headers) are replaced as a whole. A header sent without value keeps its stored secret. Schedule changes apply from the next window; history is never rewritten. The monitor type cannot be changed.

Request body — MonitorPatch

{
    "schedule": {
        "preset": "hourly",
        "days": [
            1,
            2,
            3,
            4,
            5
        ],
        "hour_from": 8,
        "hour_to": 18,
        "minute_start": 0,
        "minute_end": 15
    },
    "notifications": {
        "extra_email": "ops@example.com"
    }
}

DELETE /monitors/{id}

Delete a monitor · scope monitors:write

Stops monitoring immediately and revokes the ping URL. History is removed together with the plan retention.

POST /monitors/{id}/pause

Pause a monitor · scope monitors:write

No windows are expected while paused. An open incident is closed without a recovery e-mail. Idempotent.

POST /monitors/{id}/resume

Resume a paused monitor · scope monitors:write

Counts towards the plan's active monitor limit. Idempotent.

POST /monitors/{id}/rotate-token

Generate a new Heartbeat ping URL · scope monitors:write

The previous URL stops working immediately. The new URL is returned only in this response — it is not stored in plain text. This is also the way to recover a lost URL.

GET /monitors/{id}/runs

Run history · scope monitors:read

Windows (Heartbeat) or checks (HTTP) that already started, newest first, within the plan's history retention (Free: 30 days).

GET /monitors/{id}/incidents

Incident history · scope incidents:read