Report a heartbeat
The request a box makes once a minute to say it is alive, how it is, and which of its agent servers are running.
API referenceThe request #
POST /v1/heartbeats:ingest
Sent by nucleated once per heartbeat interval. Carries machine health
and every environment the daemon is configured to run, each with
whether its agent server is alive right now.
An environment exists in Watch from the first heartbeat that names it. An environment the machine has reported before and leaves out of a heartbeat is treated as not alive.
Environments beyond the account's limit are accepted and stored, but hidden from the console and never alerted on.
The body is limited to 16 KB and 40 environments.
A machine token (nuc_…), minted in the console and kept on the box
in a file only the agent user can read. Write-only: accepted on
POST /v1/heartbeats:ingest and POST /v1/events:ingest and nowhere
else.
Request body #
| Field | Type | Required | Meaning |
|---|---|---|---|
machine | object | Required | |
machine.disk_used_pct | number | Required | 0 to 100. |
machine.load_1m | number | Required | 0 to 100000. |
machine.uptime_s | integer | Required | At least 0. |
machine.memory_pressure_pct | number | Optional | Share of recent time some task stalled on memory. Omit where the box cannot measure it. 0 to 100. |
environments | array of object | Required | Every environment the daemon is configured to run. env_id values are unique. At most 40 items. |
environments[].env_id | string | Required | The environment's name on the box, unique within its machine. Lower case letters, digits, ., _ and -. Must match ^[a-z0-9][a-z0-9._-]{0,63}$. |
environments[].server_alive | boolean | Required | Whether the environment's agent server process is running right now. |
daemon_version | string | Optional | Must match ^[0-9A-Za-z.+-]{1,32}$. |
client_ts | string (date-time) | Required | The box's clock. A diagnostic; never used for a deadline. |
Any field that is not in this table is rejected, and the request with it.
{
"machine": {
"disk_used_pct": 41.5,
"load_1m": 0.62,
"uptime_s": 864000,
"memory_pressure_pct": 3.1
},
"environments": [
{
"env_id": "client-a",
"server_alive": true
},
{
"env_id": "personal",
"server_alive": true
}
],
"daemon_version": "0.1.0",
"client_ts": "2026-11-19T12:00:00.000Z"
}
Responses #
| Status | Meaning |
|---|---|
200 | The heartbeat was recorded. |
400 | The request was malformed (malformed_json) or broke the schema (validation_failed, with one entry in errors per problem). |
401 | The credential is missing, wrong, expired or revoked, or the person is not one Watch knows: they have not signed in, or their account was deleted (unauthorized). |
413 | The body is over the size limit (payload_too_large). |
415 | The body is not application/json (unsupported_media_type). |
429 | The token is sending too fast (rate_limited). Wait Retry-After seconds. |
What the answer means #
The answer tells a client two things:
| Field | Type | Required | Meaning |
|---|---|---|---|
received_at | string (date-time) | Required | |
heartbeat_interval_s | integer | Required | How often the account expects a heartbeat. The daemon follows this. |
Any field that is not in this table is rejected, and the request with it.
heartbeat_interval_s is how often the account expects to hear from this machine. A client waits that long before its next heartbeat. It changes when the account changes plan or its deadlines, which is how a box learns of either without being told twice.
received_at is the time Watch recorded, and the one every deadline is measured from.
What Watch does with it #
A heartbeat does three things at once:
- It marks the machine as seen, now.
- For each environment it names with
server_alive: true, it marks that environment's agent server as seen, now. - For an environment it has not seen before, it creates it.
An environment the machine has reported before and leaves out of a heartbeat is treated as not alive. To retire one for good, delete it in the console.
Environments beyond the account's limit are accepted and stored, hidden from the console, and never alerted on. What happens over a limit explains why they are not refused.
Try it #
With a token minted in the console for a test machine:
curl -sS https://api.nucarium.com/v1/heartbeats:ingest \
-H "Authorization: Bearer $(cat token)" \
-H "Content-Type: application/json" \
-d '{"machine":{"disk_used_pct":41.5,"load_1m":0.62,"uptime_s":864000},"environments":[{"env_id":"client-a","server_alive":true}],"client_ts":"2026-11-19T12:00:00.000Z"}'
{
"received_at": "2026-11-19T12:00:00.412Z",
"heartbeat_interval_s": 60
}
Stop sending, and the machine goes stale and then down on the usual deadlines.