Heartbeats documentation

Monitor cron jobs, backups, scheduled Workers, and background processes with a simple dead man's switch.

Quick start

Register with your email and enter the six-digit verification code.
Create a heartbeat and choose how often it should run plus an optional grace period.
Copy the secret ping URL into your job.
Call the URL after a successful run. Use /fail or an exit code to report failures.

curl https://heartbeats.dorianmarie.com/ping/YOUR_SECRET

Keep ping URLs private. Anyone with a monitor's secret URL can report its state.

Web interface

Registration and verification

Enter an email address on the dashboard. Heartbeats emails a single-use six-digit code that expires after ten minutes. Entering the code verifies the address and creates the account. Future sign-ins use the same flow.

Creating a heartbeat

Choose a name, optional description, expected interval, and grace period. Intervals support minutes, hours, days, weeks, and 30-day months. A new monitor stays pending until its first ping.

Monitor states

State	Meaning
Pending	Waiting for the first ping.
Healthy	The last ping arrived before its deadline.
Late	The expected ping plus grace period has elapsed.
Failed	The job explicitly reported a failure.
Paused	Deadline checks and alerts are temporarily disabled.

API tokens

Open API tokens in the dashboard, name the token, and copy it immediately. Tokens are stored as hashes and cannot be displayed again. Revoke a token from the same screen at any time.

Authentication

Dashboard requests use an HTTP-only session cookie. API requests use a Bearer token:

Authorization: Bearer hb_api_YOUR_TOKEN

POST /api/auth/start

Send an email verification code.

{"email":"you@example.com"}

POST /api/auth/verify

Verify the code and create a browser session.

{"email":"you@example.com","code":"123456"}

Monitor API

All interval and grace values in the JSON API are integer seconds. Authenticated monitor operations are isolated to the token's owner.

GET /api/overview

List the current user's monitors and 50 most recent incidents.

POST /api/monitors

Create a monitor. The interval must be at least ten seconds.

curl -X POST https://heartbeats.dorianmarie.com/api/monitors \
  -H "Authorization: Bearer hb_api_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Nightly backup","description":"Database export","interval_seconds":86400,"grace_seconds":1800}'

PATCH /api/monitors/:id

Update any combination of name, description, interval_seconds, grace_seconds, or paused.

DELETE /api/monitors/:id

Permanently delete a monitor and its incident and event history.

POST /api/monitors/:id/rotate-token

Replace the secret ping URL immediately.

GET /api/monitors/:id/events

Return the monitor's 100 most recent pings and failures.

Ping API

Ping endpoints use the secret monitor URL and do not need a Bearer token. GET, POST, and other HTTP methods are accepted. Request bodies up to 8 KB are saved with the event.

ANY /ping/:secret

Report a successful run and resolve any open incident.

curl https://heartbeats.dorianmarie.com/ping/YOUR_SECRET

ANY /ping/:secret/fail

Report an explicit failure and include diagnostic output.

curl -d "backup upload failed" \
  https://heartbeats.dorianmarie.com/ping/YOUR_SECRET/fail

ANY /ping/:secret/:exit_code

Exit code 0 is healthy; any other numeric code is a failure.

output=$(./backup.sh 2>&1)
curl -d "$output" https://heartbeats.dorianmarie.com/ping/YOUR_SECRET/$?

Errors and limits

Status	Meaning
400	Invalid input.
401	Missing, expired, or invalid authentication.
404	Resource or heartbeat secret not found.
429	A verification code was requested too recently.
502	The configured email provider rejected the message.
503	SMTP email sending is not configured.