Documentation

Everything here applies to both the hosted service and the self-hosted build unless noted otherwise.

Quickstart

Create your first check from the dashboard, or from the command line:

curl -X POST https://api.statlark.dev/v1/checks \
  -H "Authorization: Bearer $STATLARK_TOKEN" \
  -d '{"url":"https://example.com/health","interval":30}'

The first result usually arrives within a minute. Until two data points exist the check reports pending rather than up.

Check types

TypeWhat it doesDefault interval
httpSends a GET, follows up to 3 redirects, asserts the status code30s
tcpOpens a connection to host:port and closes it60s
icmpThree echo requests, reports median round-trip60s

For http checks you can additionally require that the response body contains a string with match_body, which is useful when an application returns 200 while being broken underneath.

HTTP API

The API is REST over JSON. Tokens are created per-project and can be scoped read-only. Rate limit is 120 requests per minute; exceeding it returns 429 with a Retry-After header.

GET  /v1/checks           list checks
GET  /v1/checks/:id       single check with last 24h of results
POST /v1/checks           create
DEL  /v1/checks/:id       remove

Webhooks

Incident webhooks are delivered at least once and may repeat, so make your handler idempotent by keying on incident_id. Payloads are signed with HMAC-SHA256 in the X-Statlark-Signature header.

{
  "incident_id": "inc_9f3c21",
  "check": "api-health",
  "state": "down",
  "started_at": "2026-09-07T09:14:03Z",
  "regions_failing": ["fi-hel", "de-fra"]
}

Self-hosted

A single static binary, no external database — results live in an embedded store and are compacted nightly. Point it at a config file and run it under systemd:

statlark serve --config /etc/statlark/config.yml

Storage grows by roughly 4 MB per check per month at a 30-second interval. Retention defaults to 90 days.

Changelog