heartbeats documentation

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

quick start

register or sign in through account.dorianmarie.com.
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

account

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 keys

create and revoke keys at account. copy a new key immediately; it is shown once.

authentication

browser requests use secure account sessions. API requests send Authorization: Bearer YOUR_ACCOUNT_API_KEY. Include Origin: https://heartbeats.dorianmarie.com for mutations. Existing heartbeat API tokens remain valid.

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 YOUR_ACCOUNT_API_KEY" \
  -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, head, post, and put are accepted. request bodies up to 8 kb are saved with the event.

ping /ping/:secret

report a successful run and resolve any open incident.

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

ping /ping/:secret/fail

report an explicit failure and include diagnostic output.

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

ping /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

accounts are limited to 100 heartbeats and 25 api tokens. ping urls accept 120 requests per minute and retain the latest 100 events and 100 incidents per heartbeat.

status	meaning
400	invalid input.
401	missing, expired, or invalid authentication.
404	resource or heartbeat secret not found.
409	an account resource limit was reached.
413	the request body is too large.
429	a request rate limit was reached.
502	the configured email provider rejected the message.
503	smtp email sending is not configured.