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.

On this page

The envelope #

Every event is one envelope:

One lifecycle event. Metadata only; there is no field for content.

FieldTypeRequiredMeaning
event_idstringRequiredGenerated on the box, unique per event. Watch deduplicates on it. Must match ^[A-Za-z0-9_-]{8,64}$.
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}$.
session_idstringRequiredMust match ^[A-Za-z0-9._:-]{1,128}$.
bridge_session_idstringOptionalThe agent vendor's own id for the session, when the box knows it. Must match ^[A-Za-z0-9._:-]{1,128}$.
typestring, one of the values listedRequiredWhat 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.
reposarray of stringOptionalThe repos in the session, as owner/name or name. At most 32 items.
branchstringOptionalA git branch name. No spaces or control characters. Must match ^[A-Za-z0-9._/@+=#-]{1,255}$.
error_kindstringOptionalWith stop_failure, a short machine-readable kind such as rate_limit. Never a message. Must match ^[a-z0-9_.-]{1,64}$.
client_tsstring (date-time)RequiredThe 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 #

FieldTypeRequiredMeaning
eventsarray of objectRequired1 to 100 items.
events[].event_idstringRequiredGenerated on the box, unique per event. Watch deduplicates on it. Must match ^[A-Za-z0-9_-]{8,64}$.
events[].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}$.
events[].session_idstringRequiredMust match ^[A-Za-z0-9._:-]{1,128}$.
events[].bridge_session_idstringOptionalThe agent vendor's own id for the session, when the box knows it. Must match ^[A-Za-z0-9._:-]{1,128}$.
events[].typestring, one of the values listedRequiredWhat 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[].reposarray of stringOptionalThe repos in the session, as owner/name or name. At most 32 items.
events[].branchstringOptionalA git branch name. No spaces or control characters. Must match ^[A-Za-z0-9._/@+=#-]{1,255}$.
events[].error_kindstringOptionalWith stop_failure, a short machine-readable kind such as rate_limit. Never a message. Must match ^[a-z0-9_.-]{1,64}$.
events[].client_tsstring (date-time)RequiredThe 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.

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

StatusMeaning
200The batch was processed.
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 #

FieldTypeRequiredMeaning
received_atstring (date-time)Required
acceptedintegerRequiredEvents recorded for the first time.
duplicatesintegerRequiredEvents Watch had already recorded. Safe to forget.
rejectedarray of objectRequiredEvents Watch will never accept. Do not retry them.
rejected[].event_idstringRequired
rejected[].reasonstring, one of the values listedRequiredOne 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:

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