Agent: Session turns
Section titled “Agent: Session turns”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.
Dispatching a turn
Section titled “Dispatching a turn”Four endpoints dispatch a turn, each with a different posture. Pick by what your caller can do, not by what feels familiar.
| Endpoint | Blocks until done | Streams events | Retry-safe with Idempotency-Key |
|---|---|---|---|
POST /api/v1/agent/sessions/{id}/messages | No (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:sync | Until the turn ends, a gate needs a person, or 290 s (then 503 with details.turn_running) | No | Yes (returns the same outcome with duplicate: true, or pending_turn while it still runs) |
POST /api/v1/agent/sessions/{id}/prompt:stream | No (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}/turns | No (returns 202 receipt once admitted) | No (observe the session stream separately) | Yes (returns the same receipt for the same key) |
POST /api/v1/agent/sessions/{id}/messages
Section titled “POST /api/v1/agent/sessions/{id}/messages”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.
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 / tool+workflow cwd. Required by routes that resolve a cwd (e.g. POST /todos; createTodo also accepts a body cwd). |
X-Hoody-Config-Dir | header | string | No | Per-request --config-dir override selecting which on-disk .hoody install a stateless read/write resolves against. |
X-Hoody-Realm | header | string | No | Per-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. |
realm | query | string | No | Per-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-Key | header | string | No | Opaque 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-Computer | header | string | No | Per-request bound remote computer (omitted = local). Rejected (400) on routes with no computer dimension. |
Request body
Section titled “Request body”| Field | Type | Required | Description |
|---|---|---|---|
text | string | Yes | Required (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_mode | string | No | Optional 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_scope | string | No | Optional 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. |
attachments | array | No | Optional 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. |
Responses
Section titled “Responses”Media type: application/json
{ "job_id": "job-9f2c4e1ab07d3355", "session_id": "sess-9f2c4e1ab07d3355", "turn_id": "turn-9f2c4e1ab07d3355"}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. |
empty_prompt | Empty prompt | The turn has no text (empty or only whitespace) and no attachments, so there is nothing to send to the model. No turn was started. details.field is “text”. | Send the message text, or at least one image attachment. |
invalid_tool_mode | Invalid tool mode | tool_mode is not standard or orchestrator (details.field is “tool_mode”), or a turn names a tool mode other than the one the session’s first turn fixed (or, before that turn runs, the one an earlier queued turn carries). Nothing was started. | Send standard or orchestrator, or omit tool_mode. A later turn sends the session’s own tool mode or omits it. |
invalid_dir_scope | Invalid directory scope | dir_scope is not home or full (details.field is “dir_scope”), or a turn names a directory scope other than the one the session’s first turn fixed (or, before that turn runs, the one an earlier queued turn carries). Nothing was started. | Send home or full, or omit dir_scope. A later turn sends the session’s own scope or omits it. |
invalid_realm | Invalid realm selector | The realm selector is malformed (not ""/“global”/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 …. |
realm_not_allowed | Realm not allowed for this login | The agent is logged in with a token limited to some realms (GET /hoody/auth/status lists them in realm_ids), and this session’s realm is not one of them, or is the global scope (a session restored from before the login, or a realm the login was narrowed away from). The session can still be read; nothing was run. | Continue in a session of a realm the login serves, or log the agent in with a token that covers this session’s realm. |
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": "gate_parked", "message": "a gate is parked on this session", "details": { "pending_gate": { "generation": 3, "id": "gate-9f2c4e1ab07d3355-3", "type": "confirm" } }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
gate_parked | Gate parked | A confirm or question gate is parked on this session, so a new turn/workflow run is refused until it is answered. The parked gate is surfaced under details.pending_gate. | Answer the parked gate (/confirm or /answer, echoing its gate_id) and retry; read it from details.pending_gate, from pending_gate on GET /sessions/{id}, or from the gate field of the stream frame that parked it. |
turn_in_flight | Turn in flight | A turn is already running on this session; the single serial turn slot is occupied, so a new turn/workflow run is refused. | Wait for the running turn to finish (observe agent_done on the session stream), then retry. |
turn_key_retired | Idempotency key retired | The Idempotency-Key was retired on this session, and from now on it admits no turn. details.admitted repeats what was recorded when the key was retired: “false” means no turn was admitted with the key; “unknown” means a turn sent with it earlier may have been admitted and run. Nothing beyond details.admitted is guaranteed. | Read details.admitted. If it is “false”, the turn may be sent under a new Idempotency-Key. If it is “unknown”, check whether the earlier turn took effect before sending it again. |
Media type: application/json
{ "code": "payload_too_large", "message": "request body exceeds the configured size limit"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
payload_too_large | Payload too large | The request body exceeds the size limit (default 8 MiB). | Reduce the request body below the configured limit; split a large payload into smaller requests. |
Media type: application/json
{ "code": "idempotency_key_reused", "message": "this idempotency key was used for a different request", "details": { "turn_id": "turn-3f2a9c1e-12" }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
idempotency_key_reused | Idempotency key reused | The Idempotency-Key was already used for a DIFFERENT request on this session. A key binds to one request; reusing it for another is a client bug. details.turn_id names the turn the key admitted (GET /sessions/{id}/turns/{turn_id} reads it). | Use a fresh Idempotency-Key for a different request, or resend the identical request to get the original receipt. |
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 persistent, inspect the daemon logs. |
Media type: application/json
{ "code": "admission_unconfirmed", "message": "the daemon did not acknowledge the turn's admission within the wait", "details": { "result_url": "/api/v1/agent/sessions/sess-9f2c4e1ab07d3355/turns/turn-9f2c4e1ab07d3355", "turn_id": "turn-9f2c4e1ab07d3355" }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
service_unavailable | Service unavailable / Turn record unreadable | The daemon could not service the request (too busy, or a per-client stream concurrency cap was hit). The session’s turn record could not be read or made durable, so whether this Idempotency-Key admitted a turn is unknown: it may have been. | Honor Retry-After and retry with the same Idempotency-Key; never change the key, since the turn may already run. |
admission_unconfirmed | Admission unconfirmed | The turn was sent but the daemon’s admission receipt did not arrive within the wait. It may still have been accepted: details.turn_id and details.result_url name the turn to poll. | GET details.result_url; retry with the SAME Idempotency-Key only after it reports the turn was not recorded (404). |
admission_write_failed | Admission write failed | The daemon could not durably record the turn’s admission, so the turn was NOT run (fail-closed). | Retry; if it persists, check the daemon’s session store (disk and permissions). |
restriction_unknown | Login restriction unknown | The agent cannot read yet which realms its login may serve (GET /hoody/auth/status reports restriction “unknown”), so it runs no work in any session until it can. Nothing was run. | Retry after the restriction is readable. |
session_terminating | Session terminating | The session is shutting down, so this request was refused before anything was recorded for it. The refusal does not cover an earlier attempt with the same Idempotency-Key: that attempt may have been admitted and run. | Retry after the Retry-After delay with the same Idempotency-Key. If an earlier attempt with that key ended uncertain (a timeout or a lost connection), read GET /sessions/{id}/turns/{turn_id} for it first. If the session has closed meanwhile, attach it again first (POST /sessions with attach). |
SDK usage
Section titled “SDK usage”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;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).
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | The session id. |
policy | query | string | No | auto_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-Policy | header | string | No | Confirm-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-Cwd | header | string | No | Per-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-Dir | header | string | No | Per-request --config-dir override selecting which on-disk .hoody install a stateless read/write resolves against. |
X-Hoody-Realm | header | string | No | Per-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. |
realm | query | string | No | Per-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-Key | header | string | No | Opaque 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-Computer | header | string | No | Per-request bound remote computer (omitted = local). Rejected (400) on routes with no computer dimension. |
Request body
Section titled “Request body”| Field | Type | Required | Description |
|---|---|---|---|
text | string | Yes | Required (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_mode | string | No | Optional 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_scope | string | No | Optional 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. |
attachments | array | No | Optional 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. |
Responses
Section titled “Responses”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.
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. |
empty_prompt | Empty prompt | The turn has no text (empty or only whitespace) and no attachments, so there is nothing to send to the model. No turn was started. details.field is “text”. | Send the message text, or at least one image attachment. |
invalid_tool_mode | Invalid tool mode | tool_mode is not standard or orchestrator (details.field is “tool_mode”), or a turn names a tool mode other than the one the session’s first turn fixed (or, before that turn runs, the one an earlier queued turn carries). Nothing was started. | Send standard or orchestrator, or omit tool_mode. A later turn sends the session’s own tool mode or omits it. |
invalid_dir_scope | Invalid directory scope | dir_scope is not home or full (details.field is “dir_scope”), or a turn names a directory scope other than the one the session’s first turn fixed (or, before that turn runs, the one an earlier queued turn carries). Nothing was started. | Send home or full, or omit dir_scope. A later turn sends the session’s own scope or omits it. |
invalid_realm | Invalid realm selector | The realm selector is malformed (not ""/“global”/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 …. |
realm_not_allowed | Realm not allowed for this login | The agent is logged in with a token limited to some realms (GET /hoody/auth/status lists them in realm_ids), and this session’s realm is not one of them, or is the global scope (a session restored from before the login, or a realm the login was narrowed away from). The session can still be read; nothing was run. | Continue in a session of a realm the login serves, or log the agent in with a token that covers this session’s realm. |
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": "turn_in_flight", "message": "a turn is already running on this session"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
turn_in_flight | Turn in flight | A turn is already running on this session; the single serial turn slot is occupied, so a new turn/workflow run is refused. | Wait for the running turn to finish (observe agent_done on the session stream), then retry. |
approval_policy_active | Approval policy active | This session requires an explicit decision on every action, so an automatic-answer alias (the auto_approve gate posture, arming YOLO, an allow rule) is refused. | Answer each gate through POST /sessions/{id}/confirm, or change the policy first (PUT /sessions/{id}/approval) if it is not locked. |
turn_key_retired | Idempotency key retired | The Idempotency-Key was retired on this session, and from now on it admits no turn. details.admitted repeats what was recorded when the key was retired: “false” means no turn was admitted with the key; “unknown” means a turn sent with it earlier may have been admitted and run. Nothing beyond details.admitted is guaranteed. | Read details.admitted. If it is “false”, the turn may be sent under a new Idempotency-Key. If it is “unknown”, check whether the earlier turn took effect before sending it again. |
Media type: application/json
{ "code": "payload_too_large", "message": "request body exceeds the configured size limit"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
payload_too_large | Payload too large | The request body exceeds the size limit (default 8 MiB). | Reduce the request body below the configured limit; split a large payload into smaller requests. |
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. | 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 persistent, inspect the daemon logs. |
Media type: application/json
{ "code": "service_unavailable", "message": "prompt:sync timed out; the turn keeps running and a gate it parks waits for /confirm, /answer or /plan \u2014 observe the stream or poll GET /sessions/{id}/turns/{turn_id}", "details": { "turn_id": "turn-9f2c4e1ab07d3355", "turn_running": true }}A 290 s timeout: the turn is still running, not cancelled. Follow it on the session stream or with GET /sessions/{id}/turns/{turn_id}. Under auto_approve, details also carries "auto_approve": "until_turn_end" and the message says auto_approve stays on for the turn’s confirm gates instead.
| Error Code | Title | Description | Resolution |
|---|---|---|---|
service_unavailable | Service unavailable / Turn record unreadable | The daemon could not service the request (too busy, or a per-client stream concurrency cap was hit). The session’s turn record could not be read or made durable, so whether this Idempotency-Key admitted a turn is unknown: it may have been. It is also the answer when the 290 s prompt-sync wait elapsed with the turn still running. | Honor Retry-After and retry with the same Idempotency-Key; never change the key, since the turn may already run. For a 290 s timeout, follow the named turn rather than retrying. |
admission_unconfirmed | Admission unconfirmed | The turn was sent but the daemon’s admission receipt did not arrive within the wait. It may still have been accepted: details.turn_id / details.result_url name the turn to poll. The gateway keeps the turn slot and job rather than inventing or discarding acceptance. | GET details.result_url; retry with the SAME Idempotency-Key only after it reports the turn was not recorded (404). |
admission_write_failed | Admission write failed | The daemon could not durably record the turn’s admission, so the turn was NOT run (fail-closed: nothing runs unrecorded). | Retry; if it persists, check the daemon’s session store (disk / permissions). |
restriction_unknown | Login restriction unknown | The agent cannot read yet which realms its login may serve (GET /hoody/auth/status reports restriction “unknown”), so it runs no work in any session until it can. Nothing was run. | Retry after the restriction is readable. |
session_terminating | Session terminating | The session is shutting down, so this request was refused before anything was recorded for it. The refusal does not cover an earlier attempt with the same Idempotency-Key: that attempt may have been admitted and run. | Retry after the Retry-After delay with the same Idempotency-Key. If an earlier attempt with that key ended uncertain (a timeout or a lost connection), read GET /sessions/{id}/turns/{turn_id} for it first. If the session has closed meanwhile, attach it again first (POST /sessions with attach). |
Media type: application/json
{ "code": "idempotency_key_reused", "message": "this idempotency key was used for a different request", "details": { "turn_id": "turn-3f2a9c1e-12" }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
idempotency_key_reused | Idempotency key reused | The Idempotency-Key was already used for a DIFFERENT request on this session. A key binds to one request; reusing it for another is a client bug. details.turn_id names the turn the key admitted (GET /sessions/{id}/turns/{turn_id} reads it). | Use a fresh Idempotency-Key for a different request, or resend the identical request to get the original receipt. |
SDK usage
Section titled “SDK usage”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.'});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.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | The session id. |
policy | query | string | No | auto_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-Policy | header | string | No | Confirm-gate posture: auto_approve adopts the headless auto-answer posture. Any other value is rejected with 400. |
X-Hoody-Cwd | header | string | No | Per-request working-directory scope. |
X-Hoody-Config-Dir | header | string | No | Per-request --config-dir override. |
X-Hoody-Realm | header | string | No | Per-request realm selector (global or a 24-hex id). |
realm | query | string | No | Per-request realm selector (query alias of X-Hoody-Realm, read when the header is absent or empty). |
Idempotency-Key | header | string | No | Opaque 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-Computer | header | string | No | Per-request bound remote computer (omitted = local). Rejected (400) on routes with no computer dimension. |
Request body
Section titled “Request body”| Field | Type | Required | Description |
|---|---|---|---|
text | string | Yes | Required (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_mode | string | No | Optional 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_scope | string | No | Optional 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. |
attachments | array | No | Optional 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. |
Responses
Section titled “Responses”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_boundarydata: {"max_seq":41,"incarnation":"0123456789abcdef0123456789abcdef","turn_id":"turn-9f2c4e1ab07d3355"}
event: stream_chunkid: 42data: {"seq":42,"incarnation":"0123456789abcdef0123456789abcdef","turn_id":"turn-9f2c4e1ab07d3355","event":{"type":"event.stream_chunk","data":{"text":"I'll look that up.\n"}}}
event: tool_callid: 43data: {"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_doneid: 44data: {"seq":44,"incarnation":"0123456789abcdef0123456789abcdef","turn_id":"turn-9f2c4e1ab07d3355","event":{"type":"event.agent_done","data":{"turn_id":"turn-9f2c4e1ab07d3355","outcome":"completed"}}}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. |
empty_prompt | Empty prompt | The turn has no text (empty or only whitespace) and no attachments, so there is nothing to send to the model. No turn was started. details.field is “text”. | Send the message text, or at least one image attachment. |
invalid_tool_mode | Invalid tool mode | tool_mode is not standard or orchestrator (details.field is “tool_mode”), or a turn names a tool mode other than the one the session’s first turn fixed (or, before that turn runs, the one an earlier queued turn carries). Nothing was started. | Send standard or orchestrator, or omit tool_mode. A later turn sends the session’s own tool mode or omits it. |
invalid_dir_scope | Invalid directory scope | dir_scope is not home or full (details.field is “dir_scope”), or a turn names a directory scope other than the one the session’s first turn fixed (or, before that turn runs, the one an earlier queued turn carries). Nothing was started. | Send home or full, or omit dir_scope. A later turn sends the session’s own scope or omits it. |
invalid_realm | Invalid realm selector | The realm selector is malformed (not ""/“global”/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 …. |
realm_not_allowed | Realm not allowed for this login | The agent is logged in with a token limited to some realms (GET /hoody/auth/status lists them in realm_ids), and this session’s realm is not one of them, or is the global scope (a session restored from before the login, or a realm the login was narrowed away from). The session can still be read; nothing was run. | Continue in a session of a realm the login serves, or log the agent in with a token that covers this session’s realm. |
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": "turn_in_flight", "message": "a turn is already running on this session"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
gate_parked | Gate parked | A confirm or question gate is parked on this session, so a new turn is refused until it is answered. | Answer the parked gate and retry. |
turn_in_flight | Turn in flight | A turn is already running on this session; the single serial turn slot is occupied. | Wait for the running turn to finish, then retry. |
approval_policy_active | Approval policy active | This session requires an explicit decision on every action, so auto_approve is refused. | Answer each gate, or change the policy first if it is not locked. |
replay_unavailable | Replay unavailable | The Idempotency-Key names a turn that already ran (details.turn is its receipt); prompt:stream cannot re-stream the original events and never re-runs the turn. | Read details.turn or GET details.turn.result_url for the outcome, or attach GET /sessions/{id}/stream with a cursor you hold. |
turn_key_retired | Idempotency key retired | The Idempotency-Key was retired on this session, and from now on it admits no turn. details.admitted repeats what was recorded when the key was retired: “false” means no turn was admitted with the key; “unknown” means a turn sent with it earlier may have been admitted and run. Nothing beyond details.admitted is guaranteed. | Read details.admitted. If it is “false”, the turn may be sent under a new Idempotency-Key. If it is “unknown”, check whether the earlier turn took effect before sending it again. |
Media type: application/json
{ "code": "payload_too_large", "message": "request body exceeds the configured size limit"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
payload_too_large | Payload too large | The request body exceeds the size limit (default 8 MiB). | Reduce the request body below the configured limit; split a large payload into smaller requests. |
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 | A transport error occurred before SSE opened. | Retry; if persistent, inspect the daemon logs. |
Media type: application/json
{ "code": "admission_unconfirmed", "message": "the daemon did not acknowledge the turn's admission within the wait", "details": { "result_url": "/api/v1/agent/sessions/sess-9f2c4e1ab07d3355/turns/turn-9f2c4e1ab07d3355", "turn_id": "turn-9f2c4e1ab07d3355" }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
service_unavailable | Service unavailable / Turn record unreadable | The daemon could not service the request (too busy, or a per-client stream concurrency cap was hit). The session’s turn record could not be read or made durable, so whether this Idempotency-Key admitted a turn is unknown: it may have been. | Honor Retry-After and retry with the same Idempotency-Key; never change the key, since the turn may already run. |
admission_unconfirmed | Admission unconfirmed | The turn was sent but the daemon’s admission receipt did not arrive within the wait. It may still have been accepted. | GET details.result_url; retry with the SAME Idempotency-Key only after it reports the turn was not recorded (404). |
admission_write_failed | Admission write failed | The daemon could not durably record the turn’s admission, so the turn was NOT run (fail-closed). | Retry; if it persists, check the daemon’s session store (disk and permissions). |
restriction_unknown | Login restriction unknown | The agent cannot read yet which realms its login may serve (GET /hoody/auth/status reports restriction “unknown”), so it runs no work in any session until it can. Nothing was run. | Retry after the restriction is readable. |
session_terminating | Session terminating | The session is shutting down, so this request was refused before anything was recorded for it. The refusal does not cover an earlier attempt with the same Idempotency-Key: that attempt may have been admitted and run. | Retry after the Retry-After delay with the same Idempotency-Key. If an earlier attempt with that key ended uncertain (a timeout or a lost connection), read GET /sessions/{id}/turns/{turn_id} for it first. If the session has closed meanwhile, attach it again first (POST /sessions with attach). |
Media type: application/json
{ "code": "idempotency_key_reused", "message": "this idempotency key was used for a different request", "details": { "turn_id": "turn-3f2a9c1e-12" }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
idempotency_key_reused | Idempotency key reused | The Idempotency-Key was already used for a DIFFERENT request on this session. A key binds to one request; reusing it for another is a client bug. details.turn_id names the turn the key admitted (GET /sessions/{id}/turns/{turn_id} reads it). | Use a fresh Idempotency-Key for a different request, or resend the identical request to get the original receipt. |
SDK usage
Section titled “SDK usage”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'});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=" }] }'POST /api/v1/agent/sessions/{id}/turns
Section titled “POST /api/v1/agent/sessions/{id}/turns”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.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | The session id. |
Idempotency-Key | header | string | No | Opaque 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-Cwd | header | string | No | Per-request working-directory scope. |
X-Hoody-Config-Dir | header | string | No | Per-request --config-dir override. |
X-Hoody-Realm | header | string | No | Per-request realm selector (global or a 24-hex id). |
realm | query | string | No | Per-request realm selector (query alias of X-Hoody-Realm, read when the header is absent or empty). |
policy | query | string | No | auto_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-Policy | header | string | No | Confirm-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-Computer | header | string | No | Per-request bound remote computer (omitted = local). Rejected (400) on routes with no computer dimension. |
Request body
Section titled “Request body”| Field | Type | Required | Description |
|---|---|---|---|
text | string | Yes | Required (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_mode | string | No | Optional 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_scope | string | No | Optional 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. |
attachments | array | No | Optional 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. |
Responses
Section titled “Responses”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": []}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. |
empty_prompt | Empty prompt | The turn has no text (empty or only whitespace) and no attachments, so there is nothing to send to the model. No turn was started. details.field is “text”. | Send the message text, or at least one image attachment. |
invalid_tool_mode | Invalid tool mode | tool_mode is not standard or orchestrator (details.field is “tool_mode”), or a turn names a tool mode other than the one the session’s first turn fixed (or, before that turn runs, the one an earlier queued turn carries). Nothing was started. | Send standard or orchestrator, or omit tool_mode. A later turn sends the session’s own tool mode or omits it. |
invalid_dir_scope | Invalid directory scope | dir_scope is not home or full (details.field is “dir_scope”), or a turn names a directory scope other than the one the session’s first turn fixed (or, before that turn runs, the one an earlier queued turn carries). Nothing was started. | Send home or full, or omit dir_scope. A later turn sends the session’s own scope or omits it. |
invalid_realm | Invalid realm selector | The realm selector is malformed (not ""/“global”/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 …. |
realm_not_allowed | Realm not allowed for this login | The agent is logged in with a token limited to some realms (GET /hoody/auth/status lists them in realm_ids), and this session’s realm is not one of them, or is the global scope (a session restored from before the login, or a realm the login was narrowed away from). The session can still be read; nothing was run. | Continue in a session of a realm the login serves, or log the agent in with a token that covers this session’s realm. |
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": "turn_in_flight", "message": "a turn is already running on this session"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
gate_parked | Gate parked | A confirm or question gate is parked on this session, so a new turn is refused until it is answered. | Answer the parked gate and retry. |
turn_in_flight | Turn in flight | A turn is already running on this session; the single serial turn slot is occupied. | Wait for the running turn to finish, then retry. |
turn_key_retired | Idempotency key retired | The Idempotency-Key was retired on this session, and from now on it admits no turn. details.admitted repeats what was recorded when the key was retired: “false” means no turn was admitted with the key; “unknown” means a turn sent with it earlier may have been admitted and run. Nothing beyond details.admitted is guaranteed. | Read details.admitted. If it is “false”, the turn may be sent under a new Idempotency-Key. If it is “unknown”, check whether the earlier turn took effect before sending it again. |
approval_policy_active | Approval policy active | This session requires an explicit decision on every action, so an automatic-answer alias (the auto_approve gate posture, arming YOLO, an allow rule) is refused. | Answer each gate through POST /api/v1/agent/sessions/{id}/confirm, or change the policy first (PUT /api/v1/agent/sessions/{id}/approval) if it is not locked. |
Media type: application/json
{ "code": "payload_too_large", "message": "request body exceeds the configured size limit"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
payload_too_large | Payload too large | The request body exceeds the size limit (default 8 MiB). | Reduce the request body below the configured limit; split a large payload into smaller requests. |
Media type: application/json
{ "code": "idempotency_key_reused", "message": "this idempotency key was used for a different request", "details": { "turn_id": "turn-3f2a9c1e-12" }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
idempotency_key_reused | Idempotency key reused | The Idempotency-Key was already used for a DIFFERENT request on this session. A key binds to one request. | Use a fresh Idempotency-Key for a different request, or resend the identical request to get the original receipt. |
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 persistent, inspect the daemon logs. |
Media type: application/json
{ "code": "service_unavailable", "message": "the session's turn record could not be read; retry with the same idempotency key"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
service_unavailable | Service unavailable / Turn record unreadable | The daemon could not service the request (too busy, or a per-client stream concurrency cap was hit). The session’s turn record could not be read or made durable, so whether this Idempotency-Key admitted a turn is unknown: it may have been. | Honor Retry-After and retry with the same Idempotency-Key; never change the key, since the turn may already run. |
admission_unconfirmed | Admission unconfirmed | The turn was sent but the daemon’s admission receipt did not arrive within the wait. It may still have been accepted: details.turn_id / details.result_url name the turn to poll. The gateway keeps the turn slot and job rather than inventing or discarding acceptance. | GET details.result_url; retry with the SAME Idempotency-Key only after it reports the turn was not recorded (404). |
admission_write_failed | Admission write failed | The daemon could not durably record the turn’s admission, so the turn was NOT run (fail-closed: nothing runs unrecorded). | Retry; if it persists, check the daemon’s session store (disk / permissions). |
restriction_unknown | Login restriction unknown | The agent cannot read yet which realms its login may serve (GET /hoody/auth/status reports restriction “unknown”), so it runs no work in any session until it can. Nothing was run. | Retry after the restriction is readable. |
session_terminating | Session terminating | The session is shutting down, so this request was refused before anything was recorded for it. The refusal does not cover an earlier attempt with the same Idempotency-Key: that attempt may have been admitted and run. | Retry after the Retry-After delay with the same Idempotency-Key. If an earlier attempt with that key ended uncertain (a timeout or a lost connection), read GET /sessions/{id}/turns/{turn_id} for it first. If the session has closed meanwhile, attach it again first (POST /sessions with attach). |
SDK usage
Section titled “SDK usage”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'});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." }'Cancelling a turn
Section titled “Cancelling a turn”POST /api/v1/agent/sessions/{id}/cancel
Section titled “POST /api/v1/agent/sessions/{id}/cancel”Cancels the active turn on the session (the historical “Esc” behaviour), or, when a turn_id is supplied, cancels only that named turn.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | The session id. |
turn_id | query | string | No | Cancel only this turn (alternative to the body field). |
X-Hoody-Cwd | header | string | No | Per-request working-directory scope. |
X-Hoody-Config-Dir | header | string | No | Per-request --config-dir override. |
X-Hoody-Realm | header | string | No | Per-request realm selector (global or a 24-hex id). |
realm | query | string | No | Per-request realm selector (query alias of X-Hoody-Realm, read when the header is absent or empty). |
X-Hoody-Computer | header | string | No | Per-request bound remote computer (omitted = local). Rejected (400) on routes with no computer dimension. |
Request body
Section titled “Request body”| Field | Type | Required | Description |
|---|---|---|---|
turn_id | string | No | The turn to cancel, as returned when it was dispatched. Cancels only that turn. Omit (or send {}) to cancel whatever is running. |
Responses
Section titled “Responses”{ "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.
{ "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”/a 24-hex id). | Pass a valid realm selector. |
{ "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 …. |
{ "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. |
{ "code": "payload_too_large", "message": "request body exceeds the configured size limit"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
payload_too_large | Payload too large | The request body exceeds the size limit (default 8 MiB). | Reduce the request body below the configured limit; split a large payload into smaller requests. |
{ "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. | Honor the Retry-After header and retry; reduce the request rate. |
{ "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 persistent, inspect the daemon logs. |
{ "code": "service_unavailable", "message": "service unavailable"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
service_unavailable | Service unavailable | The daemon could not service the request (too busy, or a per-client stream concurrency cap was hit). | Honor Retry-After and retry. |
SDK usage
Section titled “SDK usage”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', {});# 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).
POST /api/v1/agent/sessions/{id}/commands
Section titled “POST /api/v1/agent/sessions/{id}/commands”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).
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | The session id. |
Idempotency-Key | header | string | Yes | Retry 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-Cwd | header | string | No | Per-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-Dir | header | string | No | Per-request --config-dir override selecting which on-disk .hoody install a stateless read/write resolves against. |
X-Hoody-Realm | header | string | No | Per-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. |
realm | query | string | No | Per-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-Computer | header | string | No | Per-request bound remote computer (omitted = local). Rejected (400) on routes with no computer dimension. |
Request body
Section titled “Request body”| Field | Type | Required | Description |
|---|---|---|---|
kind | string | Yes | message, interrupt, or stop. |
text | string | No | The message text (message and interrupt: required, non-empty, at most 32 KiB). Delivered verbatim. A stop takes none. |
close | boolean | No | A stop only: close the session once its work is stopped. |
on_gate | string | No | A 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. |
order | integer | No | Optional, 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. |
from | object | No | Who sends it (kind enum: user, bot, delegate, system; optional id of at most 256 bytes). Attribution only, never authorization. |
trigger | string | No | What 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."}Responses
Section titled “Responses”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).
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 (for example, a missing Idempotency-Key, an empty text on a message or interrupt, or text larger than 32 KiB). | Correct the request body or headers. |
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”/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 |
|---|---|---|---|
realm_not_allowed | Realm not allowed for this login | The agent is logged in with a token limited to some realms (GET /hoody/auth/status lists them in realm_ids), and this session’s realm is not one of them, or is the global scope (a session restored from before the login, or a realm the login was narrowed away from). The session can still be read; nothing was run. | Continue in a session of a realm the login serves, or log the agent in with a token that covers this session’s realm. |
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": "session_closed", "message": "the session is being closed"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
session_closed | Session closed | The session is closed (not live), or a stop sent with close is closing it. Nothing was admitted. | Attach the session with POST /sessions (attach) and send the command again, or start another session. |
command_unsupported | Commands unsupported | This session does not take commands: a headless run or an internal session (a TODO run). Nothing was admitted. | Cancel it with POST /sessions/{id}/cancel instead. |
command_key_retired | Idempotency key retired | The Idempotency-Key was retired on this session, and from now on it admits no command. details.admitted repeats what was recorded when the key was retired: “false” means no command was admitted with the key; “unknown” means a command sent with it earlier may have been admitted and run. Nothing beyond details.admitted is guaranteed. | Read details.admitted. If it is “false”, the command may be sent under a new Idempotency-Key. If it is “unknown”, check whether the earlier command took effect before sending it again. |
Media type: application/json
{ "code": "payload_too_large", "message": "request body exceeds the configured size limit"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
payload_too_large | Payload too large | The request body exceeds the size limit (default 8 MiB). | Reduce the request body below the configured limit (default 8 MiB); split a large payload into smaller requests. |
Media type: application/json
{ "code": "idempotency_key_reused", "message": "the idempotency key was used for a different command (cmd_3f2a9c1e5b7d40a1c2e8f6d9)"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
idempotency_key_reused | Idempotency key reused | The Idempotency-Key was already used for a DIFFERENT command on this session (another kind, text, close, on_gate, order, from or trigger). Nothing was admitted. The message names the command the key admitted. | Use a fresh Idempotency-Key for a different command, or resend the identical command to get its receipt. |
Media type: application/json
{ "code": "command_queue_full", "message": "too much text is queued on this session; retry after event.command_committed"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
command_queue_full | Command queue full | The text of the commands still waiting on this session would pass 128 KiB with this one. Nothing was admitted. Retry-After says when to retry. | Wait for event.command_committed (the queued commands reached the session), then send again with the same Idempotency-Key. |
idempotency_keys_exhausted | Too many remembered keys | The session already remembers 4096 Idempotency-Keys (each one while its command waits and for 24 hours after the command settled). Nothing was admitted. A stop is never refused because of the remembered-key limit. | Send the command later, when older keys have expired. |
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 persistent, inspect the daemon logs. |
Media type: application/json
{ "code": "service_unavailable", "message": "the session's command record could not be read; retry with the same idempotency key"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
service_unavailable | Service unavailable / Command record unreadable | The daemon could not service the request (too busy, or a per-client stream concurrency cap was hit). The session’s command record could not be read or made durable, so whether a command was admitted with this Idempotency-Key is unknown: it may have been. Nothing is reported as missing. | Honor Retry-After and retry with the same Idempotency-Key; never change the key, since the command may already be admitted. |
restriction_unknown | Login restriction unknown | The agent cannot read yet which realms its login may serve (GET /hoody/auth/status reports restriction “unknown”), so it runs no work in any session until it can. Nothing was run. | Retry after the restriction is readable. |
admission_write_failed | Admission write failed | The agent could not record the command, so it was NOT admitted. | Retry with the same Idempotency-Key; if it persists, check the agent’s storage (disk space, permissions). |
admission_unconfirmed | Admission unconfirmed | The command was sent but the agent did not acknowledge it within the wait. It may have been admitted. | Resend the identical request with the same Idempotency-Key: if the command was admitted it answers the stored receipt (duplicate true), and nothing is admitted twice. |
SDK usage
Section titled “SDK usage”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'});# 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.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | The session id. |
command_id | path | string | Yes | The command id. |
X-Hoody-Cwd | header | string | No | Per-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-Dir | header | string | No | Per-request --config-dir override selecting which on-disk .hoody install a stateless read/write resolves against. |
X-Hoody-Realm | header | string | No | Per-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. |
realm | query | string | No | Per-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-Computer | header | string | No | Per-request bound remote computer (omitted = local). Rejected (400) on routes with no computer dimension. |
Responses
Section titled “Responses”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).
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”/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 command id is not for this session, or its receipt is no longer kept (the keep window is while the command waits and 24 hours after it settled). | Verify the path and identifier; resend the command if its keep window elapsed. |
Media type: application/json
{ "code": "session_closed", "message": "the session is being closed"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
session_closed | Session closed | The session is closed (not live), or a stop sent with close is closing it. Nothing was admitted. | Attach the session with POST /sessions (attach) and send the command again, or start another session. |
command_key_retired | Idempotency key retired | The Idempotency-Key was retired on this session, and from now on it admits no command. details.admitted repeats what was recorded when the key was retired: “false” means no command was admitted with the key; “unknown” means a command sent with it earlier may have been admitted and run. Nothing beyond details.admitted is guaranteed. | Read details.admitted. If it is “false”, the command may be sent under a new Idempotency-Key. If it is “unknown”, check whether the earlier command took effect before sending it again. |
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. | 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 persistent, 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 |
|---|---|---|---|
service_unavailable | Service unavailable / Command record unreadable | The daemon could not service the request (too busy, or a per-client stream concurrency cap was hit). The session’s command record could not be read or made durable, so whether a command was admitted with this Idempotency-Key is unknown: it may have been. Nothing is reported as missing. | Honor Retry-After and retry with the same Idempotency-Key; never change the key, since the command may already be admitted. |
restriction_unknown | Login restriction unknown | The agent cannot read yet which realms its login may serve (GET /hoody/auth/status reports restriction “unknown”), so it refuses realm-scoped requests until it can. Nothing was read or changed. | Retry after the restriction is readable. |
SDK usage
Section titled “SDK usage”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;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.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | The session id. |
command_id | path | string | Yes | The command id. |
X-Hoody-Cwd | header | string | No | Per-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-Dir | header | string | No | Per-request --config-dir override selecting which on-disk .hoody install a stateless read/write resolves against. The value must be UTF-8. |
X-Hoody-Computer | header | string | No | Per-request bound remote computer (omitted = local). |
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 the session is looked up in. |
realm | query | string | No | Per-request realm selector, the query alias of X-Hoody-Realm, read when the header is absent or empty. |
This endpoint takes no request body.
Responses
Section titled “Responses”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.
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 path, query parameters, or headers. |
realm_scope_unsupported | Realm scope unsupported | A per-request scope header this route does not take, or a realm other than the one an agent is pinned to. | Omit the header, or name the realm the agent is pinned to. |
invalid_realm | Invalid realm selector | The realm selector is malformed. | Pass global or a 24-hex realm id. |
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 command id was never admitted by this session, or its receipt is no longer kept. | Verify the command id. Do not resend the message until the withdrawal outcome is known. |
Media type: application/json
{ "code": "command_not_withdrawable", "message": "only a message can be withdrawn; this command is stop"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
session_closed | Session closed | The session is closed or a stop sent with close is closing it. Nothing was withdrawn. | Attach the session with POST /api/v1/agent/sessions and try again, or start another session. |
command_not_withdrawable | Not a message | The command is an interrupt or a stop. Only a message can be withdrawn, and nothing was changed. | Read the command with GET /api/v1/agent/sessions/{id}/commands/{command_id}. To stop the session’s work, send a stop. |
Media type: application/json
{ "code": "payload_too_large", "message": "request body exceeds the configured size limit"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
payload_too_large | Payload too large | The request body exceeds the size limit (default 8 MiB). | Reduce the request body below the configured limit (default 8 MiB); split a large payload into smaller requests. |
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 persistent, inspect the daemon logs. |
Media type: application/json
{ "code": "withdraw_unconfirmed", "message": "the agent did not answer within the wait; whether the message was withdrawn is unknown: repeat the request"}The Retry-After header says how long to wait before repeating the request.
| 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. |
withdraw_unconfirmed | Withdrawal unconfirmed | Whether the message was withdrawn is unknown. The message may have been withdrawn, may still be queued, or may have been delivered. | Honor Retry-After and repeat the request, or read the command receipt. Do not send the message again until the outcome is withdrawn or ended. |
withdraw_write_failed | Withdrawal not recorded | The agent could not record the withdrawal, so the message was not withdrawn and remains queued. | Honor Retry-After and repeat the request. If it persists, check the agent’s storage. |
session_terminating | Session terminating | The session is shutting down. Nothing was withdrawn. | Retry shortly. |
restriction_unknown | Login restriction unknown | The agent cannot read yet which realms its login may serve, so it refuses realm-scoped requests until it can. Nothing was read or changed. | Retry after the restriction is readable. |
SDK usage
Section titled “SDK usage”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;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.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | The session id. |
key | path | string | Yes | The key. |
X-Hoody-Cwd | header | string | No | Per-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-Dir | header | string | No | Per-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-Realm | header | string | No | Per-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. |
realm | query | string | No | Per-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-Computer | header | string | No | Per-request bound remote computer (omitted = local). Rejected (400) on routes with no computer dimension. |
This endpoint takes no request body.
Responses
Section titled “Responses”{ "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.
{ "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”/a 24-hex id). | Pass a valid realm selector. |
{ "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 …. |
{ "code": "command_not_found", "message": "no command with this idempotency key in this session; a miss proves nothing until the key is retired", "details": { "retired": false }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
not_found | Not found | The requested resource does not exist. | Verify the path and identifier. |
command_not_found | No command with this key | No command with this idempotency key is kept on this session: none was admitted with it, or its receipt expired (a receipt is kept while its command waits and for 24 hours after it settled). details.retired says whether the key was retired; while it is not, the miss proves nothing. | Retire the key (POST /api/v1/agent/sessions/{id}/commands/by-key/{key}/retire) to settle it. |
{ "code": "session_closed", "message": "the session is being closed"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
session_closed | Session closed | The session is closed (not live), or a stop sent with close is closing it. Nothing was admitted. | Attach the session with POST /api/v1/agent/sessions (attach) and send the command again, or start another session. |
{ "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. | Honor the Retry-After header and retry; reduce the request rate. |
{ "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 persistent, inspect the daemon logs. |
{ "code": "service_unavailable", "message": "the command record could not be read; whether a command was admitted with this key is unknown", "details": { "admitted": "unknown" }}The Retry-After header says how long to wait before asking again when the command record could not be read, the retired key could not be made durable, or the session is shutting down.
| Error Code | Title | Description | Resolution |
|---|---|---|---|
service_unavailable | Service unavailable / Outcome unknown | The daemon could not service the request (too busy, or a per-client stream concurrency cap was hit). The command record could not be read, or the retired key could not be made durable, so whether a command was admitted with this key is unknown: it may have been. Nothing is reported as missing, and a retire is unconfirmed: it may have been recorded. | Honor Retry-After and ask again with the same key. Never send the command again under a new key on this answer. |
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 it refuses realm-scoped requests until it can. Nothing was read or changed. | Retry after the restriction is readable. |
SDK usage
Section titled “SDK usage”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;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.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | The session id. |
key | path | string | Yes | The key. |
X-Hoody-Cwd | header | string | No | Per-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-Dir | header | string | No | Per-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-Realm | header | string | No | Per-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. |
realm | query | string | No | Per-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-Computer | header | string | No | Per-request bound remote computer (omitted = local). Rejected (400) on routes with no computer dimension. |
This endpoint takes no request body.
Responses
Section titled “Responses”{ "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.
{ "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”/a 24-hex id). | Pass a valid realm selector. |
{ "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 …. |
{ "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. |
{ "code": "command_fences_exhausted", "message": "this session holds too many retired keys; the key was not retired, so whether a command is admitted with it is unknown (do not send a replacement)", "details": { "admitted": "unknown" }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
session_closed | Session closed | The session is closed (not live), or a stop sent with close is closing it. Nothing was admitted. | Attach the session with POST /api/v1/agent/sessions (attach) and send the command again, or start another session. |
command_fences_exhausted | Too many retired keys | The session already holds the most retired command keys it keeps, so this key was NOT retired: a command sent with it may still be admitted. | Do not send a replacement: the command may still run. Read the key again later. |
{ "code": "payload_too_large", "message": "request body exceeds the configured size limit"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
payload_too_large | Payload too large | The request body exceeds the size limit (default 8 MiB). | Reduce the request body below the configured limit (default 8 MiB); split a large payload into smaller requests. |
{ "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. |
{ "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 persistent, inspect the daemon logs. |
{ "code": "session_terminating", "message": "the session is shutting down; nothing was retired (retry)", "details": { "admitted": "unknown" }}The Retry-After header says how long to wait before asking again when the command record could not be read, the retired key could not be made durable, or the session is shutting down.
| Error Code | Title | Description | Resolution |
|---|---|---|---|
service_unavailable | Service unavailable / Outcome unknown | The daemon could not service the request (too busy, or a per-client stream concurrency cap was hit). The command record could not be read, or the retired key could not be made durable, so whether a command was admitted with this key is unknown: it may have been. Nothing is reported as missing, and a retire is unconfirmed: it may have been recorded. | Honor Retry-After and ask again with the same key. Never send the command again under a new key on this answer. |
session_terminating | Session terminating | The session is shutting down, so the key was not retired; whether a command was admitted with it is unknown. | Honor Retry-After and retire the key again against the session once it is back. |
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 it refuses realm-scoped requests until it can. Nothing was read or changed. | Retry after the restriction is readable. |
SDK usage
Section titled “SDK usage”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;curl -X POST "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/sessions/sess-9f2c4e1ab07d3355/commands/by-key/01HX5G2EXAMPLE1234567890AB/retire"Stopping everything in the realm
Section titled “Stopping everything in the realm”POST /api/v1/agent/stop
Section titled “POST /api/v1/agent/stop”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.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
X-Hoody-Realm | header | string | No | Per-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. |
realm | query | string | No | Per-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. |
Request body
Section titled “Request body”| Field | Type | Required | Description |
|---|---|---|---|
after | string | No | A 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. |
Responses
Section titled “Responses”{ "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": []}{ "code": "bad_request", "message": "invalid request"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The request was malformed or carried invalid parameters (for example, a non-opaque value in after). | 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”/a 24-hex id). | Pass a valid realm selector. |
{ "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 …. |
{ "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. |
{ "code": "payload_too_large", "message": "request body exceeds the configured size limit"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
payload_too_large | Payload too large | The request body exceeds the size limit (default 8 MiB). | Reduce the request body below the configured limit; split a large payload into smaller requests. |
{ "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. | Honor the Retry-After header and retry; reduce the request rate. |
{ "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 persistent, inspect the daemon logs. |
{ "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 /hoody/auth/status reports restriction “unknown”), so it refuses realm-scoped requests until it can. Nothing was read or changed. | Retry after the restriction is readable. |
SDK usage
Section titled “SDK usage”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 });# 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" }'Sending input to a running workflow
Section titled “Sending input to a running workflow”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.
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. |
X-Hoody-Config-Dir | header | string | No | Per-request --config-dir override. |
X-Hoody-Realm | header | string | No | Per-request realm selector (global or a 24-hex id). |
realm | query | string | No | Per-request realm selector (query alias of X-Hoody-Realm, read when the header is absent or empty). |
X-Hoody-Computer | header | string | No | Per-request bound remote computer (omitted = local). Rejected (400) on routes with no computer dimension. |
Request body
Section titled “Request body”| Field | Type | Required | Description |
|---|---|---|---|
text | string | No | Feedback or input text fed to the running workflow. |
Responses
Section titled “Responses”{ "status": "ok"}The response carries only status.
{ "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”/a 24-hex id). | Pass a valid realm selector. |
{ "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 …. |
realm_not_allowed | Realm not allowed for this login | The agent is logged in with a token limited to some realms (GET /hoody/auth/status lists them in realm_ids), and this session’s realm is not one of them, or is the global scope (a session restored from before the login, or a realm the login was narrowed away from). The session can still be read; nothing was run. | Continue in a session of a realm the login serves, or log the agent in with a token that covers this session’s realm. |
{ "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. |
{ "code": "payload_too_large", "message": "request body exceeds the configured size limit"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
payload_too_large | Payload too large | The request body exceeds the size limit (default 8 MiB). | Reduce the request body below the configured limit (default 8 MiB); split a large payload into smaller requests. |
{ "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. | Honor the Retry-After header and retry; reduce the request rate. |
{ "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 persistent, inspect the daemon logs. |
{ "code": "service_unavailable", "message": "service unavailable"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
service_unavailable | Service unavailable | The daemon could not service the request (too busy, or a per-client stream concurrency cap was hit). | Honor Retry-After and retry. |
restriction_unknown | Login restriction unknown | The agent cannot read yet which realms its login may serve (GET /hoody/auth/status reports restriction “unknown”), so it runs no work in any session until it can. Nothing was run. | Retry after the restriction is readable. |
admission_unconfirmed | Admission unconfirmed | The message was sent but the daemon’s answer did not arrive within the wait. It may still be delivered to the running workflow. | Watch the session stream before resending: a resent message replaces an undelivered one (the workflow keeps only the latest). |
| Error Code | Title | Description | Resolution |
|---|---|---|---|
no_active_workflow | No active workflow | No workflow is running in this session, so there is nothing to feed the message to. It was not delivered, and it is not kept for a workflow started later. | Start a workflow (POST /sessions/{id}/workflow) and send the message while it runs. |
SDK usage
Section titled “SDK usage”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.'});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." }'Reading turn receipts
Section titled “Reading turn receipts”GET /api/v1/agent/sessions/{id}/turns
Section titled “GET /api/v1/agent/sessions/{id}/turns”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.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | The session id. |
limit | query | integer | No | Return at most this many receipts, newest first (1 to 1000). A cap, not a page size: there is no next page. |
X-Hoody-Cwd | header | string | No | Per-request working-directory scope. |
X-Hoody-Config-Dir | header | string | No | Per-request --config-dir override. |
X-Hoody-Realm | header | string | No | Per-request realm selector (global or a 24-hex id). |
realm | query | string | No | Per-request realm selector (query alias of X-Hoody-Realm, read when the header is absent or empty). |
X-Hoody-Computer | header | string | No | Per-request bound remote computer (omitted = local). Rejected (400) on routes with no computer dimension. |
Responses
Section titled “Responses”{ "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": [] } ]}{ "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”/a 24-hex id). | Pass a valid realm selector. |
{ "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 …. |
{ "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. |
{ "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. | Honor the Retry-After header and retry; reduce the request rate. |
{ "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 persistent, inspect the daemon logs. |
{ "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 /hoody/auth/status reports restriction “unknown”), so it refuses realm-scoped requests until it can. Nothing was read or changed. | Retry after the restriction is readable. |
SDK usage
Section titled “SDK usage”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');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.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | The session id. |
turn_id | path | string | Yes | The turn id. |
X-Hoody-Cwd | header | string | No | Per-request working-directory scope. |
X-Hoody-Config-Dir | header | string | No | Per-request --config-dir override. |
X-Hoody-Realm | header | string | No | Per-request realm selector (global or a 24-hex id). |
realm | query | string | No | Per-request realm selector (query alias of X-Hoody-Realm, read when the header is absent or empty). |
X-Hoody-Computer | header | string | No | Per-request bound remote computer (omitted = local). Rejected (400) on routes with no computer dimension. |
Responses
Section titled “Responses”{ "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": []}{ "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”/a 24-hex id). | Pass a valid realm selector. |
{ "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 …. |
{ "code": "turn_not_found", "message": "turn not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
not_found | Not found | The requested resource does not exist. | Verify the path and identifier. |
turn_not_found | Turn not found | No ledger row for this turn id on this session. | Use the turn_id from the dispatch receipt. |
{ "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. | Honor the Retry-After header and retry; reduce the request rate. |
{ "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 persistent, inspect the daemon logs. |
{ "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 /hoody/auth/status reports restriction “unknown”), so it refuses realm-scoped requests until it can. Nothing was read or changed. | Retry after the restriction is readable. |
SDK usage
Section titled “SDK usage”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');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.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | The session id. |
key | path | string | Yes | The key. |
X-Hoody-Cwd | header | string | No | Per-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-Dir | header | string | No | Per-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-Realm | header | string | No | Per-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. |
realm | query | string | No | Per-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-Computer | header | string | No | Per-request bound remote computer (omitted = local). Rejected (400) on routes with no computer dimension. |
This endpoint takes no request body.
Responses
Section titled “Responses”{ "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.
{ "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”/a 24-hex id). | Pass a valid realm selector. |
{ "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 …. |
{ "code": "turn_not_found", "message": "no turn with this idempotency key in this session; a miss proves nothing until the key is retired", "details": { "retired": false }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
not_found | Not found | The requested resource does not exist. | Verify the path and identifier. |
turn_not_found | No turn with this key | No turn was admitted with this idempotency key on this session. details.retired says whether the key was retired; while it is not, the miss proves nothing (the turn may still be on its way). | Retire the key (POST /api/v1/agent/sessions/{id}/turns/by-key/{key}/retire) to settle it. |
{ "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 Retry-After and retry. |
{ "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 persistent, inspect the daemon logs. |
{ "code": "service_unavailable", "message": "the turn record could not be read; whether a turn was admitted with this key is unknown", "details": { "admitted": "unknown" }}The Retry-After header says how long to wait before asking again when the turn record could not be read, the retired key could not be made durable, or the session is shutting down.
| Error Code | Title | Description | Resolution |
|---|---|---|---|
service_unavailable | Outcome unknown | The turn record could not be read, or the retired key could not be made durable, so whether a turn was admitted with this key is unknown: it may have been. Nothing is reported as missing, and a retire is unconfirmed: it may have been recorded. | Honor Retry-After and ask again with the same key. Never send the turn again under a new key on this answer. |
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 it refuses realm-scoped requests until it can. Nothing was read or changed. | Retry after the restriction is readable. |
SDK usage
Section titled “SDK usage”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;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.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | The session id. |
key | path | string | Yes | The key. |
X-Hoody-Cwd | header | string | No | Per-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-Dir | header | string | No | Per-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-Realm | header | string | No | Per-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. |
realm | query | string | No | Per-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-Computer | header | string | No | Per-request bound remote computer (omitted = local). Rejected (400) on routes with no computer dimension. |
This endpoint takes no request body.
Responses
Section titled “Responses”{ "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.
{ "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”/a 24-hex id). | Pass a valid realm selector. |
{ "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 …. |
{ "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. |
{ "code": "turn_fences_exhausted", "message": "this session holds too many retired keys; the key was not retired, so whether a turn is admitted with it is unknown (do not send a replacement)", "details": { "admitted": "unknown" }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
turn_fences_exhausted | Too many retired keys | The session already holds the most retired turn keys it keeps, so this key was NOT retired: a turn sent with it may still be admitted. | Do not send a replacement: the turn may still run. Read the key again later. |
{ "code": "payload_too_large", "message": "request body exceeds the configured size limit"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
payload_too_large | Payload too large | The request body exceeds the size limit (default 8 MiB). | Reduce the request body below the configured limit (default 8 MiB); split a large payload into smaller requests. |
{ "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. |
{ "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 persistent, inspect the daemon logs. |
{ "code": "session_terminating", "message": "the session is shutting down; nothing was retired (retry)", "details": { "admitted": "unknown" }}The Retry-After header says how long to wait before asking again when the turn record could not be read, the retired key could not be made durable, or the session is shutting down.
| Error Code | Title | Description | Resolution |
|---|---|---|---|
session_terminating | Session terminating | The session is shutting down, so the key was not retired; whether a turn was admitted with it is unknown. | Honor Retry-After and retire the key again against the session once it is back. |
service_unavailable | Outcome unknown | The turn record could not be read, or the retired key could not be made durable, so whether a turn was admitted with this key is unknown: it may have been. Nothing is reported as missing, and a retire is unconfirmed: it may have been recorded. | Honor Retry-After and ask again with the same key. Never send the turn again under a new key on this answer. |
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 it refuses realm-scoped requests until it can. Nothing was read or changed. | Retry after the restriction is readable. |
SDK usage
Section titled “SDK usage”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;curl -X POST "https://{projectId}-{computerId}-agent-1.{server}.computers.hoody.com/api/v1/agent/sessions/sess-9f2c4e1ab07d3355/turns/by-key/01HX5G2EXAMPLE1234567890AB/retire"