Automation

HTTP API

Create and manage checks programmatically. The API is a small JSON/REST interface used by scripts, CI, and the Terraform provider.

Base URL

https://api.alwaysbeat.com/api/v1

Authentication

Requests authenticate with an API key. Create one in the dashboard under Settings → API keys; the full key (prefixed dmf_) is shown once at creation — store it somewhere safe. Send it in the X-DMF-Token header:

curl -H "X-DMF-Token: dmf_xxxxxxxxxxxx" \
  https://api.alwaysbeat.com/api/v1/checks

An Authorization: Bearer <key> header is accepted too. A key grants full access to your account, so treat it like a password and revoke it from the dashboard if leaked.

Durations & timezones

In requests, durations are Go-style strings: 30s, 15m, 1h, 24h. In responses, the same values come back as integer seconds with an _s suffix (e.g. grace_s). Timezones are IANA names (Australia/Melbourne).

Endpoints

Method & path	Purpose
`GET /health`	Liveness probe (no auth).
`GET /checks`	List your checks.
`POST /checks`	Create a check.
`GET /checks/{id}`	Fetch one check.
`PATCH /checks/{id}`	Update fields (merge-patch).
`DELETE /checks/{id}`	Delete a check.
`POST /checks/{id}/pause`	Pause monitoring.
`POST /checks/{id}/resume`	Resume monitoring.
`GET /checks/{id}/events`	List recent events (paginated).
`GET /keys` · `POST /keys` · `DELETE /keys/{key_id}`	Manage API keys.

Create a check

POST/api/v1/checks

curl -X POST https://api.alwaysbeat.com/api/v1/checks \
  -H "X-DMF-Token: dmf_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "nightly-db-backup",
    "schedule": { "kind": "cron", "cron_expr": "0 3 * * *", "tz": "Australia/Melbourne" },
    "grace": "30m",
    "channels": ["email:ops@example.com", "webhook:https://example.com/hooks/dmf"],
    "max_run": "25m",
    "max_run_mode": "hung"
  }'

For an interval check, use "schedule": { "kind": "interval", "interval": "1h", "tz": "UTC" }. Optional fields: grace, channels, flap_cooldown, nag_interval, max_run, max_run_mode (hung | late).

Response `201`

{
  "check_id": "3f8a1c2e-...",
  "account_id": "...",
  "name": "nightly-db-backup",
  "status": "new",
  "schedule_kind": "cron",
  "cron_expr": "0 3 * * *",
  "tz": "Australia/Melbourne",
  "grace_s": 1800,
  "channels": ["email:ops@example.com", "webhook:https://example.com/hooks/dmf"],
  "max_run_s": 1500,
  "max_run_mode": "hung",
  "created_at": 1753000000,
  "updated_at": 1753000000,
  "ping_url": "https://ping.alwaysbeat.com/ping/3f8a1c2e-..."
}

Use the returned ping_url in your job. See Signaling jobs.

List checks

GET/api/v1/checks

{ "checks": [ { "check_id": "...", "status": "up", ... }, ... ] }

Update a check

PATCH/api/v1/checks/{id}

Send only the fields you want to change. Unparseable values are rejected (a bad duration is an error, not a silent no-op).

curl -X PATCH https://api.alwaysbeat.com/api/v1/checks/<id> \
  -H "X-DMF-Token: dmf_xxxx" -H "Content-Type: application/json" \
  -d '{ "grace": "45m", "channels": ["email:oncall@example.com"] }'

Pause & resume

POST/api/v1/checks/{id}/pause

POST/api/v1/checks/{id}/resume

List events

GET/api/v1/checks/{id}/events

Returns recent pings and transitions, newest first. Supports ?limit= and a ?cursor= for pagination; the response includes next_cursor when more pages exist.

{ "events": [ { "type": "ping", "at": 1753000000000, "src_ip": "..." } ], "next_cursor": "..." }

Errors

Status	Meaning
`400`	Malformed body, or an invalid cron/timezone/duration.
`401`	Missing or invalid API key.
`404`	No such check in your account.

Errors return a JSON body of the form { "error": "message" }.