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.

On this page

The 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 #

FieldTypeRequiredMeaning
machineobjectRequired
machine.disk_used_pctnumberRequired0 to 100.
machine.load_1mnumberRequired0 to 100000.
machine.uptime_sintegerRequiredAt least 0.
machine.memory_pressure_pctnumberOptionalShare of recent time some task stalled on memory. Omit where the box cannot measure it. 0 to 100.
environmentsarray of objectRequiredEvery environment the daemon is configured to run. env_id values are unique. At most 40 items.
environments[].env_idstringRequiredThe 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_alivebooleanRequiredWhether the environment's agent server process is running right now.
daemon_versionstringOptionalMust match ^[0-9A-Za-z.+-]{1,32}$.
client_tsstring (date-time)RequiredThe 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.

POST /v1/heartbeats:ingest
{
  "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 #

StatusMeaning
200The heartbeat was recorded.
400The request was malformed (malformed_json) or broke the schema (validation_failed, with one entry in errors per problem).
401The 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).
413The body is over the size limit (payload_too_large).
415The body is not application/json (unsupported_media_type).
429The token is sending too fast (rate_limited). Wait Retry-After seconds.

What the answer means #

The answer tells a client two things:

FieldTypeRequiredMeaning
received_atstring (date-time)Required
heartbeat_interval_sintegerRequiredHow 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:

  1. It marks the machine as seen, now.
  2. For each environment it names with server_alive: true, it marks that environment's agent server as seen, now.
  3. 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:

Workstation
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"}'
Output
{
  "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.