Report session events
The request a box makes when something happens to a session, and the envelope each event travels in. Metadata only, there is no field for content.
API referenceOn this page
The envelope #
Every event is one envelope:
One lifecycle event. Metadata only; there is no field for content.
| Field | Type | Required | Meaning |
|---|---|---|---|
event_id | string | Required | Generated on the box, unique per event. Watch deduplicates on it. Must match ^[A-Za-z0-9_-]{8,64}$. |
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}$. |
session_id | string | Required | Must match ^[A-Za-z0-9._:-]{1,128}$. |
bridge_session_id | string | Optional | The agent vendor's own id for the session, when the box knows it. Must match ^[A-Za-z0-9._:-]{1,128}$. |
type | string, one of the values listed | Required | What happened to the session, and the status it moves to: One of: session_start, user_prompt_submit, activity, permission_prompt, input_prompt, elicitation_prompt, stop, stop_failure, session_end. |
repos | array of string | Optional | The repos in the session, as owner/name or name. At most 32 items. |
branch | string | Optional | A git branch name. No spaces or control characters. Must match ^[A-Za-z0-9._/@+=#-]{1,255}$. |
error_kind | string | Optional | With stop_failure, a short machine-readable kind such as rate_limit. Never a message. Must match ^[a-z0-9_.-]{1,64}$. |
client_ts | string (date-time) | Required | The box's clock when the event happened. Orders events within a session; never used for a deadline. |
Any field that is not in this table is rejected, and the request with it.
event_id is made on the box, once, when the event happens. nucleated uses a UUIDv7. Watch remembers the ids it has seen, so an event sent twice is recorded once.
Event types #
The type says what happened, and decides the session's status:
type |
The session becomes |
|---|---|
session_start |
Idle. A new session, even if one with this id ended before. |
user_prompt_submit |
Working |
activity |
Working. The agent moved on by itself, for example after a permission was granted. |
permission_prompt |
Needs input |
input_prompt |
Needs input |
elicitation_prompt |
Needs input |
stop |
Idle |
stop_failure |
Failed. Send error_kind with it. |
session_end |
Ended |
Nothing but session_start brings an ended session back.
These names are the API's own. They are not Claude Code's hook names (SessionStart, Notification and so on), and they are the same whichever agent runs on the box. nucleated maps one to the other: what each event becomes has the table for Claude Code.
The request #
POST /v1/events:ingest
A batch of up to 100 event envelopes. Each envelope is metadata only: which session, in which environment, did what kind of thing, and when.
Delivery is at-least-once. Watch deduplicates on event_id, so a batch
can be retried whole. Events may arrive out of order; an event older
than the newest one already applied to its session is kept in the
debug ring and changes nothing.
An event for an environment no heartbeat from this machine has named
is rejected, and reported in rejected. The rest of the batch is
still applied.
The body is limited to 256 KB.
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 |
|---|---|---|---|
events | array of object | Required | 1 to 100 items. |
events[].event_id | string | Required | Generated on the box, unique per event. Watch deduplicates on it. Must match ^[A-Za-z0-9_-]{8,64}$. |
events[].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}$. |
events[].session_id | string | Required | Must match ^[A-Za-z0-9._:-]{1,128}$. |
events[].bridge_session_id | string | Optional | The agent vendor's own id for the session, when the box knows it. Must match ^[A-Za-z0-9._:-]{1,128}$. |
events[].type | string, one of the values listed | Required | What happened to the session, and the status it moves to: One of: session_start, user_prompt_submit, activity, permission_prompt, input_prompt, elicitation_prompt, stop, stop_failure, session_end. |
events[].repos | array of string | Optional | The repos in the session, as owner/name or name. At most 32 items. |
events[].branch | string | Optional | A git branch name. No spaces or control characters. Must match ^[A-Za-z0-9._/@+=#-]{1,255}$. |
events[].error_kind | string | Optional | With stop_failure, a short machine-readable kind such as rate_limit. Never a message. Must match ^[a-z0-9_.-]{1,64}$. |
events[].client_ts | string (date-time) | Required | The box's clock when the event happened. Orders events within a session; never used for a deadline. |
Any field that is not in this table is rejected, and the request with it.
{
"events": [
{
"event_id": "01JD3K9Q2M7V4X8Z5B6N0P1R2S",
"env_id": "client-a",
"session_id": "7f3c2a1e-58b4-4d0c-9a6e-2b1f0c9d8e7a",
"type": "permission_prompt",
"repos": [
"your-org/web",
"your-org/api"
],
"branch": "agent/checkout-fix",
"client_ts": "2026-11-19T12:00:03.120Z"
}
]
}
Responses #
| Status | Meaning |
|---|---|
200 | The batch was processed. |
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 #
| Field | Type | Required | Meaning |
|---|---|---|---|
received_at | string (date-time) | Required | |
accepted | integer | Required | Events recorded for the first time. |
duplicates | integer | Required | Events Watch had already recorded. Safe to forget. |
rejected | array of object | Required | Events Watch will never accept. Do not retry them. |
rejected[].event_id | string | Required | |
rejected[].reason | string, one of the values listed | Required | One of: unknown_environment. |
Any field that is not in this table is rejected, and the request with it.
A client deletes what was accepted and what were duplicates: Watch has both. It also gives up on anything in rejected, which will never be accepted however often it is sent. The one reason today is unknown_environment: the event names an environment no heartbeat from this machine has named.
The rest of a batch is still applied when part of it is rejected.
Order and lateness #
Events may arrive out of order, and after an outage they arrive late. Watch handles both:
- Within one session, events are ordered by
client_ts. An event older than the newest one already applied to its session is kept for the record and changes nothing. - An event for a session that has ended is ignored, unless it is a
session_start. - How long a session has been waiting is counted from when Watch received the event that said so, never from
client_ts.
Try it #
After a heartbeat has named client-a:
curl -sS https://api.nucarium.com/v1/events:ingest \
-H "Authorization: Bearer $(cat token)" \
-H "Content-Type: application/json" \
-d '{"events":[{"event_id":"019ab3f2-6d1c-7e4a-9b0f-3c2d1e0f4a5b","env_id":"client-a","session_id":"test-1","type":"permission_prompt","repos":["your-org/web"],"branch":"workspace/fix-login","client_ts":"2026-11-19T12:00:03.120Z"}]}'
{
"received_at": "2026-11-19T12:00:03.512Z",
"accepted": 1,
"duplicates": 0,
"rejected": []
}
The session test-1 is now at the top of the inbox, waiting. Send the same request again and the answer says "accepted": 0, "duplicates": 1. Add a field that is not in the envelope, "prompt": "hello" say, and the whole request is refused.