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.
API referenceOn 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:
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:
{
"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.