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

A turn is one user message dispatched into an agent session. This page covers the four ways to dispatch a turn, how to cancel one (the active turn on the session, or a named turn), how to send commands to a session that may already be working (a message, an interrupt, or a stop) and how to read their receipts, how to stop every running item in the realm, how to send input into a running workflow, and how to read the durable turn receipts that survive a disconnect or a daemon restart. Per-request scoping uses the standard X-Hoody-* headers (the realm is also accepted as a query parameter). Each route lists the headers it accepts; stop-all takes only the realm.

In the Hub, open AI > Chats and select the conversation. Enter your message and press Send. To end the running reply, press Stop.

Four endpoints dispatch a turn, each with a different posture. Pick by what your caller can do, not by what feels familiar.

EndpointBlocks until doneStreams eventsRetry-safe with Idempotency-Key
POST /api/v1/agent/sessions/{id}/messagesNo (returns 202 immediately)No (observe the session stream separately)Yes (returns the same receipt for the same key)
POST /api/v1/agent/sessions/{id}/prompt:syncUntil the turn ends, a gate needs a person, or 290 s (then 503 with details.turn_running)NoYes (returns the same outcome with duplicate: true, or pending_turn while it still runs)
POST /api/v1/agent/sessions/{id}/prompt:streamNo (opens SSE at once)Yes (SSE starting just before dispatch)Yes. While the original turn’s key is remembered, a retry with the same key and request returns 409 replay_unavailable with the original turn’s receipt and does not dispatch a second turn.
POST /api/v1/agent/sessions/{id}/turnsNo (returns 202 receipt once admitted)No (observe the session stream separately)Yes (returns the same receipt for the same key)

Fire-and-observe. Dispatches a user turn and returns immediately with {job_id, session_id, turn_id}. Observe agent_done on the session stream (its turn_id matches the response) to learn the outcome. The session is single-writer: a parked gate (409 gate_parked) or a running turn (409 turn_in_flight) refuses a new dispatch. Pass an optional Idempotency-Key to make a retry return the same receipt without re-running the turn; the same key with a different request body returns 422 idempotency_key_reused.

NameInTypeRequiredDescription
idpathstringYesThe session id.
X-Hoody-CwdheaderstringNoPer-request working-directory scope: the .hoody project layer / record cwd / tool+workflow cwd. Required by routes that resolve a cwd (e.g. POST /todos; createTodo also accepts a body cwd).
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override selecting which on-disk .hoody install a stateless read/write resolves against.
X-Hoody-RealmheaderstringNoPer-request realm selector: “global” (not tied to a realm) or a 24-hex realm id (also accepted as ?realm=). On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.
realmquerystringNoPer-request realm selector, the in:query alias of the X-Hoody-Realm header (read when the header is absent or empty): “global” (not tied to a realm) or a 24-hex realm id. On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.
Idempotency-KeyheaderstringNoOpaque retry key (1–255 printable ASCII, no whitespace). A retry with the same key returns the same receipt and never re-runs the turn; the same key with a different request body is 422.
X-Hoody-ComputerheaderstringNoPer-request bound remote computer (omitted = local). Rejected (400) on routes with no computer dimension.
FieldTypeRequiredDescription
textstringYesRequired (may be empty only with attachments). The user message text for this turn: empty or whitespace-only text with no attachments is refused (400 empty_prompt) and no turn runs.
tool_modestringNoOptional tool mode: standard or orchestrator. Not a per-turn override: the session’s first turn applies it and fixes it for the session’s lifetime (tool_mode_locked). On a later turn (including one queued before the first turn ran), the same value is accepted and a different one is refused 400 invalid_tool_mode; any other value is refused 400 invalid_tool_mode too.
dir_scopestringNoOptional directory-access scope: home or full. Not a per-turn override: the session’s first turn applies it and fixes it for the session’s lifetime (dir_scope_locked). On a later turn (including one queued before the first turn ran), the same value is accepted and a different one is refused 400 invalid_dir_scope; any other value is refused 400 invalid_dir_scope too.
attachmentsarrayNoOptional images for this turn, as INLINE base64 bytes. At most 4 per turn, each at most 4 MiB DECODED (~5.33 MiB of base64); the request body limit applies on top and is authoritative, so several individually-legal images can still exceed it. A violation is refused with 400 BEFORE the turn is accepted, nothing is silently dropped. path is not supported here: it would name a file on the CALLER’s machine, so an attachment with a non-empty path refuses the whole request with 400 bad_request before a turn is accepted. If the active model cannot accept images the daemon reports that on the session stream.

Media type: application/json

{
"job_id": "job-9f2c4e1ab07d3355",
"session_id": "sess-9f2c4e1ab07d3355",
"turn_id": "turn-9f2c4e1ab07d3355"
}
import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' });
const result = await client.agent.sessions.turns.start('sess-9f2c4e1ab07d3355', {
text: 'Summarize the last 10 commits in the repo.'
});
const turnId = result.data.turn_id;
Terminal window
curl -X POST "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/sessions/sess-9f2c4e1ab07d3355/messages" \
-H "Content-Type: application/json" \
-d '{ "text": "Summarize the last 10 commits in the repo." }'

POST /api/v1/agent/sessions/{id}/prompt:sync

Section titled “POST /api/v1/agent/sessions/{id}/prompt:sync”

Dispatches a turn and waits at most 290 seconds. Returns when the turn ends, or as soon as a turn parks on a confirm or question gate with 200 pending_gate (no status; the turn is still running). At the 290 s mark it returns 200 pending_gate if a gate needs a person, and otherwise 503 service_unavailable with details.turn_id and details.turn_running: true; the turn is NOT cancelled, follow it on the stream or with GET /sessions/{id}/turns/{turn_id}. Repeated prompt:sync against a parked session returns the same pending_gate (no duplicate parked turns). Pass X-Hoody-Gate-Policy: auto_approve (or ?policy=auto_approve) to adopt the headless posture and auto-answer confirm gates with approved=true, except a confirm gate a tool-call rule raised (its confirm_request carries rules: a check-in, or rules that could not be checked), and a destructive-shape gate (gate_cause static_stakes: a recursive force delete, curl piped to a shell, sudo, a force push…), which is answered approved=false. A human_only gate is never answered automatically: it returns as pending_gate for a person, as under the default posture. Question and plan gates still wait for /answer or /plan. Under auto_approve the posture is bound to the turn, not the request: once the request has ended (timeout, or the client went away) the turn’s confirm gates are still auto-answered until the turn ends (details.auto_approve: "until_turn_end" in the 503 body).

NameInTypeRequiredDescription
idpathstringYesThe session id.
policyquerystringNoauto_approve adopts the headless auto-answer posture (alias of the X-Hoody-Gate-Policy header); off by default; the gateway asks for no separate credentials to use it; access is decided by the computer’s proxy permission policy.
X-Hoody-Gate-PolicyheaderstringNoConfirm-gate posture: “auto_approve” adopts the headless auto-answer posture (off by default; the in:query alias is ?policy=). Any other value is rejected 400.
X-Hoody-CwdheaderstringNoPer-request working-directory scope: the .hoody project layer / record cwd / tool+workflow cwd. Required by routes that resolve a cwd (e.g. POST /todos; createTodo also accepts a body cwd).
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override selecting which on-disk .hoody install a stateless read/write resolves against.
X-Hoody-RealmheaderstringNoPer-request realm selector: “global” (not tied to a realm) or a 24-hex realm id (also accepted as ?realm=). On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.
realmquerystringNoPer-request realm selector, the in:query alias of the X-Hoody-Realm header (read when the header is absent or empty): “global” (not tied to a realm) or a 24-hex realm id. On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.
Idempotency-KeyheaderstringNoOpaque retry key (1–255 printable ASCII, no whitespace). The turn runs at most once per key: a retry answers 200 duplicate:true with the turn’s outcome (or pending_turn while it still runs) and never re-runs it; the same key with a different request body is 422.
X-Hoody-ComputerheaderstringNoPer-request bound remote computer (omitted = local). Rejected (400) on routes with no computer dimension.
FieldTypeRequiredDescription
textstringYesRequired (may be empty only with attachments). The user message text for this turn: empty or whitespace-only text with no attachments is refused (400 empty_prompt) and no turn runs.
tool_modestringNoOptional tool mode: standard or orchestrator. Not a per-turn override: the session’s first turn applies it and fixes it for the session’s lifetime (tool_mode_locked). On a later turn (including one queued before the first turn ran), the same value is accepted and a different one is refused 400 invalid_tool_mode; any other value is refused 400 invalid_tool_mode too.
dir_scopestringNoOptional directory-access scope: home or full. Not a per-turn override: the session’s first turn applies it and fixes it for the session’s lifetime (dir_scope_locked). On a later turn (including one queued before the first turn ran), the same value is accepted and a different one is refused 400 invalid_dir_scope; any other value is refused 400 invalid_dir_scope too.
attachmentsarrayNoOptional images for this turn, as INLINE base64 bytes. At most 4 per turn, each at most 4 MiB DECODED (~5.33 MiB of base64); the request body limit applies on top and is authoritative, so several individually-legal images can still exceed it. A violation is refused with 400 BEFORE the turn is accepted, nothing is silently dropped. path is not supported here: it would name a file on the CALLER’s machine, so an attachment with a non-empty path refuses the whole request with 400 bad_request before a turn is accepted. If the active model cannot accept images the daemon reports that on the session stream.

Media type: application/json

{
"status": "done",
"session_id": "sess-9f2c4e1ab07d3355",
"turn_id": "turn-9f2c4e1ab07d3355"
}

A parked turn returns {pending_gate} with no status. A keyed retry answering pending_turn has status: "running" and duplicate: true. Terminal outcomes carry status: done, error, canceled, or quit. A 290 s timeout returns pending_gate if a gate needs a person, otherwise 503 service_unavailable with details.turn_id and details.turn_running: true.

import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' });
const outcome = await client.agent.sessions.turns.run('sess-9f2c4e1ab07d3355', {
text: 'Summarize the last 10 commits in the repo.'
});
Terminal window
curl -X POST "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/sessions/sess-9f2c4e1ab07d3355/prompt:sync" \
-H "Content-Type: application/json" \
-d '{ "text": "Summarize the last 10 commits in the repo." }'

POST /api/v1/agent/sessions/{id}/prompt:stream

Section titled “POST /api/v1/agent/sessions/{id}/prompt:stream”

Stream the response. Dispatches a turn and opens an SSE stream positioned at the seq captured just before dispatch, so the first frames are this turn’s rather than the retained ring’s backlog.

Pass X-Hoody-Gate-Policy: auto_approve (or ?policy=auto_approve) to auto-answer confirm gates with approved=true for the life of the stream, except a gate a tool-call rule raised (its confirm_request carries rules), which it answers approved=false, and a destructive-shape gate (gate_cause static_stakes), which it also answers approved=false, and a human_only gate, which it never answers and leaves for a person (POST /api/v1/agent/sessions/{id}/confirm). Off by default.

NameInTypeRequiredDescription
idpathstringYesThe session id.
policyquerystringNoauto_approve auto-answers confirm gates for the life of the stream (alias of the X-Hoody-Gate-Policy header); off by default.
X-Hoody-Gate-PolicyheaderstringNoConfirm-gate posture: auto_approve adopts the headless auto-answer posture. Any other value is rejected with 400.
X-Hoody-CwdheaderstringNoPer-request working-directory scope.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override.
X-Hoody-RealmheaderstringNoPer-request realm selector (global or a 24-hex id).
realmquerystringNoPer-request realm selector (query alias of X-Hoody-Realm, read when the header is absent or empty).
Idempotency-KeyheaderstringNoOpaque retry key (1–255 printable ASCII, no whitespace). The turn runs at most once per key: a retry is 409 replay_unavailable with the turn’s receipt (details.turn), never a re-run and never a second stream; the same key with a different request body is 422.
X-Hoody-ComputerheaderstringNoPer-request bound remote computer (omitted = local). Rejected (400) on routes with no computer dimension.
FieldTypeRequiredDescription
textstringYesRequired (may be empty only with attachments). The user message text for this turn: empty or whitespace-only text with no attachments is refused (400 empty_prompt) and no turn runs.
tool_modestringNoOptional tool mode: standard or orchestrator. Not a per-turn override: the session’s first turn applies it and fixes it for the session’s lifetime (tool_mode_locked). On a later turn (including one queued before the first turn ran), the same value is accepted and a different one is refused 400 invalid_tool_mode; any other value is refused 400 invalid_tool_mode too.
dir_scopestringNoOptional directory-access scope: home or full. Not a per-turn override: the session’s first turn applies it and fixes it for the session’s lifetime (dir_scope_locked). On a later turn (including one queued before the first turn ran), the same value is accepted and a different one is refused 400 invalid_dir_scope; any other value is refused 400 invalid_dir_scope too.
attachmentsarrayNoOptional images for this turn, as INLINE base64 bytes. At most 4 per turn, each at most 4 MiB DECODED (~5.33 MiB of base64); the request body limit applies on top and is authoritative, so several individually-legal images can still exceed it. A violation is refused with 400 BEFORE the turn is accepted, nothing is silently dropped. path is not supported here: it would name a file on the CALLER’s machine, so an attachment with a non-empty path refuses the whole request with 400 bad_request before a turn is accepted. If the active model cannot accept images the daemon reports that on the session stream.

Media type: text/event-stream

Response is text/event-stream. Stop reading at the agent_done whose turn_id matches the X-Hoody-Turn-Id response header, then close the connection yourself. The stream opens with a replay_boundary control frame (no id line); each catalogue event frame has event: <type without the event. prefix>, id: <seq> and data: {seq, incarnation, turn_id, event: {type, data}}. See Session streaming for the frame format.

event: replay_boundary
data: {"max_seq":41,"incarnation":"0123456789abcdef0123456789abcdef","turn_id":"turn-9f2c4e1ab07d3355"}
event: stream_chunk
id: 42
data: {"seq":42,"incarnation":"0123456789abcdef0123456789abcdef","turn_id":"turn-9f2c4e1ab07d3355","event":{"type":"event.stream_chunk","data":{"text":"I'll look that up.\n"}}}
event: tool_call
id: 43
data: {"seq":43,"incarnation":"0123456789abcdef0123456789abcdef","turn_id":"turn-9f2c4e1ab07d3355","event":{"type":"event.tool_call","data":{"tool_id":"toolu-1","name":"shell","arguments":{"cmd":"git log --oneline -10"}}}}
event: agent_done
id: 44
data: {"seq":44,"incarnation":"0123456789abcdef0123456789abcdef","turn_id":"turn-9f2c4e1ab07d3355","event":{"type":"event.agent_done","data":{"turn_id":"turn-9f2c4e1ab07d3355","outcome":"completed"}}}
import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' });
await client.agent.sessions.turns.start('sess-9f2c4e1ab07d3355', {
text: 'What is in this image?',
attachments: [
{
type: 'image',
media_type: 'image/png',
data: 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkAAIAAAoAAv/lxKUAAAAASUVORK5CYII='
}
]
}, {
stream: true,
gatePolicy: 'auto_approve'
});
Terminal window
curl -X POST "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/sessions/sess-9f2c4e1ab07d3355/prompt:stream?policy=auto_approve" \
-H "Content-Type: application/json" \
-H "Accept: text/event-stream" \
-d '{ "text": "What is in this image?", "attachments": [{ "type": "image", "media_type": "image/png", "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkAAIAAAoAAv/lxKUAAAAASUVORK5CYII=" }] }'

Retry-safe dispatch. Dispatches a user turn and returns 202 with a durable receipt once the daemon has admitted it.

The session is single-writer: a parked gate (409 gate_parked) or a running turn (409 turn_in_flight) refuses a new dispatch and records nothing. If the daemon does not acknowledge within the wait the answer is 503 admission_unconfirmed carrying turn_id and result_url; the turn may still have been accepted, so poll result_url before retrying (acceptance is never invented and never rolled back). A ledger write failure is 503 admission_write_failed (fail-closed). A turn interrupted by a daemon restart replays as state interrupted with effects_may_have_occurred: true and is never re-run.

NameInTypeRequiredDescription
idpathstringYesThe session id.
Idempotency-KeyheaderstringNoOpaque retry key (1 to 255 printable ASCII, no whitespace). A retry with the same key returns the same receipt and never re-runs the turn; the same key with a different request body returns 422.
X-Hoody-CwdheaderstringNoPer-request working-directory scope.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override.
X-Hoody-RealmheaderstringNoPer-request realm selector (global or a 24-hex id).
realmquerystringNoPer-request realm selector (query alias of X-Hoody-Realm, read when the header is absent or empty).
policyquerystringNoauto_approve auto-answers the admitted turn’s confirm gates until it ends (alias of the X-Hoody-Gate-Policy header); off by default; the gateway asks for no separate credentials to use it; access is decided by the computer’s proxy permission policy.
X-Hoody-Gate-PolicyheaderstringNoConfirm-gate posture: “auto_approve” adopts the headless auto-answer posture (off by default; the in:query alias is ?policy=). Any other value is rejected 400.
X-Hoody-ComputerheaderstringNoPer-request bound remote computer (omitted = local). Rejected (400) on routes with no computer dimension.
FieldTypeRequiredDescription
textstringYesRequired (may be empty only with attachments). The user message text for this turn: empty or whitespace-only text with no attachments is refused (400 empty_prompt) and no turn runs.
tool_modestringNoOptional tool mode: standard or orchestrator. Not a per-turn override: the session’s first turn applies it and fixes it for the session’s lifetime (tool_mode_locked). On a later turn (including one queued before the first turn ran), the same value is accepted and a different one is refused 400 invalid_tool_mode; any other value is refused 400 invalid_tool_mode too.
dir_scopestringNoOptional directory-access scope: home or full. Not a per-turn override: the session’s first turn applies it and fixes it for the session’s lifetime (dir_scope_locked). On a later turn (including one queued before the first turn ran), the same value is accepted and a different one is refused 400 invalid_dir_scope; any other value is refused 400 invalid_dir_scope too.
attachmentsarrayNoOptional images for this turn, as INLINE base64 bytes. At most 4 per turn, each at most 4 MiB DECODED (~5.33 MiB of base64); the request body limit applies on top and is authoritative, so several individually-legal images can still exceed it. A violation is refused with 400 BEFORE the turn is accepted, nothing is silently dropped. path is not supported here: it would name a file on the CALLER’s machine, so an attachment with a non-empty path refuses the whole request with 400 bad_request before a turn is accepted. If the active model cannot accept images the daemon reports that on the session stream.

Media type: application/json

{
"turn_id": "turn-9f2c4e1ab07d3355",
"job_id": "job-9f2c4e1ab07d3355",
"state": "accepted",
"accepted_at": "2025-04-12T14:32:11Z",
"result_url": "/api/v1/agent/sessions/sess-9f2c4e1ab07d3355/turns/turn-9f2c4e1ab07d3355",
"stream_url": "/api/v1/agent/sessions/sess-9f2c4e1ab07d3355/stream",
"notices": []
}
import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' });
const receipt = await client.agent.sessions.turns.create('sess-9f2c4e1ab07d3355', {
text: 'Summarize the last 10 commits in the repo.'
}, {
idempotencyKey: '01HX5G2EXAMPLE1234567890AB'
});
Terminal window
curl -X POST "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/sessions/sess-9f2c4e1ab07d3355/turns" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 01HX5G2EXAMPLE1234567890AB" \
-d '{ "text": "Summarize the last 10 commits in the repo." }'

Cancels the active turn on the session (the historical “Esc” behaviour), or, when a turn_id is supplied, cancels only that named turn.

NameInTypeRequiredDescription
idpathstringYesThe session id.
turn_idquerystringNoCancel only this turn (alternative to the body field).
X-Hoody-CwdheaderstringNoPer-request working-directory scope.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override.
X-Hoody-RealmheaderstringNoPer-request realm selector (global or a 24-hex id).
realmquerystringNoPer-request realm selector (query alias of X-Hoody-Realm, read when the header is absent or empty).
X-Hoody-ComputerheaderstringNoPer-request bound remote computer (omitted = local). Rejected (400) on routes with no computer dimension.
FieldTypeRequiredDescription
turn_idstringNoThe turn to cancel, as returned when it was dispatched. Cancels only that turn. Omit (or send {}) to cancel whatever is running.
{
"status": "ok",
"turn_id": "turn-9f2c4e1ab07d3355",
"matched": true
}

matched is present on a turn-scoped cancel: false when the named turn no longer held the slot, in which case nothing was cancelled.

import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' });
// Cancel a specific turn by id.
const result = await client.agent.sessions.turns.cancel('sess-9f2c4e1ab07d3355', {
turn_id: 'turn-9f2c4e1ab07d3355'
});
// Cancel whatever turn is currently running on the session.
await client.agent.sessions.turns.cancel('sess-9f2c4e1ab07d3355', {});
Terminal window
# Cancel a specific turn.
curl -X POST "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/sessions/sess-9f2c4e1ab07d3355/cancel" \
-H "Content-Type: application/json" \
-d '{ "turn_id": "turn-9f2c4e1ab07d3355" }'
# Cancel whatever turn is currently running.
curl -X POST "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/sessions/sess-9f2c4e1ab07d3355/cancel" \
-H "Content-Type: application/json" \
-d '{}'

Commands: reaching a session that may already be working

Section titled “Commands: reaching a session that may already be working”

Reach a live session, working or idle, with a message, an interrupt, or a stop. Returns 202 with the command’s receipt once the agent has recorded it. The Idempotency-Key header is required: a retry with the same key and the same command returns the stored receipt (with duplicate: true) and admits nothing; the same key with a different command is 422 idempotency_key_reused.

Commands reach live sessions only: a closed session is 409 session_closed, an unknown session is 404, and a headless or internal session (a TODO run) is 409 command_unsupported. A configured UserPromptSubmit hook sees each message before delivery and can refuse it (state refused, reason hook). Stream events announce delivered commands (event.command_committed) and the ones that ended otherwise (event.command_settled).

Sends a command to a live session.

Kind message delivers text to the session at its next step. An idle session starts a turn for the message. text is required, non-empty, and at most 32 KiB (more is 400 bad_request).

Kind interrupt stops the work the session was running when the interrupt was sent, then delivers text as a new turn. Background tasks, background workflow runs, and background shells keep running (a stop ends them). The receipt says whether work was running (interrupted). text is required, non-empty, and at most 32 KiB.

Kind stop stops all of the session’s work, pauses its loops, and supersedes every message and interrupt sent before it that has not been delivered. A stop carries no text. The receipt’s stopped lists what the stop acted on and how each ended. With close: true the session is closed once its work is stopped, and later commands are 409 session_closed.

order (optional, at least 0) sequences one caller’s commands: a message or interrupt with a positive order lower than the highest stop order the session has recorded is superseded at once (reason: order), whoever sent the stop. order: 0, or omitting it, skips this check. from and trigger are attribution only (they change how the message is introduced to the model); the agent does not verify them. The text waiting on one session is at most 128 KiB (more is 429 command_queue_full with Retry-After).

NameInTypeRequiredDescription
idpathstringYesThe session id.
Idempotency-KeyheaderstringYesRetry key, required on this route; the SDK and CLI send one automatically. 1–255 printable ASCII, no whitespace. A retry with the same key and command returns the stored receipt and admits nothing; the same key with a different command is 422. The key is remembered while the command waits and for 24 hours after it settled. Past 4096 remembered keys a new key is 429 idempotency_keys_exhausted; a stop is never refused because of the remembered-key limit.
X-Hoody-CwdheaderstringNoPer-request working-directory scope: the .hoody project layer / record cwd / tool+workflow cwd. Required by routes that resolve a cwd (e.g. POST /todos; createTodo also accepts a body cwd).
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override selecting which on-disk .hoody install a stateless read/write resolves against.
X-Hoody-RealmheaderstringNoPer-request realm selector: “global” (not tied to a realm) or a 24-hex realm id (also accepted as ?realm=). On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.
realmquerystringNoPer-request realm selector, the in:query alias of the X-Hoody-Realm header (read when the header is absent or empty): “global” (not tied to a realm) or a 24-hex realm id. On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.
X-Hoody-ComputerheaderstringNoPer-request bound remote computer (omitted = local). Rejected (400) on routes with no computer dimension.
FieldTypeRequiredDescription
kindstringYesmessage, interrupt, or stop.
textstringNoThe message text (message and interrupt: required, non-empty, at most 32 KiB). Delivered verbatim. A stop takes none.
closebooleanNoA stop only: close the session once its work is stopped.
on_gatestringNoA message only: deny (default) declines a confirmation or question the session is waiting on so the message is read now; wait leaves it waiting. A Claude Code session reads the message when its turn ends; deny still declines its confirmations, so the turn ends. A fusion model, or a turn started by a loop or a finished background task, keeps waiting either way.
orderintegerNoOptional, at least 0: a sequence number for your commands. A message or interrupt with a positive order lower than the highest stop order the session has recorded is superseded, whoever sent the stop. 0, or omitting it, skips this check.
fromobjectNoWho sends it (kind enum: user, bot, delegate, system; optional id of at most 256 bytes). Attribution only, never authorization.
triggerstringNoWhat caused it (enum: human, wake, clear). Recorded on the receipt. Attribution only, never authorization.
{
"kind": "message",
"text": "Also update the README when you are done."
}

Media type: application/json

{
"admitted_at": "2026-10-08T14:03:11.204Z",
"command_id": "cmd_3f2a9c1e5b7d40a1c2e8f6d9",
"kind": "message",
"state": "queued"
}

A receipt carries the command’s state: queued, committed, superseded, refused, or failed. A committed receipt also carries how (next_step, new_turn, or stop) and, except for a stop, turn_id. A stop receipt’s stopped lists what it acted on (kind session, task, workflow_run, bash_job, or loop) and the outcome per item (stopped, already_done, or failed).

import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' });
const receipt = await client.agent.sessions.commands.send('sess-9f2c4e1ab07d3355', {
kind: 'message',
text: 'Also update the README when you are done.'
}, {
idempotencyKey: '01HX5G2EXAMPLE1234567890AB'
});
// Track a stop; the receipt's stopped tells you what it ended.
const stop = await client.agent.sessions.commands.send('sess-9f2c4e1ab07d3355', {
kind: 'stop',
close: true
}, {
idempotencyKey: '01HX5G2EXAMPLE1234567890CD'
});
Terminal window
# Send a message.
curl -X POST "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/sessions/sess-9f2c4e1ab07d3355/commands" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 01HX5G2EXAMPLE1234567890AB" \
-d '{ "kind": "message", "text": "Also update the README when you are done." }'
# Stop everything and close the session.
curl -X POST "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/sessions/sess-9f2c4e1ab07d3355/commands" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 01HX5G2EXAMPLE1234567890CD" \
-d '{ "kind": "stop", "close": true }'

GET /api/v1/agent/sessions/{id}/commands/{command_id}

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

Returns the receipt of a command sent to this session. state is queued until the command is delivered, then committed (with how, and turn_id except for a stop), superseded, refused, or failed. The session must be live: a closed session is 409 session_closed. A command id this session never admitted is 404, and so is one whose receipt is no longer kept (a receipt is kept while its command waits and for 24 hours after it settled). Cache-Control: no-store.

NameInTypeRequiredDescription
idpathstringYesThe session id.
command_idpathstringYesThe command id.
X-Hoody-CwdheaderstringNoPer-request working-directory scope: the .hoody project layer / record cwd / tool+workflow cwd. Required by routes that resolve a cwd (e.g. POST /todos; createTodo also accepts a body cwd).
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override selecting which on-disk .hoody install a stateless read/write resolves against.
X-Hoody-RealmheaderstringNoPer-request realm selector: “global” (not tied to a realm) or a 24-hex realm id (also accepted as ?realm=). On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.
realmquerystringNoPer-request realm selector, the in:query alias of the X-Hoody-Realm header (read when the header is absent or empty): “global” (not tied to a realm) or a 24-hex realm id. On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.
X-Hoody-ComputerheaderstringNoPer-request bound remote computer (omitted = local). Rejected (400) on routes with no computer dimension.

Media type: application/json

{
"admitted_at": "2026-10-08T14:03:11.204Z",
"command_id": "cmd_3f2a9c1e5b7d40a1c2e8f6d9",
"kind": "message",
"state": "queued"
}

A committed receipt carries turn_id (the running turn when how is next_step, or the turn it started when how is new_turn; absent for a stop) and committed_at. A superseded receipt carries superseded_by (the command_id of the stop that superseded it); reason is stop (a stop sent after it), order (a stop with a higher order), or withdrawn (the sender took the message back before the session took it). A refused receipt carries reason (hook, closed, or unsupported) and an optional detail (for example, the hook’s message). A failed receipt carries reason: write_failed. A stop receipt’s stopped lists what it acted on and how each ended; interrupted appears on an interrupt receipt (whether running work was stopped for it).

import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' });
// Poll the receipt returned by POST /commands.
const r = await client.agent.sessions.commands.get('sess-9f2c4e1ab07d3355', 'cmd_3f2a9c1e5b7d40a1c2e8f6d9');
const state = r.data.state;
Terminal window
curl -X GET "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/sessions/sess-9f2c4e1ab07d3355/commands/cmd_3f2a9c1e5b7d40a1c2e8f6d9"

POST /api/v1/agent/sessions/{id}/commands/{command_id}/withdraw

Section titled “POST /api/v1/agent/sessions/{id}/commands/{command_id}/withdraw”

Takes back a queued message that the session has not taken yet. The decision is made with the session’s queue, so a message is either withdrawn or delivered, never both.

outcome is withdrawn when the message was still waiting. It is recorded as state: superseded with reason: withdrawn before the response, its text is dropped, and it never reaches the session. Repeating the request answers withdrawn again and changes nothing. outcome is taken when the session has already taken the message, and ended when the message had already ended for another reason. Neither taken nor ended withdraws the message or changes the receipt.

Only a message can be withdrawn. The Idempotency-Key used to send the message continues to answer its receipt, so a resend under that key never admits it again. A changed message is a new command under a new key, sent only after withdrawn or ended.

NameInTypeRequiredDescription
idpathstringYesThe session id.
command_idpathstringYesThe command id.
X-Hoody-CwdheaderstringNoPer-request working-directory scope: the .hoody project layer / record cwd / tool+workflow cwd. Required by routes that resolve a cwd. The value must be UTF-8.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override selecting which on-disk .hoody install a stateless read/write resolves against. The value must be UTF-8.
X-Hoody-ComputerheaderstringNoPer-request bound remote computer (omitted = local).
X-Hoody-RealmheaderstringNoPer-request realm selector: global or a 24-hex realm id. On a session route it names the realm the session is looked up in.
realmquerystringNoPer-request realm selector, the query alias of X-Hoody-Realm, read when the header is absent or empty.

This endpoint takes no request body.

Media type: application/json

{
"command": {
"admitted_at": "2026-10-08T14:03:11.204Z",
"command_id": "cmd_3f2a9c1e5b7d40a1c2e8f6d9",
"kind": "message",
"reason": "withdrawn",
"state": "superseded"
},
"outcome": "withdrawn"
}

The command object is the command receipt. Its required fields are command_id, kind, state, and admitted_at. Optional fields are duplicate, turn_id, how, committed_at, interrupted, reason, detail, superseded_by, stopped, cleanup, close, order, from, and trigger.

outcome is withdrawn, taken, or ended. A receipt’s kind is message, interrupt, or stop; its state is queued, committed, superseded, refused, or failed; and its reason is stop, order, hook, closed, unsupported, write_failed, or withdrawn. Each stopped item has required kind, id, and outcome fields, with optional detail and cleanup fields. from.kind is user, bot, delegate, or system.

import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' });
const result = await client.agent.sessions.commands.withdraw(
'sess-9f2c4e1ab07d3355',
'cmd_3f2a9c1e5b7d40a1c2e8f6d9'
);
const outcome = result.data.outcome;
Terminal window
curl -X POST "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/sessions/sess-9f2c4e1ab07d3355/commands/cmd_3f2a9c1e5b7d40a1c2e8f6d9/withdraw"

GET /api/v1/agent/sessions/{id}/commands/by-key/{key}

Section titled “GET /api/v1/agent/sessions/{id}/commands/by-key/{key}”

Returns the receipt of the command a keyed POST /api/v1/agent/sessions/{id}/commands admitted, by its key: the same record GET /api/v1/agent/sessions/{id}/commands/{command_id} returns. {key} is the Idempotency-Key the request was sent with (1 to 255 printable ASCII, no whitespace; URL-encode it). The session must be live: a closed session is 409 session_closed. Reads never admit anything. A 404 command_not_found with details.retired false proves nothing (the command may still be on its way, or its receipt expired 24 hours after it settled); POST /api/v1/agent/sessions/{id}/commands/by-key/{key}/retire settles it. Responses carry Cache-Control: no-store.

NameInTypeRequiredDescription
idpathstringYesThe session id.
keypathstringYesThe key.
X-Hoody-CwdheaderstringNoPer-request working-directory scope: the .hoody project layer / record cwd / tool+workflow cwd. Required by routes that resolve a cwd (e.g. POST /api/v1/agent/todos; createTodo also accepts a body cwd). The value must be UTF-8: other bytes (a non-ASCII path sent as Latin-1) are refused 400 bad_request.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override selecting which on-disk .hoody install a stateless read/write resolves against. The value must be UTF-8: other bytes are refused 400 bad_request.
X-Hoody-RealmheaderstringNoPer-request realm selector: “global” (not tied to a realm) or a 24-hex realm id (also accepted as ?realm=). On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.
realmquerystringNoPer-request realm selector, the in:query alias of the X-Hoody-Realm header (read when the header is absent or empty): “global” (not tied to a realm) or a 24-hex realm id. On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.
X-Hoody-ComputerheaderstringNoPer-request bound remote computer (omitted = local). Rejected (400) on routes with no computer dimension.

This endpoint takes no request body.

{
"admitted_at": "2026-10-08T14:03:11.204Z",
"command_id": "cmd_3f2a9c1e5b7d40a1c2e8f6d9",
"kind": "message",
"state": "queued"
}

The receipt never contains the command’s text. state is queued until the command is delivered, then committed (with how, and turn_id except for a stop), superseded, refused, or failed.

import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' });
const receipt = await client.agent.sessions.commands.getByKey('sess-9f2c4e1ab07d3355', '01HX5G2EXAMPLE1234567890AB');
const state = receipt.data.state;
Terminal window
curl -X GET "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/sessions/sess-9f2c4e1ab07d3355/commands/by-key/01HX5G2EXAMPLE1234567890AB"

POST /api/v1/agent/sessions/{id}/commands/by-key/{key}/retire

Section titled “POST /api/v1/agent/sessions/{id}/commands/by-key/{key}/retire”

Settles a keyed command whose answer was lost. {key} is the Idempotency-Key the request was sent with (1 to 255 printable ASCII, no whitespace; URL-encode it). A key whose command is kept answers retired false, admitted "true" and the receipt. Otherwise the key is retired durably on this session: retired true, and a command sent with it earlier and delivered later is refused 409 command_key_retired; retiring it again answers the same. admitted is "false" only while no receipt of this session has expired; otherwise "unknown" (the key may have admitted a command whose receipt is gone: treat it as possibly run). The session must be live: a closed session is 409 session_closed. A 503 is unknown: nothing is proven, retire again after Retry-After. 409 command_fences_exhausted: the key was NOT retired, so a delayed command sent with it can still be admitted; never send a replacement. A retire request never runs the original command, but a command already admitted with the key may have run or may still run. The request has no body.

NameInTypeRequiredDescription
idpathstringYesThe session id.
keypathstringYesThe key.
X-Hoody-CwdheaderstringNoPer-request working-directory scope: the .hoody project layer / record cwd / tool+workflow cwd. Required by routes that resolve a cwd (e.g. POST /api/v1/agent/todos; createTodo also accepts a body cwd). The value must be UTF-8: other bytes (a non-ASCII path sent as Latin-1) are refused 400 bad_request.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override selecting which on-disk .hoody install a stateless read/write resolves against. The value must be UTF-8: other bytes are refused 400 bad_request.
X-Hoody-RealmheaderstringNoPer-request realm selector: “global” (not tied to a realm) or a 24-hex realm id (also accepted as ?realm=). On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.
realmquerystringNoPer-request realm selector, the in:query alias of the X-Hoody-Realm header (read when the header is absent or empty): “global” (not tied to a realm) or a 24-hex realm id. On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.
X-Hoody-ComputerheaderstringNoPer-request bound remote computer (omitted = local). Rejected (400) on routes with no computer dimension.

This endpoint takes no request body.

{
"admitted": "false",
"retired": true
}

With admitted "true", the answer also carries command, the receipt of the command the key admitted. With admitted "false", nothing was admitted with the key and nothing can be from now on. "unknown" means a command sent with the key earlier may have been admitted and run.

import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' });
const settled = await client.agent.sessions.commands.retireKey('sess-9f2c4e1ab07d3355', '01HX5G2EXAMPLE1234567890AB');
const retired = settled.data.retired;
Terminal window
curl -X POST "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/sessions/sess-9f2c4e1ab07d3355/commands/by-key/01HX5G2EXAMPLE1234567890AB/retire"

Stops, in one call, all running work in the realm the caller may see. It covers running or parked session turns (every live session, including system, resident, and headless ones; each is stopped like POST /sessions/{id}/cancel with the turn_id of the turn that was running when the call listed it, so a turn that starts later is never stopped, only reported under started_during_call), background tasks, workflow runs, todo runs (the lease is released as cancelled, as cancelTodoRun does), detached local background bash jobs, detached background bash jobs on bound computers, loops (PAUSED, never deleted: resume one with PATCH /sessions/{id}/loops/{loopId} {"paused":false}), and this gateway’s detached headless and gated tool jobs. Work it does not reach is named in not_covered.

In the Hub, select the computer and realm, open AI settings > Rules & hooks, and choose Stop everything in this realm…. Review and confirm the action, then read its result.

NameInTypeRequiredDescription
X-Hoody-RealmheaderstringNoPer-request realm selector: “global” (not tied to a realm) or a 24-hex realm id (also accepted as ?realm=). On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.
realmquerystringNoPer-request realm selector, the in:query alias of the X-Hoody-Realm header (read when the header is absent or empty): “global” (not tied to a realm) or a 24-hex realm id. On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.
FieldTypeRequiredDescription
afterstringNoA next_cursor from an earlier call, unchanged (the cursor is opaque): act only on the items after it. Any other value is 400 bad_request.
{
"behind_cursor": [],
"complete": true,
"items": [
{
"id": "5f0c2a91d3b44e7f",
"kind": "session",
"outcome": "stopped"
},
{
"id": "loop-3",
"kind": "loop",
"outcome": "stopped"
}
],
"not_covered": [
{
"kind": "sync_request",
"reason": "synchronous and streaming tool and headless requests end when their HTTP request is closed"
}
],
"started_during_call": []
}
import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' });
// Stop everything running in the realm (start from the first item).
const result = await client.agent.stopAllWork({});
// Continue with the items behind an earlier next_cursor.
const next = await client.agent.stopAllWork({ after: result.data.next_cursor });
Terminal window
# Stop everything running in the realm.
curl -X POST "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/stop" \
-H "Content-Type: application/json" \
-d '{}'
# Continue with the items behind an earlier next_cursor.
curl -X POST "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/stop" \
-H "Content-Type: application/json" \
-d '{ "after": "session/5f0c2a91d3b44e7f" }'

POST /api/v1/agent/sessions/{id}/workflow/messages

Section titled “POST /api/v1/agent/sessions/{id}/workflow/messages”

Sends feedback or input directly to the foreground or background workflow running in the session. The message is delivered to the workflow itself, not queued as a new session turn, and only the run that was active when the message was accepted receives it: a run that starts later never does. 200 means the daemon accepted it for that run. 409 no_active_workflow when no workflow is running: nothing is delivered or kept. 503 admission_unconfirmed when the daemon’s answer did not arrive within the wait: it may still be delivered.

NameInTypeRequiredDescription
idpathstringYesThe session id.
X-Hoody-CwdheaderstringNoPer-request working-directory scope.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override.
X-Hoody-RealmheaderstringNoPer-request realm selector (global or a 24-hex id).
realmquerystringNoPer-request realm selector (query alias of X-Hoody-Realm, read when the header is absent or empty).
X-Hoody-ComputerheaderstringNoPer-request bound remote computer (omitted = local). Rejected (400) on routes with no computer dimension.
FieldTypeRequiredDescription
textstringNoFeedback or input text fed to the running workflow.
{
"status": "ok"
}

The response carries only status.

import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' });
await client.agent.workflows.sendMessage('sess-9f2c4e1ab07d3355', {
text: 'Use the staged branch for the next attempt.'
});
Terminal window
curl -X POST "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/sessions/sess-9f2c4e1ab07d3355/workflow/messages" \
-H "Content-Type: application/json" \
-d '{ "text": "Use the staged branch for the next attempt." }'

Lists the durable receipts of the session’s turns, newest first. Each receipt is the same record returned by GET /sessions/{id}/turns/{turn_id}. This is how a client that lost its turn ids after a disconnect finds them again. Works for a live or dormant session. Pass ?limit to cap the count (1 to 1000; the default is all retained rows). Keyed and client-identified rows are never pruned. Responses carry Cache-Control: no-store.

NameInTypeRequiredDescription
idpathstringYesThe session id.
limitqueryintegerNoReturn at most this many receipts, newest first (1 to 1000). A cap, not a page size: there is no next page.
X-Hoody-CwdheaderstringNoPer-request working-directory scope.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override.
X-Hoody-RealmheaderstringNoPer-request realm selector (global or a 24-hex id).
realmquerystringNoPer-request realm selector (query alias of X-Hoody-Realm, read when the header is absent or empty).
X-Hoody-ComputerheaderstringNoPer-request bound remote computer (omitted = local). Rejected (400) on routes with no computer dimension.
{
"session_id": "sess-9f2c4e1ab07d3355",
"turns": [
{
"turn_id": "turn-9f2c4e1ab07d3355",
"job_id": "job-9f2c4e1ab07d3355",
"state": "completed",
"outcome": "completed",
"accepted_at": "2025-04-12T14:32:11Z",
"terminal_at": "2025-04-12T14:33:02Z",
"result_url": "/api/v1/agent/sessions/sess-9f2c4e1ab07d3355/turns/turn-9f2c4e1ab07d3355",
"stream_url": "/api/v1/agent/sessions/sess-9f2c4e1ab07d3355/stream",
"notices": []
},
{
"turn_id": "turn-3a2f1e0d9c8b7a6b",
"job_id": "job-3a2f1e0d9c8b7a6b",
"state": "failed",
"outcome": "failed",
"error_code": "no_credentials",
"accepted_at": "2025-04-12T14:18:47Z",
"terminal_at": "2025-04-12T14:19:01Z",
"result_url": "/api/v1/agent/sessions/sess-9f2c4e1ab07d3355/turns/turn-3a2f1e0d9c8b7a6b",
"stream_url": "/api/v1/agent/sessions/sess-9f2c4e1ab07d3355/stream",
"notices": []
}
]
}
import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' });
// Most recent 50 receipts.
const recent = await client.agent.sessions.turns.list('sess-9f2c4e1ab07d3355', { limit: 50 });
const turns = recent.data.turns;
// All retained receipts.
const all = await client.agent.sessions.turns.list('sess-9f2c4e1ab07d3355');
Terminal window
curl -X GET "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/sessions/sess-9f2c4e1ab07d3355/turns?limit=50"

GET /api/v1/agent/sessions/{id}/turns/{turn_id}

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

Returns the durable record of a turn: state, terminal outcome, error_code once terminal, and effects_may_have_occurred, which is true conservatively for every unfinished turn recovered as interrupted, even one that was only accepted, has no recorded tool calls, or was waiting for approval; it does not prove that a tool ran or an external effect occurred. Works for a live or dormant session. A turn the ledger never recorded returns 404 turn_not_found. Responses carry Cache-Control: no-store.

The state field is one of accepted, dispatched, completed, failed, cancelled, or interrupted. outcome and error_code are absent until the turn is terminal.

NameInTypeRequiredDescription
idpathstringYesThe session id.
turn_idpathstringYesThe turn id.
X-Hoody-CwdheaderstringNoPer-request working-directory scope.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override.
X-Hoody-RealmheaderstringNoPer-request realm selector (global or a 24-hex id).
realmquerystringNoPer-request realm selector (query alias of X-Hoody-Realm, read when the header is absent or empty).
X-Hoody-ComputerheaderstringNoPer-request bound remote computer (omitted = local). Rejected (400) on routes with no computer dimension.
{
"turn_id": "turn-9f2c4e1ab07d3355",
"job_id": "job-9f2c4e1ab07d3355",
"state": "completed",
"outcome": "completed",
"accepted_at": "2025-04-12T14:32:11Z",
"terminal_at": "2025-04-12T14:33:02Z",
"result_url": "/api/v1/agent/sessions/sess-9f2c4e1ab07d3355/turns/turn-9f2c4e1ab07d3355",
"stream_url": "/api/v1/agent/sessions/sess-9f2c4e1ab07d3355/stream",
"notices": []
}
import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' });
const receipt = await client.agent.sessions.turns.get('sess-9f2c4e1ab07d3355', 'turn-9f2c4e1ab07d3355');
Terminal window
curl -X GET "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/sessions/sess-9f2c4e1ab07d3355/turns/turn-9f2c4e1ab07d3355"

GET /api/v1/agent/sessions/{id}/turns/by-key/{key}

Section titled “GET /api/v1/agent/sessions/{id}/turns/by-key/{key}”

Returns the durable receipt of the turn a keyed POST /api/v1/agent/sessions/{id}/turns or POST /api/v1/agent/sessions/{id}/messages admitted, by its key: the same record GET /api/v1/agent/sessions/{id}/turns/{turn_id} returns. {key} is the Idempotency-Key the request was sent with (1 to 255 printable ASCII, no whitespace; URL-encode it). Works for a live or dormant session; reads never admit anything. A 404 turn_not_found with details.retired false proves nothing (the turn may still be on its way); POST /api/v1/agent/sessions/{id}/turns/by-key/{key}/retire settles it. Responses carry Cache-Control: no-store.

NameInTypeRequiredDescription
idpathstringYesThe session id.
keypathstringYesThe key.
X-Hoody-CwdheaderstringNoPer-request working-directory scope: the .hoody project layer / record cwd / tool+workflow cwd. Required by routes that resolve a cwd (e.g. POST /api/v1/agent/todos; createTodo also accepts a body cwd). The value must be UTF-8: other bytes (a non-ASCII path sent as Latin-1) are refused 400 bad_request.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override selecting which on-disk .hoody install a stateless read/write resolves against. The value must be UTF-8: other bytes are refused 400 bad_request.
X-Hoody-RealmheaderstringNoPer-request realm selector: “global” (not tied to a realm) or a 24-hex realm id (also accepted as ?realm=). On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.
realmquerystringNoPer-request realm selector, the in:query alias of the X-Hoody-Realm header (read when the header is absent or empty): “global” (not tied to a realm) or a 24-hex realm id. On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.
X-Hoody-ComputerheaderstringNoPer-request bound remote computer (omitted = local). Rejected (400) on routes with no computer dimension.

This endpoint takes no request body.

{
"turn_id": "turn-9f2c4e1ab07d3355",
"job_id": "job-9f2c4e1ab07d3355",
"state": "completed",
"outcome": "completed",
"accepted_at": "2025-04-12T14:32:11Z",
"terminal_at": "2025-04-12T14:33:02Z",
"result_url": "/api/v1/agent/sessions/sess-9f2c4e1ab07d3355/turns/turn-9f2c4e1ab07d3355",
"stream_url": "/api/v1/agent/sessions/sess-9f2c4e1ab07d3355/stream",
"notices": []
}

state is one of accepted, dispatched, completed, failed, cancelled, or interrupted. outcome and error_code are absent until the turn is terminal.

import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' });
const receipt = await client.agent.sessions.turns.getByKey('sess-9f2c4e1ab07d3355', '01HX5G2EXAMPLE1234567890AB');
const state = receipt.data.state;
Terminal window
curl -X GET "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/sessions/sess-9f2c4e1ab07d3355/turns/by-key/01HX5G2EXAMPLE1234567890AB"

POST /api/v1/agent/sessions/{id}/turns/by-key/{key}/retire

Section titled “POST /api/v1/agent/sessions/{id}/turns/by-key/{key}/retire”

Settles a keyed turn whose answer was lost. {key} is the Idempotency-Key the request was sent with (1 to 255 printable ASCII, no whitespace; URL-encode it). A key that admitted a turn answers retired false, admitted "true" and the turn’s receipt. Otherwise the key is retired durably on this session: retired true, admitted "false", and a turn sent with it earlier and delivered later is refused 409 turn_key_retired; retiring it again answers the same. The session must be live: a dormant one answers 503 (unknown) until it is attached. A 503 is unknown: nothing is proven, retire again after Retry-After. 409 turn_fences_exhausted: the key was NOT retired, so a delayed turn sent with it can still be admitted; never send a replacement. A retire request never runs the original turn, but a turn already admitted with the key may have run or may still run. The request has no body.

NameInTypeRequiredDescription
idpathstringYesThe session id.
keypathstringYesThe key.
X-Hoody-CwdheaderstringNoPer-request working-directory scope: the .hoody project layer / record cwd / tool+workflow cwd. Required by routes that resolve a cwd (e.g. POST /api/v1/agent/todos; createTodo also accepts a body cwd). The value must be UTF-8: other bytes (a non-ASCII path sent as Latin-1) are refused 400 bad_request.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override selecting which on-disk .hoody install a stateless read/write resolves against. The value must be UTF-8: other bytes are refused 400 bad_request.
X-Hoody-RealmheaderstringNoPer-request realm selector: “global” (not tied to a realm) or a 24-hex realm id (also accepted as ?realm=). On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.
realmquerystringNoPer-request realm selector, the in:query alias of the X-Hoody-Realm header (read when the header is absent or empty): “global” (not tied to a realm) or a 24-hex realm id. On a session route it names the realm the session is looked up in: a session in another realm, or in a realm this login does not serve, is 404 not_found. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes, and for any other realm on an agent pinned to one realm.
X-Hoody-ComputerheaderstringNoPer-request bound remote computer (omitted = local). Rejected (400) on routes with no computer dimension.

This endpoint takes no request body.

{
"admitted": "false",
"retired": true
}

With admitted "true", the answer also carries turn, the receipt of the turn the key admitted. With admitted "false", nothing was admitted with the key and nothing can be from now on. "unknown" means a turn sent with the key earlier may have been admitted and run.

import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com' });
const settled = await client.agent.sessions.turns.retireKey('sess-9f2c4e1ab07d3355', '01HX5G2EXAMPLE1234567890AB');
const retired = settled.data.retired;
Terminal window
curl -X POST "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/sessions/sess-9f2c4e1ab07d3355/turns/by-key/01HX5G2EXAMPLE1234567890AB/retire"