The box-side API

Everything a box says to Watch, written down so you can check it or build a client of your own. Two requests report, and three sign the box in and out.

On this page

Who this is for #

You do not need this page to use Nucarium. nucleated is the client, and it is already written.

It is here for two kinds of reader: someone who wants to see exactly what a box says to Watch, and someone writing their own reporter for an agent or a system nucleated does not cover.

The pages in this section are drawn from the API's own OpenAPI document when the site is built. If they and the service ever disagree, that is a bug in the service.

Signing in #

nucleate login gets a box its token with three requests of their own, described in Sign a box in. They carry no credential, because the box does not have one yet.

The two reporting requests #

Request When Carries
POST /v1/heartbeats:ingest Once per heartbeat interval The machine's health, and which agent servers are alive
POST /v1/events:ingest When something happens to a session A batch of event envelopes

Both are JSON over HTTPS, to https://api.nucarium.com.

Authentication #

Every request carries a machine token:

The header
Authorization: Bearer nuc_...

A token belongs to one machine. It is accepted on these two paths and nowhere else, and it can read nothing. You get one by signing a box in, which is this exchange, or by minting one in the console for a machine.

The machine is not named in the body of either request. The token says which machine is speaking.

Environments are not registered #

There is no request that creates an environment. One exists from the first heartbeat that names it, under the machine whose token sent the heartbeat.

An event for an environment that no heartbeat from that machine has named is refused. So a client sends a heartbeat first.

Time #

Timestamps are RFC 3339 in UTC, with milliseconds: 2026-11-19T12:00:00.000Z.

Every last-seen time and every deadline uses the moment Watch received a request. The client_ts a client sends is kept as a diagnostic and to order the events of one session. It never decides whether something is late. Deadlines says why.

Unknown fields are refused #

A request body is an allowlist. If it has a field the contract does not name, the whole request is rejected with validation_failed and nothing from it is stored. There is no field for content, and no way to add one.

Errors #

Errors are RFC 7807 problem documents, with the content type application/problem+json. Each has a stable code to act on:

A rejected request
{
  "type": "https://nucarium.dev/problems/validation-failed",
  "title": "The request is not valid",
  "status": 400,
  "code": "validation_failed",
  "detail": "1 field is not allowed or not valid.",
  "errors": [{ "path": "events.0.prompt", "message": "Unknown field." }]
}
Status code What a client should do
400 malformed_json, validation_failed Do not retry. The request is wrong and will stay wrong.
401 unauthorized Stop sending and keep what is unsent. The token is missing, wrong or revoked.
413 payload_too_large Send less in one request.
415 unsupported_media_type Send Content-Type: application/json.
429 rate_limited Wait the number of seconds in Retry-After, then retry.
5xx internal_error Retry with a growing delay.

Limits #

Heartbeat Events
Body 16 KB 256 KB
Items 40 environments 100 events

Delivery #

Delivery is at-least-once. A client that does not get an answer sends again, and Watch drops what it has already recorded: events by event_id, heartbeats because a second one is simply the next one. A batch can always be retried whole.

The rest of the API #

Watch's console reads through the same service, with a signed-in user instead of a machine token. Those paths are not documented here. A token for reading is part of the Orchard plan.