Skip to content

Beta: these docs are still being updated. The next full update is on 19 November at 8 PM UTC. Docs in beta. Full update 19 Nov, 8 PM UTC.

Hoody.com

Six endpoints cover a session’s event surface. They differ in whether they attach to a live session, consume the exclusive attach slot, or read data without attaching:

  • stream attaches to a live session over WebSocket or SSE and receives events as they happen. Use it for a reconnecting client that retained its cursor.
  • watch attaches to up to 32 live sessions over one SSE stream. Use it when one page watches many sessions and you want to use one stream slot instead of one per session.
  • replay returns events already buffered for a live session without attaching. Use it to catch up after a reload, then resume stream with ?since=...&incarnation=....
  • state reads recoverable state and the current stream watermark without attaching. Use it when you need the session state rather than its event history.
  • transcript reads the persisted conversation without attaching. Use it for a non-live session or for history older than the replay ring.
  • images reads the bytes of one image attached to a transcript message, without attaching.

In the Hub, open AI > Chats and select the conversation to read its history and follow new replies.

All endpoints are computer-scoped. Their base URL is https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com. Access to these Kit routes is set by the computer’s proxy permission rules.

Attach to a live session’s event stream over WebSocket (primary) or SSE. Each frame carries a gateway-stamped monotonic seq and the incarnation that stamped it. It may also carry turn_id and an envelope-level gate with id, generation, and type.

Every catalogue event nests its payload under event.data. Assistant text is event.stream_chunk (the SSE event name is stream_chunk) and a tool call is event.tool_call. Over WebSocket a frame arrives verbatim:

{
"seq": 43,
"incarnation": "0123456789abcdef0123456789abcdef",
"event": {
"type": "event.stream_chunk",
"data": {
"text": "Let me check the build output."
}
}
}

Resume from the 1024-event replay ring with ?since=<seq>&incarnation=<id>. A cursor beyond the retained ring emits a lagged frame with code replay_gap, followed by events beginning at min_seq.

Read a gate’s answerable identity from the frame envelope’s gate.id. The numeric gate_id inside the event payload is a daemon diagnostic id and is not the value to send to a gate endpoint.

For SSE, the event: line drops the leading event. prefix, while the JSON on the data: line retains the full event type. WebSocket frames are delivered without this rewriting.

WS clients can post inline confirm, answer, cancel, and workflow_message frames. A slow client is dropped with a lagged frame and does not backpressure the daemon.

NameInTypeRequiredDescription
idpathstringYesThe session id.
sincequeryintegerNoResume from this gateway int64 seq. It is also accepted as the Last-Event-ID header.
incarnationquerystringNoThe incarnation the since cursor belongs to, from a frame, replay_boundary, or the session record. If it differs from the live session’s, the cursor is invalid and the full retained ring is sent.
Last-Event-IDheaderstringNoSSE resume cursor containing the gateway int64 seq. It is the header alias of since and is sent automatically by an SSE client on reconnect.
X-Hoody-CwdheaderstringNoPer-request working-directory scope: the .hoody project layer, record cwd, and tool and workflow cwd. The value must be UTF-8. Other bytes are refused with 400 bad_request.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override selecting which on-disk .hoody install a stateless read or write resolves against. The value must be UTF-8. Other bytes are refused with 400 bad_request.
X-Hoody-ComputerheaderstringNoPer-request bound remote computer. Omitting it selects the local computer. It is rejected with 400 on routes with no computer dimension.
X-Hoody-RealmheaderstringNoPer-request realm selector: global or a 24-hex realm id. On a session route it names the realm where the session is looked up. A session in another realm, or in a realm this login does not serve, returns 404 not_found. It is rejected with 400 realm_scope_unsupported on active-only and no-realm routes, and for another realm on an agent pinned to one realm.
realmquerystringNoQuery alias of the X-Hoody-Realm header, read when the header is absent or empty: global or a 24-hex realm id. On a session route it names the realm where the session is looked up. A session in another realm, or in a realm this login does not serve, returns 404 not_found. It is rejected with 400 realm_scope_unsupported on active-only and no-realm routes, and for another realm on an agent pinned to one realm.

This endpoint accepts no request body.

Terminal window
curl -X GET "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/sessions/67e89abc123def456789abc1/stream?since=42&incarnation=0123456789abcdef0123456789abcdef" \
-N

Media type: none

The response has no body; the connection switches to the WebSocket frame protocol.

Watch up to 32 live sessions on one SSE stream. This endpoint uses one stream slot instead of one slot per session, which makes it suitable for a page that monitors many sessions.

Each session retains the same per-session sequence numbers, incarnation, replay ring, cursor, replay_gap, replay_boundary, and lagged-drop behavior as GET /api/v1/agent/sessions/{id}/stream. The SSE event: name drops the event. prefix, while the JSON data retains the full event type. Catalogue event payloads are nested under event.data.

A session event has the following data:

{
"session_id": "67e89abc123def456789abc1",
"seq": 43,
"incarnation": "0123456789abcdef0123456789abcdef",
"turn_id": "67e89abc123def456789abc3",
"event": {
"type": "event.stream_chunk",
"data": {
"text": "Checking the build output."
}
}
}

Per-session control frames include replay_boundary with session_id, session_lagged with session_id and a code of replay_gap or lagged, and session_end with session_id and reason. These control frames are not catalogue events, so their fields stay flat. Only the final end frame, whose data is {"reason":"no sessions left"}, ends the shared stream.

A gap or drop in one session does not reset the other sessions. A session dropped because the client was too slow receives session_lagged with code set to lagged and leaves the stream. Reconnect that session with its own cursor.

Sessions start in the order of the ids list. A session that is not live or that the caller may not see receives session_end with reason set to session not found. A closed session receives session closed, and a session whose owner is no longer the active account receives session not authorized.

The stream is read-only. To answer a gate, use POST /api/v1/agent/sessions/{id}/confirm or POST /api/v1/agent/sessions/{id}/answer with the gate id from the frame envelope.

Access to this Kit route is set by the computer’s proxy permission rules.

NameInTypeRequiredDescription
idsquerystringYesComma list of 1 to 32 distinct session ids.
sincequerystringNoComma list of <session id>:<seq>, containing the last gateway seq applied per session. Ids not listed start from their whole retained ring.
incarnationquerystringNoComma list of <session id>:<incarnation>, containing the incarnation each since cursor belongs to. A session whose incarnation differs gets replay_gap and its full retained ring.
X-Hoody-CwdheaderstringNoPer-request working-directory scope: the .hoody project layer, record cwd, and tool and workflow cwd. The value must be UTF-8. Other bytes are refused with 400 bad_request.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override selecting which on-disk .hoody install a stateless read or write resolves against. The value must be UTF-8. Other bytes are refused with 400 bad_request.
X-Hoody-RealmheaderstringNoPer-request realm selector: global or a 24-hex realm id. On a session route it names the realm where the session is looked up. A session in another realm, or in a realm this login does not serve, returns 404 not_found. It is rejected with 400 realm_scope_unsupported on active-only and no-realm routes, and for another realm on an agent pinned to one realm.
realmquerystringNoQuery alias of the X-Hoody-Realm header, read when the header is absent or empty: global or a 24-hex realm id. On a session route it names the realm where the session is looked up. A session in another realm, or in a realm this login does not serve, returns 404 not_found. It is rejected with 400 realm_scope_unsupported on active-only and no-realm routes, and for another realm on an agent pinned to one realm.

This endpoint accepts no request body.

Terminal window
curl -X GET "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/sessions:events?ids=67e89abc123def456789abc1,67e89abc123def456789abc2&since=67e89abc123def456789abc1:42,67e89abc123def456789abc2:17&incarnation=67e89abc123def456789abc1:0123456789abcdef0123456789abcdef,67e89abc123def456789abc2:fedcba9876543210fedcba9876543210" \
-H "X-Hoody-Cwd: /home/user/project" \
-H "X-Hoody-Config-Dir: /home/user/.hoody" \
-H "X-Hoody-Realm: global" \
-N

Media type: text/event-stream

The response is an SSE event stream. Frames do not include an SSE id line because one id cannot represent every session’s cursor.

event: replay_boundary
data: {"session_id":"67e89abc123def456789abc1","max_seq":2,"incarnation":"0123456789abcdef0123456789abcdef"}
event: stream_chunk
data: {"session_id":"67e89abc123def456789abc1","seq":43,"incarnation":"0123456789abcdef0123456789abcdef","turn_id":"67e89abc123def456789abc3","event":{"type":"event.stream_chunk","data":{"text":"Checking the build output."}}}
event: stream_chunk
data: {"session_id":"67e89abc123def456789abc2","seq":18,"incarnation":"fedcba9876543210fedcba9876543210","event":{"type":"event.stream_chunk","data":{"text":"The test suite is running."}}}
event: session_lagged
data: {"session_id":"67e89abc123def456789abc2","code":"lagged"}
event: stream_chunk
data: {"session_id":"67e89abc123def456789abc1","seq":44,"incarnation":"0123456789abcdef0123456789abcdef","event":{"type":"event.stream_chunk","data":{"text":"The build error is in the config file."}}}
event: session_end
data: {"session_id":"67e89abc123def456789abc1","reason":"session closed"}
event: end
data: {"reason":"no sessions left"}

Replay a live session’s buffered event tail without attaching. The response contains the gateway’s own ring snapshot, not a daemon reply, with min_seq and max_seq plus the incarnation they belong to for resuming the stream.

Every buffered event nests its payload under event.data. Sequence 1 of a fresh ring is event.session_started, assistant text is event.stream_chunk, and max_seq equals the seq of the last event in the window.

While a gate is parked, the response includes a pending_gate whose id is the addressable identity to echo on POST /api/v1/agent/sessions/{id}/confirm or POST /api/v1/agent/sessions/{id}/answer. It also carries the generation, the type (confirm or question), and the required human_only field, which is always present. Optional tool_name, gate_cause, and risk fields are included when the agent supplied them. For a non-live session, use GET /api/v1/agent/sessions/{id}/transcript instead.

NameInTypeRequiredDescription
idpathstringYesThe session id.
X-Hoody-CwdheaderstringNoPer-request working-directory scope: the .hoody project layer, record cwd, and tool and workflow cwd. The value must be UTF-8. Other bytes are refused with 400 bad_request.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override selecting which on-disk .hoody install a stateless read or write resolves against. The value must be UTF-8. Other bytes are refused with 400 bad_request.
X-Hoody-ComputerheaderstringNoPer-request bound remote computer. Omitting it selects the local computer. It is rejected with 400 on routes with no computer dimension.
X-Hoody-RealmheaderstringNoPer-request realm selector: global or a 24-hex realm id. On a session route it names the realm where the session is looked up. A session in another realm, or in a realm this login does not serve, returns 404 not_found. It is rejected with 400 realm_scope_unsupported on active-only and no-realm routes, and for another realm on an agent pinned to one realm.
realmquerystringNoQuery alias of the X-Hoody-Realm header, read when the header is absent or empty: global or a 24-hex realm id. On a session route it names the realm where the session is looked up. A session in another realm, or in a realm this login does not serve, returns 404 not_found. It is rejected with 400 realm_scope_unsupported on active-only and no-realm routes, and for another realm on an agent pinned to one realm.

This endpoint accepts no request body.

Terminal window
curl -X GET "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/sessions/67e89abc123def456789abc1/replay"

Media type: application/json

{
"session_id": "67e89abc123def456789abc1",
"incarnation": "0123456789abcdef0123456789abcdef",
"min_seq": 1,
"max_seq": 2,
"events": [
{
"seq": 1,
"incarnation": "0123456789abcdef0123456789abcdef",
"event": {
"type": "event.session_started",
"data": {
"session_id": "67e89abc123def456789abc1",
"started_at": "2024-01-15T10:30:00Z"
}
}
},
{
"seq": 2,
"incarnation": "0123456789abcdef0123456789abcdef",
"event": {
"type": "event.stream_chunk",
"data": {
"text": "I'll look at the build output."
}
}
}
],
"pending_gate": {
"id": "01HMW7D3Q4K5J6V7Y8Z9X0C1BV",
"generation": 1,
"type": "confirm",
"tool_name": "bash",
"gate_cause": "approval_policy",
"risk": "destructive",
"human_only": true
}
}

Read a session’s recoverable state without attaching. The response contains one consistent snapshot: the daemon’s state object paired with this gateway’s stream watermark, incarnation and seq.

The watermark is read before the daemon snapshot, so an event that lands during the read is replayed and is not lost. The endpoint works for a live or dormant session. A dormant session carries no incarnation or seq. The response uses Cache-Control: no-store.

The approval object is the effective approval policy and waiver posture. It is the same object that GET /api/v1/agent/sessions/{id}/approval returns.

While a gate is parked, pending_gate_ref names the addressable identity of that gate. It is published only when it names the same gate as pending_gate. When the gate changed during the read, the ref is omitted and pending_gate stands alone, so read the state again before answering.

While a turn is running, turn_since identifies the stream cursor immediately before that turn’s first frame. If it is below min_seq, the turn’s first frame was evicted from the replay ring.

NameInTypeRequiredDescription
idpathstringYesThe session id.
X-Hoody-CwdheaderstringNoPer-request working-directory scope: the .hoody project layer, record cwd, and tool and workflow cwd. The value must be UTF-8. Other bytes are refused with 400 bad_request.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override selecting which on-disk .hoody install a stateless read or write resolves against. The value must be UTF-8. Other bytes are refused with 400 bad_request.
X-Hoody-ComputerheaderstringNoPer-request bound remote computer. Omitting it selects the local computer. It is rejected with 400 on routes with no computer dimension.
X-Hoody-RealmheaderstringNoPer-request realm selector: global or a 24-hex realm id. On a session route it names the realm where the session is looked up. A session in another realm, or in a realm this login does not serve, returns 404 not_found. It is rejected with 400 realm_scope_unsupported on active-only and no-realm routes, and for another realm on an agent pinned to one realm.
realmquerystringNoQuery alias of the X-Hoody-Realm header, read when the header is absent or empty: global or a 24-hex realm id. On a session route it names the realm where the session is looked up. A session in another realm, or in a realm this login does not serve, returns 404 not_found. It is rejected with 400 realm_scope_unsupported on active-only and no-realm routes, and for another realm on an agent pinned to one realm.

This endpoint accepts no request body.

Terminal window
curl -X GET "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/sessions/67e89abc123def456789abc1/state"

Media type: application/json

{
"session_id": "67e89abc123def456789abc1",
"live": true,
"epoch": "epoch-20240115103000123456",
"state": "parked",
"current_turn_id": "67e89abc123def456789abc2",
"queued_turn_ids": [],
"approval": {
"mode": "always",
"locked": false,
"revision": 1,
"yolo": false,
"yolo_origin": "",
"auto_write": false,
"auto_dir_access": false,
"backend_auto_approving": false,
"rules": [],
"capabilities": {
"always": true,
"locked": true,
"lease": true
},
"lease": {
"held": true,
"holder": "http:approver-console-1",
"generation": 1,
"expires_at": "2024-01-15T10:45:00Z",
"epoch": "epoch-20240115103000123456"
},
"epoch": "epoch-20240115103000123456"
},
"pending_gate": {
"type": "confirm",
"gate_id": 3,
"generation": 1,
"tool_name": "bash",
"gate_cause": "approval_policy",
"human_only": true,
"lease_required": true,
"params": {
"command": "rm -rf build"
}
},
"last_detach": null,
"incarnation": "0123456789abcdef0123456789abcdef",
"seq": 42,
"pending_gate_ref": {
"id": "01HMW7D3Q4K5J6V7Y8Z9X0C1BV",
"generation": 1,
"type": "confirm",
"tool_name": "bash",
"gate_cause": "approval_policy",
"human_only": true
}
}

GET /api/v1/agent/sessions/{id}/transcript

Section titled “GET /api/v1/agent/sessions/{id}/transcript”

Read a session’s persisted conversation without attaching. The response contains the message projection from the session record: text, thinking, tool_use, and tool_result blocks, an image block for every image a person attached, plus turn boundaries. On an outcome_claims session, it also includes an outcome_claims block following each report_outcome tool result.

An image block marks an image a person attached to the message. It carries image_id (the id that GET /api/v1/agent/sessions/{id}/images/{image_id} takes, valid for this session only), media_type (image/png, image/jpeg, image/webp or image/gif) and bytes (the image’s size). Those three fields are omitted when the stored image cannot be read there: a type other than the four, bytes that do not start as such an image, or an image over 16 MiB. Only the start of the image is checked, so an image whose later bytes are damaged keeps its id and is returned as stored.

The endpoint never attaches, never resumes, and never consumes the exclusive attach slot. For a live session, the content is fresh to the last persist point. The mid-turn streaming tail is served by GET /api/v1/agent/sessions/{id}/replay and GET /api/v1/agent/sessions/{id}/stream instead.

X-Hoody-Config-Dir selects the record store. X-Hoody-Cwd is not a match filter on this endpoint.

NameInTypeRequiredDescription
idpathstringYesThe session id.
after_turnqueryintegerNoExclusive completed-turn skip cursor. Returns content strictly after completed turn N. 0 returns the full transcript, values past the end clamp, and a negative or non-integer value returns 400.
X-Hoody-CwdheaderstringNoPer-request working-directory scope: the .hoody project layer, record cwd, and tool and workflow cwd. The value must be UTF-8. Other bytes are refused with 400 bad_request.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override selecting which on-disk .hoody install a stateless read or write resolves against. The value must be UTF-8. Other bytes are refused with 400 bad_request.
X-Hoody-RealmheaderstringNoPer-request realm selector: global or a 24-hex realm id. On a session route it names the realm where the session is looked up. A session in another realm, or in a realm this login does not serve, returns 404 not_found. It is rejected with 400 realm_scope_unsupported on active-only and no-realm routes, and for another realm on an agent pinned to one realm.
realmquerystringNoQuery alias of the X-Hoody-Realm header, read when the header is absent or empty: global or a 24-hex realm id. On a session route it names the realm where the session is looked up. A session in another realm, or in a realm this login does not serve, returns 404 not_found. It is rejected with 400 realm_scope_unsupported on active-only and no-realm routes, and for another realm on an agent pinned to one realm.

This endpoint accepts no request body.

Terminal window
curl -X GET "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/sessions/67e89abc123def456789abc1/transcript?after_turn=0"

Media type: application/json

{
"session_id": "67e89abc123def456789abc1",
"live": false,
"realm": "global",
"name": "Fix the build",
"model": "claude-opus-4",
"cwd": "/home/user/project",
"turns_total": 1,
"turns_returned": 1,
"after_turn": 0,
"turn_boundaries": [1],
"messages": [
{
"role": "user",
"blocks": [
{
"kind": "text",
"text": "Please fix the build."
},
{
"kind": "image",
"image_id": "0d85f5af1e0dfa09503f0bdb179ab8f37c4225b43d442a3a91e59c3c849bc99e",
"media_type": "image/png",
"bytes": 20481
}
]
},
{
"role": "assistant",
"blocks": [
{
"kind": "thinking",
"text": "Let me check the build output first."
},
{
"kind": "tool_use",
"tool_id": "toolu_01abc",
"tool_name": "bash",
"input": {
"command": "npm run build"
}
},
{
"kind": "tool_result",
"tool_id": "toolu_01abc",
"output": "Error: ENOENT: no such file or directory",
"is_error": true
},
{
"kind": "text",
"text": "The issue is a missing config file."
}
]
}
],
"started_at": "2024-01-15T10:00:00Z",
"last_request_at": "2024-01-15T10:05:00Z"
}

GET /api/v1/agent/sessions/{id}/images/{image_id}

Section titled “GET /api/v1/agent/sessions/{id}/images/{image_id}”

Read the bytes of one image a person attached to a message of the session. The image_id comes from an image block of the transcript (or of event.replay); the transcript carries only the block’s media_type and bytes, never the bytes themselves. An image_id is 64 lowercase hexadecimal characters, and an image block without one cannot be read here.

Like the transcript, this endpoint reads the session record for a live or closed session and never attaches. The body is the image bytes with their own Content-Type (image/png, image/jpeg, image/webp or image/gif), sent with X-Content-Type-Options: nosniff, Content-Disposition: inline and Cache-Control: private, no-store.

The image lasts as long as its message stays in the transcript. Once the message leaves the transcript (a trim, a clear or a compaction) or the session is deleted, the id is unknown. One plain 404 answers a session that is not visible to this caller, an id this session does not hold, and a malformed id alike.

The agent answers these reads one at a time, each from the whole session record: ask for a few images at a time, not for every image of a long conversation in parallel.

NameInTypeRequiredDescription
idpathstringYesThe session id.
image_idpathstringYesThe image id.
X-Hoody-CwdheaderstringNoPer-request working-directory scope: the .hoody project layer, record cwd, and tool and workflow cwd. The value must be UTF-8. Other bytes are refused with 400 bad_request.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override selecting which on-disk .hoody install a stateless read or write resolves against. The value must be UTF-8. Other bytes are refused with 400 bad_request.
X-Hoody-RealmheaderstringNoPer-request realm selector: global or a 24-hex realm id. On a session route it names the realm where the session is looked up. A session in another realm, or in a realm this login does not serve, returns 404 not_found. It is rejected with 400 realm_scope_unsupported on active-only and no-realm routes, and for another realm on an agent pinned to one realm.
realmquerystringNoQuery alias of the X-Hoody-Realm header, read when the header is absent or empty: global or a 24-hex realm id. On a session route it names the realm where the session is looked up. A session in another realm, or in a realm this login does not serve, returns 404 not_found. It is rejected with 400 realm_scope_unsupported on active-only and no-realm routes, and for another realm on an agent pinned to one realm.

This endpoint accepts no request body.

Terminal window
curl -X GET "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/sessions/67e89abc123def456789abc1/images/0d85f5af1e0dfa09503f0bdb179ab8f37c4225b43d442a3a91e59c3c849bc99e" \
--output image.png

Media type: image/png, image/jpeg, image/webp, image/gif

The body is the raw image bytes, not a JSON document. The Content-Type header names which of the four types they are. The response also carries X-Content-Type-Options: nosniff, Content-Disposition: inline and Cache-Control: private, no-store.