Ping API reference
Every URL a heartbeat monitor understands: success, start, fail, exit codes, logs.
Every heartbeat monitor has one URL. Append a suffix to say what happened. Any of GET, POST, PUT or HEAD works; the body of a POST or PUT (up to 64 KB, the tail is kept) becomes the run's log.
| URL | Meaning |
|---|---|
https://vivere.dev/p/<monitor-id> | Success. Sets the monitor Up and starts the next period. |
https://vivere.dev/p/<monitor-id>/start | The job started. Opens a run so the next success or failure records a duration. |
https://vivere.dev/p/<monitor-id>/fail | The job failed. The monitor goes Down immediately and alerts. |
https://vivere.dev/p/<monitor-id>/<exit-code> | Report an exit code 0–255. /0 is success, anything else is a failure with the code recorded. |
https://vivere.dev/p/<monitor-id>/log | Attach text to the current run without changing status. Useful for progress output. |
Responses
200 OK with the body OK. 404 means the monitor id is unknown or the monitor is an HTTP check. 429 means more than 120 pings a minute for one monitor; slow down.
Timing rules
- With a period, the next ping is expected at last success + period, and the deadline is that plus grace.
- With a cron expression, the next ping is expected at the next scheduled time after the last success (in the monitor's timezone), plus grace.
- Between the expected time and the deadline the monitor shows Late but does not alert.
- Past the deadline it is Down and alerts once. The next success sets it Up and sends a recovery alert.
- Pinging a paused monitor resumes it.
Safe curl
curl -fsS -m 10 --retry 3 -o /dev/null https://vivere.dev/p/<monitor-id>-f fails on HTTP errors, -sS is quiet except for errors, -m 10 caps the time, --retry 3 survives a blip.