Skip to content
Hoody Documentation
Hoody.com
Download Page (.md)

Agent: Sessions

Section titled “Agent: Sessions”

The agent sessions API governs the full lifecycle of a Hoody agent session — create, attach, fork, dispatch turns, answer gates, trim history, and reconfigure the running session’s model, effort, verbosity, chat agent, and auto-reply posture. Sessions freeze their start binding (realm, container, cwd, tool mode, dir scope, backend) at creation time; subsequent per-request realm or container headers that contradict that binding are rejected. Use these endpoints when you are building a control surface that drives the agent over the public, proxied endpoint.

All routes are scoped to the per-request container’s agent service and resolve through hoody-proxy. Sessions are identified by a 24-character lowercase hexadecimal id.

Session lifecycle

Section titled “Session lifecycle”

POST /api/v1/agent/sessions

Section titled “POST /api/v1/agent/sessions”

Create a new session, fork an existing session, or attach to a live session. The session freezes its realm, container, cwd, tool mode, dir scope, and backend at start. Set backend: "acp" together with delegated_agent to delegate the session to an external CLI agent (BYOA; only "claude" is supported). Use attach to rejoin a live session and fork to branch from an existing session.

This endpoint takes no path parameters. The realm and container headers, if supplied, must match the parent’s binding for fork and the session’s frozen binding for attach; otherwise a realm_conflict or container_conflict is returned.

Terminal window
curl -X POST \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "cwd": "/Users/me/projects/acme",
    "model": "anthropic/claude-opus-4-8",
    "agent": "default",
    "tool_mode": "default",
    "dir_scope": "home"
  }' \
  https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/sessions

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
X-Hoody-CwdheaderstringNoPer-request working-directory scope: the .hoody project layer / record cwd / tool+workflow cwd. Required by routes that resolve a cwd.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override selecting which on-disk .hoody install a stateless read/write resolves (HoodyPaths).
X-Hoody-ContainerheaderstringNoPer-request bound remote container (omitted = local). Rejected (400) on routes with no container dimension.
X-Hoody-RealmheaderstringNoPer-request realm selector: "global" or a 24-hex id. Rejected (400 realm_scope_unsupported) on active-only / no-realm routes.
realmquerystringNoIn-query alias of the X-Hoody-Realm header (read only when the header is absent).

Request Body

Section titled “Request Body”
NameTypeRequiredDescription
realmstringNoRealm selector to scope the session (frozen at start).
containerstringNoContainer id/selector to run tools on (frozen at start).
cwdstringNoWorking directory for the session (frozen at start).
config_dirstringNoConfig directory override.
modelstringNoModel for this session. On a fresh create/fork it overrides the chat agent’s pinned model for this session only. Rejected (400) together with attach or backend: "acp".
agentstringNoInitial chat-agent name. Rejected (400) together with fork or attach.
tool_modestringNoInitial tool mode (frozen at start).
dir_scopestringNoInitial directory-access scope: home/full (frozen at start).
attachstringNoattach_session_id — attach to an existing session instead of creating one.
forkstringNofork_session_id — fork from an existing session.
fork_turn_idxintegerNoTurn index to fork at (with fork).
backendstringNoSession backend: "" (Hoody LLM) or "acp" (BYOA delegated agent).
delegated_agentstringNoBYOA agent when backend: "acp": claude.
headlessbooleanNoStart the session in headless posture.

DELETE /api/v1/agent/sessions/{id}

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

Closes the live session connection (the daemon cancels the session). With ?hard=true, also removes the persisted record. A session created with a body config_dir override is persisted under that override’s sessions dir; to hard-delete it, send the same directory as X-Hoody-Config-Dir.

Terminal window
curl -X DELETE \
  -H "Authorization: Bearer <token>" \
  https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/sessions/67e89abc123def456789abcd?hard=true

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesSession identifier.
hardquerybooleanNoWhen true, also remove the persisted session record (not just the live connection).
X-Hoody-CwdheaderstringNoPer-request working-directory scope.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override. Required for hard-delete when the session was created with a body config_dir override.
X-Hoody-ContainerheaderstringNoPer-request bound remote container (omitted = local). Rejected (400) on routes with no container dimension.
X-Hoody-RealmheaderstringNoPer-request realm selector. Rejected (400) on this route.
realmquerystringNoIn-query alias of X-Hoody-Realm.

Listing and discovery

Section titled “Listing and discovery”

GET /api/v1/agent/sessions

Section titled “GET /api/v1/agent/sessions”

Lists persisted sessions for the requesting cwd (open + closed), with an attached flag for live sessions. Pagination via page/limit is honored; omit limit (default 0) to receive the full set. meta.total is always the full pre-slice count; meta.page and meta.limit echo the window when limit is supplied.

Terminal window
curl -X GET \
  -H "Authorization: Bearer <token>" \
  "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/sessions?page=1&limit=20"

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
include_systemquerybooleanNoWhen true, also include daemon-owned system/resident sessions in the listing.
pagequeryintegerNo1-based page number for pagination.
limitqueryintegerNoMaximum items per page (0 = no pagination).
X-Hoody-CwdheaderstringNoPer-request working-directory scope.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override.
X-Hoody-ContainerheaderstringNoPer-request bound remote container. Rejected (400) on this route.
X-Hoody-RealmheaderstringNoPer-request realm selector. Rejected (400) on this route.
realmquerystringNoIn-query alias of X-Hoody-Realm.

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

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

Returns the persisted summary for a session (live or closed). A live session also surfaces its frozen start binding (realm/container/modes) and attached: true.

Terminal window
curl -X GET \
  -H "Authorization: Bearer <token>" \
  https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/sessions/67e89abc123def456789abcd

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesSession identifier.
X-Hoody-CwdheaderstringNoPer-request working-directory scope.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override.
X-Hoody-ContainerheaderstringNoPer-request bound remote container. Rejected (400) on this route.
X-Hoody-RealmheaderstringNoPer-request realm selector. Rejected (400) on this route.
realmquerystringNoIn-query alias of X-Hoody-Realm.

GET /api/v1/agent/sessions/cwds

Section titled “GET /api/v1/agent/sessions/cwds”

Returns the distinct working directories across all persisted sessions, most-recent first.

Terminal window
curl -X GET \
  -H "Authorization: Bearer <token>" \
  https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/sessions/cwds

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
X-Hoody-CwdheaderstringNoPer-request working-directory scope.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override.
X-Hoody-ContainerheaderstringNoPer-request bound remote container. Rejected (400) on this route.
X-Hoody-RealmheaderstringNoPer-request realm selector. Rejected (400) on this route.
realmquerystringNoIn-query alias of X-Hoody-Realm.

Replay, stream, and transcript

Section titled “Replay, stream, and transcript”

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

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

Returns the gateway’s buffered event tail for a LIVE session (the daemon’s full viewport snapshot already streamed into the replay ring), with min_seq/max_seq for resume. For a non-live session, use /transcript to read the persisted conversation without attaching, or attach to receive the daemon’s event.replay.

Terminal window
curl -X GET \
  -H "Authorization: Bearer <token>" \
  https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/sessions/67e89abc123def456789abcd/replay

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesSession identifier.
X-Hoody-CwdheaderstringNoPer-request working-directory scope.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override.
X-Hoody-ContainerheaderstringNoPer-request bound remote container. Rejected (400) on this route.
X-Hoody-RealmheaderstringNoPer-request realm selector. Rejected (400) on this route.
realmquerystringNoIn-query alias of X-Hoody-Realm.

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

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

WebSocket (primary) or SSE attach to a live session’s full event.* taxonomy. Events carry a gateway-stamped monotonic int64 seq; ?since=<seq> / Last-Event-ID resume from the 1024-event replay ring (a gap past eviction emits event: lagged {code:replay_gap} then streams from min_seq). A slow client is dropped lagged and never backpressures the daemon. WS clients may post inline answer frames (confirm/answer/cancel/workflow_message).

Terminal window
curl -X GET \
  -H "Authorization: Bearer <token>" \
  -H "Accept: text/event-stream" \
  -H "Last-Event-ID: 152" \
  https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/sessions/67e89abc123def456789abcd/stream

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesSession identifier.
sincequeryintegerNoResume from this gateway int64 seq (also accepted as the Last-Event-ID header).
Last-Event-IDheaderstringNoSSE resume cursor — the gateway int64 seq to resume from; sent automatically by an SSE client on reconnect.
X-Hoody-CwdheaderstringNoPer-request working-directory scope.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override.
X-Hoody-ContainerheaderstringNoPer-request bound remote container. Rejected (400) on this route.
X-Hoody-RealmheaderstringNoPer-request realm selector. Rejected (400) on this route.
realmquerystringNoIn-query alias of X-Hoody-Realm.

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

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

Returns the persisted conversation — the event.replay message projection (text/thinking/tool_use/tool_result blocks) plus turn boundaries — for a live or closed session, read from the session record. It never attaches, never resumes, and never consumes the exclusive attach slot. Use after_turn=N to skip completed turns 1..N (exclusive cursor; 0 = full transcript; past-end values clamp; the response echoes the applied value).

Terminal window
curl -X GET \
  -H "Authorization: Bearer <token>" \
  "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/sessions/67e89abc123def456789abcd/transcript?after_turn=0"

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesSession identifier.
after_turnqueryintegerNoExclusive completed-turn skip cursor: return content strictly after completed turn N (0 = full transcript; values past the end clamp; negative/non-integer = 400).
X-Hoody-CwdheaderstringNoPer-request working-directory scope.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override.
X-Hoody-ContainerheaderstringNoPer-request bound remote container. Rejected (400) on this route.
X-Hoody-RealmheaderstringNoPer-request realm selector. Rejected (400) on this route.
realmquerystringNoIn-query alias of X-Hoody-Realm.

Turn dispatch

Section titled “Turn dispatch”

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

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

Dispatches a user turn and returns {job_id}; observe agent_done on the session’s stream. Refuses a new turn when the session already has a parked gate (409 gate_parked) or a turn is already running (409 turn_in_flight) — single-writer, no duplicate parked turns.

Terminal window
curl -X POST \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"text": "Explain the bug in src/main.go"}' \
  https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/sessions/67e89abc123def456789abcd/messages

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesSession identifier.
X-Hoody-CwdheaderstringNoPer-request working-directory scope.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override.
X-Hoody-ContainerheaderstringNoPer-request bound remote container. Rejected (400) on this route.
X-Hoody-RealmheaderstringNoPer-request realm selector. Rejected (400) on this route.
realmquerystringNoIn-query alias of X-Hoody-Realm.

Request Body

Section titled “Request Body”
NameTypeRequiredDescription
textstringNoThe user message text for this turn.
tool_modestringNoOptional per-turn tool mode override.
dir_scopestringNoOptional per-turn directory-access scope override: home/full.

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

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

Dispatches a turn and streams the resulting events over SSE from the seq captured just before the dispatch — only this turn’s events, not the whole retained ring. The explicit X-Hoody-Gate-Policy: auto_approve header (or ?policy=auto_approve) auto-answers confirm gates with approved=true for the life of the stream — off by default.

Terminal window
curl -X POST \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -H "X-Hoody-Gate-Policy: auto_approve" \
  -d '{"text": "Summarize the diff"}' \
  https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/sessions/67e89abc123def456789abcd/prompt:stream

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesSession identifier.
policyquerystringNoauto_approve auto-answers confirm gates for the life of the stream; off by default.
X-Hoody-Gate-PolicyheaderstringNoConfirm-gate posture: "auto_approve". Any other value is rejected 400.
X-Hoody-CwdheaderstringNoPer-request working-directory scope.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override.
X-Hoody-ContainerheaderstringNoPer-request bound remote container. Rejected (400) on this route.
X-Hoody-RealmheaderstringNoPer-request realm selector. Rejected (400) on this route.
realmquerystringNoIn-query alias of X-Hoody-Realm.

Request Body

Section titled “Request Body”
NameTypeRequiredDescription
textstringNoThe user message text for this turn.
tool_modestringNoOptional per-turn tool mode override.
dir_scopestringNoOptional per-turn directory-access scope override: home/full.

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

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

Dispatches a turn and blocks until agent_done. By default (interactive posture) it returns {pending_gate} the moment a turn parks — it NEVER auto-approves implicitly. Repeated calls against a parked session return the SAME pending_gate (no duplicate parked turns). The explicit X-Hoody-Gate-Policy: auto_approve header (or ?policy=auto_approve) adopts the headless posture and auto-answers confirm gates. A server read-timeout prevents a parked turn from wedging the request.

Terminal window
curl -X POST \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"text": "Run the tests"}' \
  https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/sessions/67e89abc123def456789abcd/prompt:sync

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesSession identifier.
policyquerystringNoauto_approve adopts the headless auto-answer posture; off by default.
X-Hoody-Gate-PolicyheaderstringNoConfirm-gate posture: "auto_approve". Any other value is rejected 400.
X-Hoody-CwdheaderstringNoPer-request working-directory scope.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override.
X-Hoody-ContainerheaderstringNoPer-request bound remote container. Rejected (400) on this route.
X-Hoody-RealmheaderstringNoPer-request realm selector. Rejected (400) on this route.
realmquerystringNoIn-query alias of X-Hoody-Realm.

Request Body

Section titled “Request Body”
NameTypeRequiredDescription
textstringNoThe user message text for this turn.
tool_modestringNoOptional per-turn tool mode override.
dir_scopestringNoOptional per-turn directory-access scope override: home/full.

Gates

Section titled “Gates”

POST /api/v1/agent/sessions/{id}/answer

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

Answers a parked ask-the-user question. Use answer/text for a free-form reply, or answers (a map) for a structured multi-field question. gate_id/generation are optional echoes (a mismatch is 409). Returns 409 no_pending_gate / stale_gate / gate_already_answered / gate_type_mismatch on mismatch.

Terminal window
curl -X POST \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"answer": "Yes, go ahead", "gate_id": "gate-3", "generation": 3}' \
  https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/sessions/67e89abc123def456789abcd/answer

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesSession identifier.
X-Hoody-CwdheaderstringNoPer-request working-directory scope.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override.
X-Hoody-ContainerheaderstringNoPer-request bound remote container. Rejected (400) on this route.
X-Hoody-RealmheaderstringNoPer-request realm selector. Rejected (400) on this route.
realmquerystringNoIn-query alias of X-Hoody-Realm.

Request Body

Section titled “Request Body”
NameTypeRequiredDescription
gate_idstringNoOptional echo of the parked gate id (stale/mismatch returns 409).
generationintegerNoOptional echo of the parked gate generation.
answerstringNoFree-form answer text.
textstringNoAlternate answer text field (forwarded alongside answer).
answersobjectNoStructured per-field answers for a multi-field question.

POST /api/v1/agent/sessions/{id}/answer:assist

Section titled “POST /api/v1/agent/sessions/{id}/answer:assist”

Runs a one-shot helper-model call that proposes answers for the parked question (emits event.question_suggestion). The real answer still travels via /answer — the daemon never answers itself. Returns 409 no_pending_gate when no question is parked, or assist_in_flight if a suggestion job is already running.

Terminal window
curl -X POST \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"mode": "suggest", "model": "anthropic/claude-haiku-4-5", "gen": 7}' \
  https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/sessions/67e89abc123def456789abcd/answer:assist

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesSession identifier.
X-Hoody-CwdheaderstringNoPer-request working-directory scope.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override.
X-Hoody-ContainerheaderstringNoPer-request bound remote container. Rejected (400) on this route.
X-Hoody-RealmheaderstringNoPer-request realm selector. Rejected (400) on this route.
realmquerystringNoIn-query alias of X-Hoody-Realm.

Request Body

Section titled “Request Body”
NameTypeRequiredDescription
modestringNoSuggestion mode (default "suggest").
modelstringNoHelper model override; empty uses the configured helper.
genintegerNoGeneration counter to correlate the suggestion event.

POST /api/v1/agent/sessions/{id}/confirm

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

Approves or denies a parked tool/dir confirmation. Returns 409 no_pending_gate when nothing is parked, or stale_gate / gate_already_answered on mismatch (the gateway never fires a command that would be silently dropped). Set persist_dirs: true on an approved directory grant to persist it to settings.json (WS/REST parity).

Terminal window
curl -X POST \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"approved": true, "persist_dirs": true, "gate_id": "gate-3", "generation": 3}' \
  https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/sessions/67e89abc123def456789abcd/confirm

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesSession identifier.
X-Hoody-CwdheaderstringNoPer-request working-directory scope.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override.
X-Hoody-ContainerheaderstringNoPer-request bound remote container. Rejected (400) on this route.
X-Hoody-RealmheaderstringNoPer-request realm selector. Rejected (400) on this route.
realmquerystringNoIn-query alias of X-Hoody-Realm.

Request Body

Section titled “Request Body”
NameTypeRequiredDescription
gate_idstringNoOptional echo of the parked gate id (stale/mismatch returns 409).
generationintegerNoOptional echo of the parked gate generation.
approvedbooleanNotrue to approve, false to deny (defaults to true if omitted).
persist_dirsbooleanNoPersist an approved directory grant to settings.json.

Cancel and close

Section titled “Cancel and close”

POST /api/v1/agent/sessions/{id}/cancel

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

Stops the active turn at the server layer; spares the session and background tasks (distinct from close). Also aborts an in-flight in-session direct tool run — it holds the same serial turn slot.

Terminal window
curl -X POST \
  -H "Authorization: Bearer <token>" \
  https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/sessions/67e89abc123def456789abcd/cancel

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesSession identifier.
X-Hoody-CwdheaderstringNoPer-request working-directory scope.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override.
X-Hoody-ContainerheaderstringNoPer-request bound remote container. Rejected (400) on this route.
X-Hoody-RealmheaderstringNoPer-request realm selector. Rejected (400) on this route.
realmquerystringNoIn-query alias of X-Hoody-Realm.

POST /api/v1/agent/sessions/{id}/close

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

Tears the session down (the daemon cancels it and removes the live session).

Terminal window
curl -X POST \
  -H "Authorization: Bearer <token>" \
  https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/sessions/67e89abc123def456789abcd/close

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesSession identifier.
X-Hoody-CwdheaderstringNoPer-request working-directory scope.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override.
X-Hoody-ContainerheaderstringNoPer-request bound remote container. Rejected (400) on this route.
X-Hoody-RealmheaderstringNoPer-request realm selector. Rejected (400) on this route.
realmquerystringNoIn-query alias of X-Hoody-Realm.

Workflow

Section titled “Workflow”

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

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

Injects user feedback/input into a running workflow (maps to session.workflow_message → workflowMsgChan, not commandChan).

Terminal window
curl -X POST \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"text": "Stop at step 4 and summarize"}' \
  https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/sessions/67e89abc123def456789abcd/workflow/messages

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesSession identifier.
X-Hoody-CwdheaderstringNoPer-request working-directory scope.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override.
X-Hoody-ContainerheaderstringNoPer-request bound remote container. Rejected (400) on this route.
X-Hoody-RealmheaderstringNoPer-request realm selector. Rejected (400) on this route.
realmquerystringNoIn-query alias of X-Hoody-Realm.

Request Body

Section titled “Request Body”
NameTypeRequiredDescription
textstringNoFeedback/input text fed to the running workflow.

Settings

Section titled “Settings”

PATCH /api/v1/agent/sessions/{id}/agent

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

Live chat-agent switch (echoed as an event).

Terminal window
curl -X PATCH \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"agent": "code-reviewer"}' \
  https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/sessions/67e89abc123def456789abcd/agent

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesSession identifier.
X-Hoody-CwdheaderstringNoPer-request working-directory scope.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override.
X-Hoody-ContainerheaderstringNoPer-request bound remote container. Rejected (400) on this route.
X-Hoody-RealmheaderstringNoPer-request realm selector. Rejected (400) on this route.
realmquerystringNoIn-query alias of X-Hoody-Realm.

Request Body

Section titled “Request Body”
NameTypeRequiredDescription
agentstringNoChat-agent name to switch to.

PATCH /api/v1/agent/sessions/{id}/auto-reply

Section titled “PATCH /api/v1/agent/sessions/{id}/auto-reply”

Arm or disarm the self-driving auto-reply loop (rounds, replier model, write opt-in).

Terminal window
curl -X PATCH \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"armed": true, "rounds": 4, "model": "anthropic/claude-haiku-4-5", "allow_writes": false}' \
  https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/sessions/67e89abc123def456789abcd/auto-reply

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesSession identifier.
X-Hoody-CwdheaderstringNoPer-request working-directory scope.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override.
X-Hoody-ContainerheaderstringNoPer-request bound remote container. Rejected (400) on this route.
X-Hoody-RealmheaderstringNoPer-request realm selector. Rejected (400) on this route.
realmquerystringNoIn-query alias of X-Hoody-Realm.

Request Body

Section titled “Request Body”
NameTypeRequiredDescription
armedbooleanNotrue to arm the auto-reply loop, false to disarm.
roundsintegerNoNumber of auto-reply rounds budgeted.
modelstringNoReplier model override.
allow_writesbooleanNoOpt in to write-class actions during auto-reply.

PATCH /api/v1/agent/sessions/{id}/auto-reply/writes

Section titled “PATCH /api/v1/agent/sessions/{id}/auto-reply/writes”

Flip the write-class opt-in on an already-armed auto-reply loop WITHOUT re-arming (no budget reset).

Terminal window
curl -X PATCH \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"allow_writes": true}' \
  https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/sessions/67e89abc123def456789abcd/auto-reply/writes

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesSession identifier.
X-Hoody-CwdheaderstringNoPer-request working-directory scope.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override.
X-Hoody-ContainerheaderstringNoPer-request bound remote container. Rejected (400) on this route.
X-Hoody-RealmheaderstringNoPer-request realm selector. Rejected (400) on this route.
realmquerystringNoIn-query alias of X-Hoody-Realm.

Request Body

Section titled “Request Body”
NameTypeRequiredDescription
allow_writesbooleanNoNew write-class opt-in state.

PATCH /api/v1/agent/sessions/{id}/effort

Section titled “PATCH /api/v1/agent/sessions/{id}/effort”

Live reasoning-effort change (low/medium/high/xhigh, or "" for the model default).

Terminal window
curl -X PATCH \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"effort": "high"}' \
  https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/sessions/67e89abc123def456789abcd/effort

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesSession identifier.
X-Hoody-CwdheaderstringNoPer-request working-directory scope.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override.
X-Hoody-ContainerheaderstringNoPer-request bound remote container. Rejected (400) on this route.
X-Hoody-RealmheaderstringNoPer-request realm selector. Rejected (400) on this route.
realmquerystringNoIn-query alias of X-Hoody-Realm.

Request Body

Section titled “Request Body”
NameTypeRequiredDescription
effortstringNolow/medium/high/xhigh, or "" for the model default.

PATCH /api/v1/agent/sessions/{id}/hoody-env

Section titled “PATCH /api/v1/agent/sessions/{id}/hoody-env”

Live toggle of the session’s HOODY_* shell-env contract for the bash tool.

Terminal window
curl -X PATCH \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}' \
  https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/sessions/67e89abc123def456789abcd/hoody-env

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesSession identifier.
X-Hoody-CwdheaderstringNoPer-request working-directory scope.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override.
X-Hoody-ContainerheaderstringNoPer-request bound remote container. Rejected (400) on this route.
X-Hoody-RealmheaderstringNoPer-request realm selector. Rejected (400) on this route.
realmquerystringNoIn-query alias of X-Hoody-Realm.

Request Body

Section titled “Request Body”
NameTypeRequiredDescription
enabledbooleanNoWhether to inject the HOODY_* shell-env contract.

PATCH /api/v1/agent/sessions/{id}/model

Section titled “PATCH /api/v1/agent/sessions/{id}/model”

SYNCHRONOUS live model switch: applies the model inline and answers what actually happened. Returns {status: "ok", model, persisted} on success; persisted=false indicates the frontmatter write failed (the live switch stands but reverts next session). 409 gate_parked/turn_in_flight while the session is busy, 404 for an unknown/closed session, 400 for a blank model, 409 delegated_session on external-agent sessions, 422 model_unavailable for a spec that cannot be constructed. A successful switch persists into the chat agent’s frontmatter — a GLOBAL repin for future sessions of that agent, not a session-scoped choice.

Terminal window
curl -X PATCH \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"model": "anthropic/claude-opus-4-8"}' \
  https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/sessions/67e89abc123def456789abcd/model

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesSession identifier.
X-Hoody-CwdheaderstringNoPer-request working-directory scope.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override.
X-Hoody-ContainerheaderstringNoPer-request bound remote container. Rejected (400) on this route.
X-Hoody-RealmheaderstringNoPer-request realm selector. Rejected (400) on this route.
realmquerystringNoIn-query alias of X-Hoody-Realm.

Request Body

Section titled “Request Body”
NameTypeRequiredDescription
modelstringYesModel spec to switch to (provider-prefixed, e.g. anthropic/claude-opus-4-8, or fusion/<slug>). A blank value is rejected, never a silent no-op.

PATCH /api/v1/agent/sessions/{id}/verbosity

Section titled “PATCH /api/v1/agent/sessions/{id}/verbosity”

Live verbosity change (normal/concise/terse/minimal).

Terminal window
curl -X PATCH \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"level": "concise"}' \
  https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/sessions/67e89abc123def456789abcd/verbosity

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesSession identifier.
X-Hoody-CwdheaderstringNoPer-request working-directory scope.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override.
X-Hoody-ContainerheaderstringNoPer-request bound remote container. Rejected (400) on this route.
X-Hoody-RealmheaderstringNoPer-request realm selector. Rejected (400) on this route.
realmquerystringNoIn-query alias of X-Hoody-Realm.

Request Body

Section titled “Request Body”
NameTypeRequiredDescription
levelstringNonormal/concise/terse/minimal.

History

Section titled “History”

POST /api/v1/agent/sessions/{id}/trim

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

Truncates the session’s conversation history to (and including) the given turn index.

Terminal window
curl -X POST \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"turn_idx": 4}' \
  https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/sessions/67e89abc123def456789abcd/trim

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesSession identifier.
X-Hoody-CwdheaderstringNoPer-request working-directory scope.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override.
X-Hoody-ContainerheaderstringNoPer-request bound remote container. Rejected (400) on this route.
X-Hoody-RealmheaderstringNoPer-request realm selector. Rejected (400) on this route.
realmquerystringNoIn-query alias of X-Hoody-Realm.

Request Body

Section titled “Request Body”
NameTypeRequiredDescription
turn_idxintegerNoTurn index to truncate history to (and including).