Agent: Session streaming
Section titled “Agent: Session streaming”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:
streamattaches to a live session over WebSocket or SSE and receives events as they happen. Use it for a reconnecting client that retained its cursor.watchattaches 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.replayreturns events already buffered for a live session without attaching. Use it to catch up after a reload, then resumestreamwith?since=...&incarnation=....statereads recoverable state and the current stream watermark without attaching. Use it when you need the session state rather than its event history.transcriptreads the persisted conversation without attaching. Use it for a non-live session or for history older than the replay ring.imagesreads 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.
Live event stream
Section titled “Live event stream”GET /api/v1/agent/sessions/{id}/stream
Section titled “GET /api/v1/agent/sessions/{id}/stream”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.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | The session id. |
since | query | integer | No | Resume from this gateway int64 seq. It is also accepted as the Last-Event-ID header. |
incarnation | query | string | No | The 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-ID | header | string | No | SSE 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-Cwd | header | string | No | Per-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-Dir | header | string | No | Per-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-Computer | header | string | No | Per-request bound remote computer. Omitting it selects the local computer. It is rejected with 400 on routes with no computer dimension. |
X-Hoody-Realm | header | string | No | Per-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. |
realm | query | string | No | Query 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.
curl -X GET "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/sessions/67e89abc123def456789abc1/stream?since=42&incarnation=0123456789abcdef0123456789abcdef" \ -Nimport { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' });
const stream = client.agent.sessions.connect('67e89abc123def456789abc1', { since: 42, incarnation: '0123456789abcdef0123456789abcdef' });
stream.onEnvelope((frame) => console.log(frame.seq, frame.event));
await stream.connect();Response
Section titled “Response”Media type: none
The response has no body; the connection switches to the WebSocket frame protocol.
Media type: text/event-stream
Event stream using SSE transport. Catalogue event names on the event: line omit the leading event. prefix, while the data: payload retains the full type and nests the event payload under event.data. Every single-session frame carries an event: line, an id: line with its seq, and a data: line.
event: stream_chunkid: 43data: {"seq":43,"incarnation":"0123456789abcdef0123456789abcdef","event":{"type":"event.stream_chunk","data":{"text":"Let me check the build output."}}}
event: agent_doneid: 44data: {"seq":44,"incarnation":"0123456789abcdef0123456789abcdef","turn_id":"67e89abc123def456789abc2","event":{"type":"event.agent_done","data":{"turn_id":"67e89abc123def456789abc2","outcome":"completed"}}}Media type: application/json
The request is malformed, or a per-request computer header contradicts the session’s frozen binding.
{ "code": "bad_request", "message": "invalid request"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
realm_scope_unsupported | Realm scope unsupported | A per-request scope header this route does not take: a realm or computer header on a route without that dimension, or, on an agent pinned to one realm, a different realm. | Omit the header, or name the realm the agent is pinned to. |
bad_request | Bad request | The request was malformed or carried invalid parameters. | Correct the request body or query parameters. |
invalid_realm | Invalid realm selector | The realm selector is malformed, not "", global, or a 24-hex id. | Pass a valid realm selector. |
Media type: application/json
{ "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
forbidden | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL, for example with hoody agent …. |
Media type: application/json
{ "code": "not_found", "message": "resource not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
not_found | Not found | The requested resource does not exist. | Verify the path and identifier. |
Media type: application/json
{ "code": "rate_limited", "message": "request rate limit exceeded"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
rate_limited | Too many requests | The per-client request rate limit was exceeded. The gateway throttled the request before dispatch. | Honor the Retry-After header and retry. Reduce the request rate. |
Media type: application/json
{ "code": "service_unavailable", "message": "service unavailable"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
service_unavailable | Service unavailable | The daemon could not service the request because it was too busy or a per-client stream concurrency cap was reached. | Honor Retry-After and retry. |
GET /api/v1/agent/sessions:events
Section titled “GET /api/v1/agent/sessions:events”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.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
ids | query | string | Yes | Comma list of 1 to 32 distinct session ids. |
since | query | string | No | Comma list of <session id>:<seq>, containing the last gateway seq applied per session. Ids not listed start from their whole retained ring. |
incarnation | query | string | No | Comma 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-Cwd | header | string | No | Per-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-Dir | header | string | No | Per-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-Realm | header | string | No | Per-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. |
realm | query | string | No | Query 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.
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" \ -Nimport { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' });
const stream = await client.agent.sessions.streamMany({ ids: '67e89abc123def456789abc1,67e89abc123def456789abc2', since: '67e89abc123def456789abc1:42,67e89abc123def456789abc2:17', incarnation: '67e89abc123def456789abc1:0123456789abcdef0123456789abcdef,67e89abc123def456789abc2:fedcba9876543210fedcba9876543210', cwd: '/home/user/project', configDir: '/home/user/.hoody', agentRealm: 'global'});
for await (const frame of stream) { console.log(frame.session_id, frame.seq, frame.event);}Response
Section titled “Response”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_boundarydata: {"session_id":"67e89abc123def456789abc1","max_seq":2,"incarnation":"0123456789abcdef0123456789abcdef"}
event: stream_chunkdata: {"session_id":"67e89abc123def456789abc1","seq":43,"incarnation":"0123456789abcdef0123456789abcdef","turn_id":"67e89abc123def456789abc3","event":{"type":"event.stream_chunk","data":{"text":"Checking the build output."}}}
event: stream_chunkdata: {"session_id":"67e89abc123def456789abc2","seq":18,"incarnation":"fedcba9876543210fedcba9876543210","event":{"type":"event.stream_chunk","data":{"text":"The test suite is running."}}}
event: session_laggeddata: {"session_id":"67e89abc123def456789abc2","code":"lagged"}
event: stream_chunkdata: {"session_id":"67e89abc123def456789abc1","seq":44,"incarnation":"0123456789abcdef0123456789abcdef","event":{"type":"event.stream_chunk","data":{"text":"The build error is in the config file."}}}
event: session_enddata: {"session_id":"67e89abc123def456789abc1","reason":"session closed"}
event: enddata: {"reason":"no sessions left"}Media type: application/json
The ids parameter is missing, blank, repeated, or contains more than 32 values. A since or incarnation entry does not have the form <id>:<value> or names an id outside ids. The request can also be rejected when a computer header is supplied.
{ "code": "bad_request", "message": "invalid request"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The request was malformed or carried invalid parameters. | Correct the request body or query parameters. |
realm_scope_unsupported | Realm scope unsupported | A per-request scope header this route does not take: a realm or computer header on a route without that dimension, or, on an agent pinned to one realm, a different realm. | Omit the header, or name the realm the agent is pinned to. |
invalid_realm | Invalid realm selector | The realm selector is malformed, not "", global, or a 24-hex id. | Pass a valid realm selector. |
Media type: application/json
{ "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
forbidden | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL, for example with hoody agent …. |
Media type: application/json
The realm named by the realm header or query is not one this login serves.
{ "code": "not_found", "message": "resource not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
not_found | Not found | The requested resource does not exist. | Verify the path and identifier. |
Media type: application/json
{ "code": "rate_limited", "message": "request rate limit exceeded"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
rate_limited | Too many requests | The per-client request rate limit was exceeded. The gateway throttled the request before dispatch. | Honor the Retry-After header and retry. Reduce the request rate. |
Media type: application/json
{ "code": "service_unavailable", "message": "service unavailable"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
service_unavailable | Service unavailable | The daemon could not service the request because it was too busy or a per-client stream concurrency cap was reached. | Honor Retry-After and retry. |
restriction_unknown | Login restriction unknown | The agent cannot read yet which realms its login may serve. GET /api/v1/agent/hoody/auth/status reports restriction unknown, so the agent refuses realm-scoped requests until it can read the restriction. Nothing was read or changed. | Retry after the restriction is readable. |
Replay buffered events
Section titled “Replay buffered events”GET /api/v1/agent/sessions/{id}/replay
Section titled “GET /api/v1/agent/sessions/{id}/replay”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.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | The session id. |
X-Hoody-Cwd | header | string | No | Per-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-Dir | header | string | No | Per-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-Computer | header | string | No | Per-request bound remote computer. Omitting it selects the local computer. It is rejected with 400 on routes with no computer dimension. |
X-Hoody-Realm | header | string | No | Per-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. |
realm | query | string | No | Query 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.
curl -X GET "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/sessions/67e89abc123def456789abc1/replay"import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' });
const replay = await client.agent.sessions.replay('67e89abc123def456789abc1');Response
Section titled “Response”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 }}Media type: application/json
{ "code": "bad_request", "message": "invalid request"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The request was malformed or carried invalid parameters. | Correct the request body or query parameters. |
realm_scope_unsupported | Realm scope unsupported | A per-request scope header this route does not take: a realm or computer header on a route without that dimension, or, on an agent pinned to one realm, a different realm. | Omit the header, or name the realm the agent is pinned to. |
invalid_realm | Invalid realm selector | The realm selector is malformed, not "", global, or a 24-hex id. | Pass a valid realm selector. |
Media type: application/json
{ "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
forbidden | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL, for example with hoody agent …. |
Media type: application/json
{ "code": "not_found", "message": "resource not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
not_found | Not found | The requested resource does not exist. | Verify the path and identifier. |
Media type: application/json
{ "code": "rate_limited", "message": "request rate limit exceeded"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
rate_limited | Too many requests | The per-client request rate limit was exceeded. The gateway throttled the request before dispatch. | Honor the Retry-After header and retry. Reduce the request rate. |
Media type: application/json
{ "code": "internal_error", "message": "internal server error"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
internal_error | Internal error | An unexpected error occurred while handling the request. | Retry. If the error persists, inspect the daemon logs. |
Media type: application/json
{ "code": "service_unavailable", "message": "service unavailable"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
service_unavailable | Service unavailable | The daemon could not service the request because it was too busy or a per-client stream concurrency cap was reached. | Honor Retry-After and retry. |
Recoverable state
Section titled “Recoverable state”GET /api/v1/agent/sessions/{id}/state
Section titled “GET /api/v1/agent/sessions/{id}/state”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.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | The session id. |
X-Hoody-Cwd | header | string | No | Per-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-Dir | header | string | No | Per-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-Computer | header | string | No | Per-request bound remote computer. Omitting it selects the local computer. It is rejected with 400 on routes with no computer dimension. |
X-Hoody-Realm | header | string | No | Per-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. |
realm | query | string | No | Query 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.
curl -X GET "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/sessions/67e89abc123def456789abc1/state"import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' });
const snapshot = await client.agent.sessions.getSnapshot('67e89abc123def456789abc1');Response
Section titled “Response”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 }}Media type: application/json
{ "code": "bad_request", "message": "invalid request"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The request was malformed or carried invalid parameters. | Correct the request body or query parameters. |
realm_scope_unsupported | Realm scope unsupported | A per-request scope header this route does not take: a realm or computer header on a route without that dimension, or, on an agent pinned to one realm, a different realm. | Omit the header, or name the realm the agent is pinned to. |
invalid_realm | Invalid realm selector | The realm selector is malformed, not "", global, or a 24-hex id. | Pass a valid realm selector. |
Media type: application/json
{ "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
forbidden | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL, for example with hoody agent …. |
Media type: application/json
{ "code": "not_found", "message": "resource not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
not_found | Not found | The requested resource does not exist. | Verify the path and identifier. |
Media type: application/json
{ "code": "rate_limited", "message": "request rate limit exceeded"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
rate_limited | Too many requests | The per-client request rate limit was exceeded. The gateway throttled the request before dispatch. | Honor the Retry-After header and retry. Reduce the request rate. |
Media type: application/json
{ "code": "internal_error", "message": "internal server error"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
internal_error | Internal error | An unexpected error occurred while handling the request. | Retry. If the error persists, inspect the daemon logs. |
Media type: application/json
{ "code": "restriction_unknown", "message": "the login's realm restriction could not be read — retry"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
restriction_unknown | Login restriction unknown | The agent cannot read yet which realms its login may serve. GET /api/v1/agent/hoody/auth/status reports restriction unknown, so the agent refuses realm-scoped requests until it can read the restriction. Nothing was read or changed. | Retry after the restriction is readable. |
Persisted transcript
Section titled “Persisted transcript”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.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | The session id. |
after_turn | query | integer | No | Exclusive 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-Cwd | header | string | No | Per-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-Dir | header | string | No | Per-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-Realm | header | string | No | Per-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. |
realm | query | string | No | Query 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.
curl -X GET "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/sessions/67e89abc123def456789abc1/transcript?after_turn=0"import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' });
const transcript = await client.agent.sessions.getTranscript('67e89abc123def456789abc1', { after_turn: 0 });Response
Section titled “Response”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"}Media type: application/json
{ "code": "bad_request", "message": "invalid request"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The request was malformed or carried invalid parameters. | Correct the request body or query parameters. |
realm_scope_unsupported | Realm scope unsupported | A per-request scope header this route does not take: a realm or computer header on a route without that dimension, or, on an agent pinned to one realm, a different realm. | Omit the header, or name the realm the agent is pinned to. |
invalid_realm | Invalid realm selector | The realm selector is malformed, not "", global, or a 24-hex id. | Pass a valid realm selector. |
Media type: application/json
{ "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
forbidden | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL, for example with hoody agent …. |
Media type: application/json
{ "code": "not_found", "message": "resource not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
not_found | Not found | The requested resource does not exist. | Verify the path and identifier. |
Media type: application/json
{ "code": "rate_limited", "message": "request rate limit exceeded"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
rate_limited | Too many requests | The per-client request rate limit was exceeded. The gateway throttled the request before dispatch. | Honor the Retry-After header and retry. Reduce the request rate. |
Media type: application/json
{ "code": "internal_error", "message": "internal server error"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
internal_error | Internal error | An unexpected error occurred while handling the request. | Retry. If the error persists, inspect the daemon logs. |
Media type: application/json
{ "code": "restriction_unknown", "message": "the login's realm restriction could not be read — retry"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
restriction_unknown | Login restriction unknown | The agent cannot read yet which realms its login may serve. GET /api/v1/agent/hoody/auth/status reports restriction unknown, so the agent refuses realm-scoped requests until it can read the restriction. Nothing was read or changed. | Retry after the restriction is readable. |
Attached images
Section titled “Attached images”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.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | The session id. |
image_id | path | string | Yes | The image id. |
X-Hoody-Cwd | header | string | No | Per-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-Dir | header | string | No | Per-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-Realm | header | string | No | Per-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. |
realm | query | string | No | Query 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.
curl -X GET "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/sessions/67e89abc123def456789abc1/images/0d85f5af1e0dfa09503f0bdb179ab8f37c4225b43d442a3a91e59c3c849bc99e" \ --output image.pngimport { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' });
const image = await client.agent.sessions.getImage('67e89abc123def456789abc1', '0d85f5af1e0dfa09503f0bdb179ab8f37c4225b43d442a3a91e59c3c849bc99e');Response
Section titled “Response”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.
Media type: application/json
{ "code": "bad_request", "message": "invalid request"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The request was malformed or carried invalid parameters. | Correct the request body or query parameters. |
realm_scope_unsupported | Realm scope unsupported | A per-request scope header this route does not take: a realm or computer header on a route without that dimension, or, on an agent pinned to one realm, a different realm. | Omit the header, or name the realm the agent is pinned to. |
invalid_realm | Invalid realm selector | The realm selector is malformed, not "", global, or a 24-hex id. | Pass a valid realm selector. |
Media type: application/json
{ "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
forbidden | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL, for example with hoody agent …. |
Media type: application/json
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.
{ "code": "not_found", "message": "resource not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
not_found | Not found | The requested resource does not exist. | Verify the path and identifier. |
Media type: application/json
{ "code": "rate_limited", "message": "request rate limit exceeded"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
rate_limited | Too many requests | The per-client request rate limit was exceeded. The gateway throttled the request before dispatch. | Honor the Retry-After header and retry. Reduce the request rate. |
Media type: application/json
{ "code": "internal_error", "message": "internal server error"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
internal_error | Internal error | An unexpected error occurred while handling the request. | Retry. If the error persists, inspect the daemon logs. |
Media type: application/json
{ "code": "restriction_unknown", "message": "the login's realm restriction could not be read — retry"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
restriction_unknown | Login restriction unknown | The agent cannot read yet which realms its login may serve. GET /api/v1/agent/hoody/auth/status reports restriction unknown, so the agent refuses realm-scoped requests until it can read the restriction. Nothing was read or changed. | Retry after the restriction is readable. |