Skip to content

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

Hoody.com

Each operation changes one setting of an existing agent session. These changes take effect from the next turn, except for the model switch, which applies inline and synchronously, and the after-compaction message, which is re-added after the summary of every compaction, before the next model request.

Most live PATCH settings can be changed while a turn is running. The agent and effort settings are discarded if a confirm or question gate is parked, and their responses include deferred: true and a note; send them again after the turn ends. The auto-reply, auto-reply write opt-in, Hoody environment, and verbosity settings apply while a gate is parked.

The model switch cannot run while the session is busy. A parked gate or running turn returns 409 instead of a deferred success. On a Claude Code delegated session, the model is a launch option that applies from the session’s next turn.

In the Hub, open AI, select the chat, and open Details > Session. While the chat is idle, choose a Model and press Use this model, or change Agent, How hard it thinks, or Reply length.

These computer-scoped Kit routes do not take a Hoody account token. Permission to call them is determined by the computer’s proxy permission rules.

Every JSON error response contains code and message, with an optional details object.

Switches the live chat agent and echoes the change as a session event. The bot agent is refused with 400 bad_request and details.field set to agent. A Bot’s own session cannot switch away from the bot agent.

On a Claude Code delegated session, the new agent’s instructions, tools, and skills apply from the next turn, while the session keeps its pinned Claude model. An installed Claude Code bridge that is too old to switch the agent mid-session returns 409 delegated_session. If the session is still connecting, the request is accepted and then refused with a delegated_session error event, leaving the agent unchanged. Read the session state back in that case.

This endpoint can be called while a turn is running. On a delegated session, the switch applies when the turn ends.

NameInTypeRequiredDescription
idpathstringYesThe session id.
X-Hoody-CwdheaderstringNoPer-request working-directory scope: the .hoody project layer / record cwd / tool+workflow cwd. Required by routes that resolve a cwd, such as POST /api/v1/agent/todos; createTodo also accepts a body cwd. The value must be UTF-8. Other bytes, such as a non-ASCII path sent as Latin-1, are refused with 400 bad_request.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override selecting which on-disk .hoody install a stateless read/write resolves against. The value must be UTF-8. Other bytes are refused with 400 bad_request.
X-Hoody-ComputerheaderstringNoPer-request bound remote computer (omitted = local). Rejected (400) on routes with no computer dimension.
X-Hoody-RealmheaderstringNoPer-request realm selector: global (not tied to a realm) or a 24-hex realm id (also accepted as ?realm=). On a session route it names the realm the session is looked up in. A session in another realm, or in a realm this login does not serve, returns 404 not_found. Rejected with 400 realm_scope_unsupported on active-only or no-realm routes and for any other realm on an agent pinned to one realm.
realmquerystringNoPer-request realm selector, the 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, returns 404 not_found. Rejected with 400 realm_scope_unsupported on active-only or no-realm routes and for any other realm on an agent pinned to one realm.
FieldTypeRequiredDescription
agentstringNoChat-agent name to switch to. The bot agent is refused with 400 bad_request and details.field set to agent on every session because it runs only inside a Bot. A Bot’s own session keeps the bot agent, so any switch is refused with 400 bad_request.
Terminal window
curl -X PATCH "https://67e89abc123def456789abcd-890abcdef12345678901cdef-agent-1.node-example-1.computers.hoody.com/api/v1/agent/sessions/{id}/agent" \
-H "Content-Type: application/json" \
-d '{"agent":"build"}'

Applied.

Media type: application/json

{
"status": "ok"
}

When a gate is parked, the response also carries deferred: true and a note explaining why the command may not have taken effect. Send it again after the turn ends.

FieldTypeDescription
statusstringok on success.
deferredbooleanPresent and true when a gate is parked. The daemon discards this command while a gate is parked and does not apply it later, so it may not have taken effect. Send it again after the turn ends.
notestringPresent alongside deferred, explaining why the command may not have taken effect.

Performs a synchronous live model switch. It returns the active model, whether it was persisted, and the applied scope. On a Claude Code session the switch is always the session’s own (scope reads session) and applies from the session’s next turn.

This endpoint cannot switch a model while the session is busy. A parked gate or running turn returns 409 gate_parked or 409 turn_in_flight.

NameInTypeRequiredDescription
idpathstringYesThe session id.
X-Hoody-CwdheaderstringNoPer-request working-directory scope: the .hoody project layer / record cwd / tool+workflow cwd. Required by routes that resolve a cwd, such as POST /api/v1/agent/todos; createTodo also accepts a body cwd. The value must be UTF-8. Other bytes, such as a non-ASCII path sent as Latin-1, are refused with 400 bad_request.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override selecting which on-disk .hoody install a stateless read/write resolves against. The value must be UTF-8. Other bytes are refused with 400 bad_request.
X-Hoody-ComputerheaderstringNoPer-request bound remote computer (omitted = local). Rejected (400) on routes with no computer dimension.
X-Hoody-RealmheaderstringNoPer-request realm selector: global (not tied to a realm) or a 24-hex realm id (also accepted as ?realm=). On a session route it names the realm the session is looked up in. A session in another realm, or in a realm this login does not serve, returns 404 not_found. Rejected with 400 realm_scope_unsupported on active-only or no-realm routes and for any other realm on an agent pinned to one realm.
realmquerystringNoPer-request realm selector, the 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, returns 404 not_found. Rejected with 400 realm_scope_unsupported on active-only or no-realm routes and for any other realm on an agent pinned to one realm.
FieldTypeRequiredDescription
modelstringYesModel spec to switch to, such as anthropic/claude-opus-4-8 or fusion/<slug>. A blank value is rejected and is never a silent no-op.
scopestringNoWhat the switch changes. agent is the default and also makes the model the chat agent’s default for later sessions. session changes only this session and leaves the agent’s file alone. A Claude Code session always uses session scope.
Terminal window
curl -X PATCH "https://67e89abc123def456789abcd-890abcdef12345678901cdef-agent-1.node-example-1.computers.hoody.com/api/v1/agent/sessions/{id}/model" \
-H "Content-Type: application/json" \
-d '{"model":"anthropic/claude-opus-4-8","scope":"session"}'

Applied.

Media type: application/json

{
"status": "ok",
"model": "anthropic/claude-opus-4-8",
"persisted": true,
"scope": "session"
}
FieldTypeDescription
statusstringok on a successful switch.
modelstringThe model spec now active on the session.
persistedbooleanWhether the choice was saved. With scope: "agent", it is written to the chat agent’s frontmatter. With scope: "session", or on a Claude Code session, it is written to the session’s own record. false means the live switch stands but reverts in the next session. A session that has not sent its first message yet saves the choice with that message.
scopestringWhat the switch changed: agent, including the chat agent’s default model, or session, only this session.

Changes reasoning effort to low, medium, high, xhigh, max, or "" for the model default.

With model_settings or agent frontmatter, thinking: disabled or a thinking configuration that names its own effort takes precedence. Otherwise, this effort supplies the level when thinking is enabled without one and the model accepts a level.

On a Claude Code delegated session, this value is Claude Code’s --effort. An explicit model_settings thinking effort wins, and "" selects Claude Code’s own default instead of a configured default. The session state reads back the effort Claude Code runs with. An installed bridge that is too old to change effort mid-session returns 409 delegated_session. If the session is still connecting, the request is accepted and then refused with a delegated_session error event, leaving the effort unchanged. Read the session state back in that case.

This endpoint can be called while a turn is running. On a delegated session, the change applies when the turn ends.

NameInTypeRequiredDescription
idpathstringYesThe session id.
X-Hoody-CwdheaderstringNoPer-request working-directory scope: the .hoody project layer / record cwd / tool+workflow cwd. Required by routes that resolve a cwd, such as POST /api/v1/agent/todos; createTodo also accepts a body cwd. The value must be UTF-8. Other bytes, such as a non-ASCII path sent as Latin-1, are refused with 400 bad_request.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override selecting which on-disk .hoody install a stateless read/write resolves against. The value must be UTF-8. Other bytes are refused with 400 bad_request.
X-Hoody-ComputerheaderstringNoPer-request bound remote computer (omitted = local). Rejected (400) on routes with no computer dimension.
X-Hoody-RealmheaderstringNoPer-request realm selector: global (not tied to a realm) or a 24-hex realm id (also accepted as ?realm=). On a session route it names the realm the session is looked up in. A session in another realm, or in a realm this login does not serve, returns 404 not_found. Rejected with 400 realm_scope_unsupported on active-only or no-realm routes and for any other realm on an agent pinned to one realm.
realmquerystringNoPer-request realm selector, the 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, returns 404 not_found. Rejected with 400 realm_scope_unsupported on active-only or no-realm routes and for any other realm on an agent pinned to one realm.
FieldTypeRequiredDescription
effortstringNolow, medium, high, xhigh, max, or "" for the model default. Any other value is refused with 400 bad_request and details.field set to effort.
Terminal window
curl -X PATCH "https://67e89abc123def456789abcd-890abcdef12345678901cdef-agent-1.node-example-1.computers.hoody.com/api/v1/agent/sessions/{id}/effort" \
-H "Content-Type: application/json" \
-d '{"effort":"high"}'

Applied.

Media type: application/json

{
"status": "ok"
}

When a gate is parked, the response also carries deferred: true and a note explaining why the command may not have taken effect. Send it again after the turn ends.

FieldTypeDescription
statusstringok on success.
deferredbooleanPresent and true when a gate is parked. The daemon discards this command while a gate is parked and does not apply it later, so it may not have taken effect. Send it again after the turn ends.
notestringPresent alongside deferred, explaining why the command may not have taken effect.

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

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

Changes response verbosity to normal, concise, terse, or minimal. The applied level is echoed on the stream as event.verbosity.

This endpoint can be called while a turn is running. The setting applies while a gate is parked.

NameInTypeRequiredDescription
idpathstringYesThe session id.
X-Hoody-CwdheaderstringNoPer-request working-directory scope: the .hoody project layer / record cwd / tool+workflow cwd. Required by routes that resolve a cwd, such as POST /api/v1/agent/todos; createTodo also accepts a body cwd. The value must be UTF-8. Other bytes, such as a non-ASCII path sent as Latin-1, are refused with 400 bad_request.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override selecting which on-disk .hoody install a stateless read/write resolves against. The value must be UTF-8. Other bytes are refused with 400 bad_request.
X-Hoody-ComputerheaderstringNoPer-request bound remote computer (omitted = local). Rejected (400) on routes with no computer dimension.
X-Hoody-RealmheaderstringNoPer-request realm selector: global (not tied to a realm) or a 24-hex realm id (also accepted as ?realm=). On a session route it names the realm the session is looked up in. A session in another realm, or in a realm this login does not serve, returns 404 not_found. Rejected with 400 realm_scope_unsupported on active-only or no-realm routes and for any other realm on an agent pinned to one realm.
realmquerystringNoPer-request realm selector, the 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, returns 404 not_found. Rejected with 400 realm_scope_unsupported on active-only or no-realm routes and for any other realm on an agent pinned to one realm.
FieldTypeRequiredDescription
levelstringNonormal, concise, terse, or minimal. Any other value is refused with 400 bad_request and details.field set to level.
Terminal window
curl -X PATCH "https://67e89abc123def456789abcd-890abcdef12345678901cdef-agent-1.node-example-1.computers.hoody.com/api/v1/agent/sessions/{id}/verbosity" \
-H "Content-Type: application/json" \
-d '{"level":"concise"}'

Applied.

Media type: application/json

{
"status": "ok"
}

The setting applies while a gate is parked.

FieldTypeDescription
statusstringok on success.

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

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

Arms or disarms the self-driving auto-reply loop and configures its round budget, replier model, and write opt-in. Arming with a speech model, or a fusion composite naming one, returns 422 model_unavailable with details.reason set to speech_model. Nothing is armed.

This endpoint can be called while a turn is running. The setting applies while a gate is parked.

NameInTypeRequiredDescription
idpathstringYesThe session id.
X-Hoody-CwdheaderstringNoPer-request working-directory scope: the .hoody project layer / record cwd / tool+workflow cwd. Required by routes that resolve a cwd, such as POST /api/v1/agent/todos; createTodo also accepts a body cwd. The value must be UTF-8. Other bytes, such as a non-ASCII path sent as Latin-1, are refused with 400 bad_request.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override selecting which on-disk .hoody install a stateless read/write resolves against. The value must be UTF-8. Other bytes are refused with 400 bad_request.
X-Hoody-ComputerheaderstringNoPer-request bound remote computer (omitted = local). Rejected (400) on routes with no computer dimension.
X-Hoody-RealmheaderstringNoPer-request realm selector: global (not tied to a realm) or a 24-hex realm id (also accepted as ?realm=). On a session route it names the realm the session is looked up in. A session in another realm, or in a realm this login does not serve, returns 404 not_found. Rejected with 400 realm_scope_unsupported on active-only or no-realm routes and for any other realm on an agent pinned to one realm.
realmquerystringNoPer-request realm selector, the 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, returns 404 not_found. Rejected with 400 realm_scope_unsupported on active-only or no-realm routes and for any other realm on an agent pinned to one realm.
FieldTypeRequiredDescription
armedbooleanNotrue to arm the auto-reply loop, false to disarm.
roundsintegerNoNumber of auto-reply rounds budgeted.
modelstringNoReplier model override. A speech model is refused with 422 model_unavailable and details.reason set to speech_model.
allow_writesbooleanNoOpt in to write-class actions during auto-reply.
Terminal window
curl -X PATCH "https://67e89abc123def456789abcd-890abcdef12345678901cdef-agent-1.node-example-1.computers.hoody.com/api/v1/agent/sessions/{id}/auto-reply" \
-H "Content-Type: application/json" \
-d '{"armed":true,"rounds":5,"model":"anthropic/claude-haiku-4-5","allow_writes":false}'

Applied.

Media type: application/json

{
"status": "ok"
}

The setting applies while a gate is parked.

FieldTypeDescription
statusstringok on success.

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

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

Flips the write-class opt-in on an already-armed auto-reply loop without re-arming it or resetting its round budget.

This endpoint can be called while a turn is running. The setting applies while a gate is parked.

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

The SDK provides these facade methods:

  • client.agent.sessions.autoReply.disableWrites(id, data, options?) sets allow_writes=false.
  • client.agent.sessions.autoReply.enableWrites(id, data, options?) sets allow_writes=true.
Terminal window
curl -X PATCH "https://67e89abc123def456789abcd-890abcdef12345678901cdef-agent-1.node-example-1.computers.hoody.com/api/v1/agent/sessions/{id}/auto-reply/writes" \
-H "Content-Type: application/json" \
-d '{"allow_writes":false}'

Applied.

Media type: application/json

{
"status": "ok"
}

The setting applies while a gate is parked.

FieldTypeDescription
statusstringok on success.

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

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

Toggles the session’s HOODY_* shell-environment contract for the bash tool.

This endpoint can be called while a turn is running. The setting applies while a gate is parked.

NameInTypeRequiredDescription
idpathstringYesThe session id.
X-Hoody-CwdheaderstringNoPer-request working-directory scope: the .hoody project layer / record cwd / tool+workflow cwd. Required by routes that resolve a cwd, such as POST /api/v1/agent/todos; createTodo also accepts a body cwd. The value must be UTF-8. Other bytes, such as a non-ASCII path sent as Latin-1, are refused with 400 bad_request.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override selecting which on-disk .hoody install a stateless read/write resolves against. The value must be UTF-8. Other bytes are refused with 400 bad_request.
X-Hoody-ComputerheaderstringNoPer-request bound remote computer (omitted = local). Rejected (400) on routes with no computer dimension.
X-Hoody-RealmheaderstringNoPer-request realm selector: global (not tied to a realm) or a 24-hex realm id (also accepted as ?realm=). On a session route it names the realm the session is looked up in. A session in another realm, or in a realm this login does not serve, returns 404 not_found. Rejected with 400 realm_scope_unsupported on active-only or no-realm routes and for any other realm on an agent pinned to one realm.
realmquerystringNoPer-request realm selector, the 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, returns 404 not_found. Rejected with 400 realm_scope_unsupported on active-only or no-realm routes and for any other realm on an agent pinned to one realm.
FieldTypeRequiredDescription
enabledbooleanNoWhether to inject the HOODY_* shell-environment contract.

The SDK provides these facade methods:

  • client.agent.sessions.disableHoodyEnv(id, data, options?) sets enabled=false.
  • client.agent.sessions.enableHoodyEnv(id, data, options?) sets enabled=true.
Terminal window
curl -X PATCH "https://67e89abc123def456789abcd-890abcdef12345678901cdef-agent-1.node-example-1.computers.hoody.com/api/v1/agent/sessions/{id}/hoody-env" \
-H "Content-Type: application/json" \
-d '{"enabled":false}'

Applied.

Media type: application/json

{
"status": "ok"
}

The setting applies while a gate is parked.

FieldTypeDescription
statusstringok on success.

PUT /api/v1/agent/sessions/{id}/after-compaction

Section titled “PUT /api/v1/agent/sessions/{id}/after-compaction”

Sets the text that the agent re-adds to the conversation as a user message right after the summary of every compaction. This includes automatic compactions, manual compactions, and the compaction that recovers from a context overflow. The message is therefore in place before the next model request.

The text is stored and re-added byte for byte. It is never included in the system prompt. Empty or whitespace-only text removes the message. The maximum size is 16 KiB, or 16384 bytes in UTF-8. The message is saved with the session, kept across restarts, and inherited by a fork. GET /api/v1/agent/sessions/{id} and GET /api/v1/agent/sessions/{id}/state expose it as after_compaction.

The setter accepts live Claude Code sessions. On a Claude Code session, where Claude Code performs the compaction, the message is sent to Claude Code with the first message after each compaction. The endpoint accepts only a live session; a closed session returns 404 not_found.

The text can be stored while a turn is running. It is used after a compaction, before the next model request.

NameInTypeRequiredDescription
idpathstringYesThe session id.
X-Hoody-CwdheaderstringNoPer-request working-directory scope: the .hoody project layer / record cwd / tool+workflow cwd. Required by routes that resolve a cwd, such as POST /api/v1/agent/todos; createTodo also accepts a body cwd. The value must be UTF-8. Other bytes, such as a non-ASCII path sent as Latin-1, are refused with 400 bad_request.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override selecting which on-disk .hoody install a stateless read/write resolves against. The value must be UTF-8. Other bytes are refused with 400 bad_request.
X-Hoody-ComputerheaderstringNoPer-request bound remote computer (omitted = local). Rejected (400) on routes with no computer dimension.
X-Hoody-RealmheaderstringNoPer-request realm selector: global (not tied to a realm) or a 24-hex realm id (also accepted as ?realm=). On a session route it names the realm the session is looked up in. A session in another realm, or in a realm this login does not serve, returns 404 not_found. Rejected with 400 realm_scope_unsupported on active-only or no-realm routes and for any other realm on an agent pinned to one realm.
realmquerystringNoPer-request realm selector, the 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, returns 404 not_found. Rejected with 400 realm_scope_unsupported on active-only or no-realm routes and for any other realm on an agent pinned to one realm.
FieldTypeRequiredDescription
textstringYesThe message text, at most 16384 bytes in UTF-8. Empty or whitespace-only text removes the message.
Terminal window
curl -X PUT "https://67e89abc123def456789abcd-890abcdef12345678901cdef-agent-1.node-example-1.computers.hoody.com/api/v1/agent/sessions/{id}/after-compaction" \
-H "Content-Type: application/json" \
-d '{"text":"You are the payments service reviewer. Run the unit tests before reporting results."}'

Saved.

Media type: application/json

{
"status": "ok",
"bytes": 82
}
FieldTypeDescription
statusstringok.
bytesintegerThe size of the saved text in bytes. 0 means the message was removed.