💓 Heartbeat API

Send a Heartbeat Ping

Report that your job/service is running successfully.

Endpoint

GET /heartbeat/{token}
POST /heartbeat/{token}

Parameters

Parameter	Location	Description
token	URL path	The unique heartbeat token (from your monitor's settings)

Example

# GET request
curl https://your-monitron.com/heartbeat/abc123def456

# POST request
curl -X POST https://your-monitron.com/heartbeat/abc123def456

Response

{
    "status": "ok",
    "message": "Heartbeat recorded"
}

What Happens

1. The monitor's last_checked_at is updated to now
2. Status is set to Up
3. Consecutive failures are reset to 0
4. If there was an active incident, it's automatically resolved

---

Report a Heartbeat Failure

Explicitly report that your job/service has failed.

Endpoint

POST /heartbeat/{token}/fail

Parameters

Parameter	Location	Description
token	URL path	The unique heartbeat token

Example

curl -X POST https://your-monitron.com/heartbeat/abc123def456/fail

Response

{
    "status": "ok",
    "message": "Failure recorded"
}

What Happens

1. Status is set to Down
2. Consecutive failures are incremented
3. An incident is created (if one isn't already open)
4. Notifications are dispatched to configured contacts

---

🔗 Finding Your Token

1. Go to Monitors → click your Heartbeat monitor → View
2. The Heartbeat URL is shown prominently in the monitor details
3. The token is the last part of the URL: /heartbeat/{this-part}