Agent: Session settings
Section titled “Agent: Session settings”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.
Agent and model
Section titled “Agent and model”PATCH /api/v1/agent/sessions/{id}/agent
Section titled “PATCH /api/v1/agent/sessions/{id}/agent”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.
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, 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-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 with 400 bad_request. |
X-Hoody-Computer | header | string | No | Per-request bound remote computer (omitted = local). Rejected (400) on routes with no computer dimension. |
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, 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. |
realm | query | string | No | Per-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. |
Request body
Section titled “Request body”| Field | Type | Required | Description |
|---|---|---|---|
agent | string | No | Chat-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. |
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"}'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://67e89abc123def456789abcd-890abcdef12345678901cdef-agent-1.node-example-1.computers.hoody.com' });
await client.agent.sessions.setAgent('{id}', { agent: 'build' });Responses
Section titled “Responses”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.
| Field | Type | Description |
|---|---|---|
status | string | ok on success. |
deferred | boolean | Present 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. |
note | string | Present alongside deferred, explaining why the command may not have taken effect. |
Media type: application/json
{ "code": "bad_request", "message": "invalid request"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The request was malformed or carried invalid parameters. | Correct the request body or query parameters. |
realm_scope_unsupported | Realm scope unsupported | A per-request scope header this route does not take: a realm or computer header on a route without that dimension, or, on an agent pinned to one realm, a different realm. | Omit the header, or name the realm the agent is pinned to. |
invalid_realm | Invalid realm selector | The realm selector is malformed (not "", global, or a 24-hex id). | Pass a valid realm selector. |
Media type: application/json
{ "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
forbidden | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL, for example with hoody agent …. |
Media type: application/json
{ "code": "not_found", "message": "resource not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
not_found | Not found | The requested resource does not exist. | Verify the path and identifier. |
Media type: application/json
{ "code": "delegated_session", "message": "Cannot change the agent: the installed Hoody Claude Code bridge cannot change this during a session; update the Hoody agent plugin, or start a new session"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
delegated_session | Delegated session | The Claude Code bridge installed for this session is too old to switch the agent mid-session. Nothing changed. | Update the Hoody agent plugin, or start a new session with the agent. |
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 configured size limit (default 8 MiB). Reduce the request body. | Reduce the request body below the configured limit (default 8 MiB); split a large payload into smaller requests. |
Media type: application/json
{ "code": "unknown_chat_agent", "message": "unknown agent \"auditr\": no chat agent by that name; list the agents with GET /api/v1/agent/agents"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
model_unavailable | Speech model | The model is a speech model, which cannot answer chat. details.reason is speech_model. Nothing was changed. | Pick a chat model from GET /api/v1/agent/models. |
unknown_chat_agent | Unknown agent | The named chat agent does not exist in the session’s realm, or its definition cannot be parsed. Nothing was created or changed. | Pick an agent from GET /api/v1/agent/agents, or omit agent to use the default. |
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": "service unavailable"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
service_unavailable | Service unavailable | The daemon could not service the request because it was too busy or a per-client stream concurrency cap was hit. | Honor Retry-After and retry. |
PATCH /api/v1/agent/sessions/{id}/model
Section titled “PATCH /api/v1/agent/sessions/{id}/model”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.
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, 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-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 with 400 bad_request. |
X-Hoody-Computer | header | string | No | Per-request bound remote computer (omitted = local). Rejected (400) on routes with no computer dimension. |
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, 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. |
realm | query | string | No | Per-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. |
Request body
Section titled “Request body”| Field | Type | Required | Description |
|---|---|---|---|
model | string | Yes | Model 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. |
scope | string | No | What 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. |
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"}'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://67e89abc123def456789abcd-890abcdef12345678901cdef-agent-1.node-example-1.computers.hoody.com' });
await client.agent.sessions.setModel('{id}', { model: 'anthropic/claude-opus-4-8', scope: 'session',});Responses
Section titled “Responses”Applied.
Media type: application/json
{ "status": "ok", "model": "anthropic/claude-opus-4-8", "persisted": true, "scope": "session"}| Field | Type | Description |
|---|---|---|
status | string | ok on a successful switch. |
model | string | The model spec now active on the session. |
persisted | boolean | Whether 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. |
scope | string | What the switch changed: agent, including the chat agent’s default model, or session, only this session. |
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. A blank model or a scope other than agent or session is refused. | Correct the request body or query parameters. |
realm_scope_unsupported | Realm scope unsupported | A per-request scope header this route does not take: a realm or computer header on a route without that dimension, or, on an agent pinned to one realm, a different realm. | Omit the header, or name the realm the agent is pinned to. |
invalid_realm | Invalid realm selector | The realm selector is malformed (not "", global, or a 24-hex id). | Pass a valid realm selector. |
Media type: application/json
{ "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
forbidden | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL, for example with hoody agent …. |
The session is unknown, closed, in another realm, or owned by another caller. These cases return one answer so they do not disclose session information.
Media type: application/json
{ "code": "not_found", "message": "session not live"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
not_found | Session not found | Unknown, closed, cross-realm, or foreign-owner sessions are collapsed into one code and one message so nothing leaks. This also covers the close-versus-switch race. | List sessions and retry against a live one. |
The session is busy or delegated.
Media type: application/json
{ "code": "delegated_session", "message": "cannot switch the model: the installed Hoody Claude Code bridge cannot change this during a session; update the Hoody agent plugin, or start a new session"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
gate_parked | Gate parked | A confirm or question gate is parked. The switch cannot apply until it resolves. | Answer or cancel the gate under details.pending_gate, then retry. |
turn_in_flight | Turn in flight | A turn is running or parked on the session’s single-writer slot. | Retry when the session is idle. |
delegated_session | Delegated session | The installed Claude Code bridge is too old to change the model mid-session. | Update the Hoody agent plugin, or start a new session with the model. |
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 configured size limit (default 8 MiB). Reduce the request body. | Reduce the request body below the configured limit (default 8 MiB); split a large payload into smaller requests. |
The requested model cannot be constructed.
Media type: application/json
{ "code": "model_unavailable", "message": "cannot switch to model \"x/y\": unknown provider"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
model_unavailable | Model unavailable | The model is unavailable. This includes an unknown catalogue model with details.reason set to unknown_model, a speech model with details.reason set to speech_model, a spec that cannot be constructed, or a model from another provider on a Claude Code session with details.reason set to not_claude. Nothing changed. | Check the model spec and provider credentials, then choose a listed chat model. For a Claude Code session, choose a Claude alias or Claude model id. |
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": "service unavailable"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
service_unavailable | Service unavailable | The daemon could not service the request because it was too busy or a per-client stream concurrency cap was hit. | Honor Retry-After and retry. |
The session was still initializing when the request ended.
Media type: application/json
{ "code": "timeout", "message": "session still initializing"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
timeout | Initialization wait cut short | The switch waited on session readiness and the request context ended first. | Retry once the session finishes initializing. |
Reasoning and response
Section titled “Reasoning and response”PATCH /api/v1/agent/sessions/{id}/effort
Section titled “PATCH /api/v1/agent/sessions/{id}/effort”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.
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, 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-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 with 400 bad_request. |
X-Hoody-Computer | header | string | No | Per-request bound remote computer (omitted = local). Rejected (400) on routes with no computer dimension. |
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, 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. |
realm | query | string | No | Per-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. |
Request body
Section titled “Request body”| Field | Type | Required | Description |
|---|---|---|---|
effort | string | No | low, medium, high, xhigh, max, or "" for the model default. Any other value is refused with 400 bad_request and details.field set to effort. |
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"}'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://67e89abc123def456789abcd-890abcdef12345678901cdef-agent-1.node-example-1.computers.hoody.com' });
await client.agent.sessions.setEffort('{id}', { effort: 'high' });Responses
Section titled “Responses”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.
| Field | Type | Description |
|---|---|---|
status | string | ok on success. |
deferred | boolean | Present 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. |
note | string | Present alongside deferred, explaining why the command may not have taken effect. |
Media type: application/json
{ "code": "bad_request", "message": "invalid request"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The request was malformed or carried invalid parameters. | Correct the request body or query parameters. |
realm_scope_unsupported | Realm scope unsupported | A per-request scope header this route does not take: a realm or computer header on a route without that dimension, or, on an agent pinned to one realm, a different realm. | Omit the header, or name the realm the agent is pinned to. |
invalid_realm | Invalid realm selector | The realm selector is malformed (not "", global, or a 24-hex id). | Pass a valid realm selector. |
Media type: application/json
{ "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
forbidden | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL, for example with hoody agent …. |
Media type: application/json
{ "code": "not_found", "message": "resource not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
not_found | Not found | The requested resource does not exist. | Verify the path and identifier. |
Media type: application/json
{ "code": "delegated_session", "message": "Cannot change the effort: the installed Hoody Claude Code bridge cannot change this during a session; update the Hoody agent plugin, or start a new session"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
delegated_session | Delegated session | The Claude Code bridge installed for this session is too old to change the effort mid-session. Nothing changed. | Update the Hoody agent plugin, or start a new session. |
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 configured size limit (default 8 MiB). Reduce the request body. | 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": "service_unavailable", "message": "service unavailable"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
service_unavailable | Service unavailable | The daemon could not service the request because it was too busy or a per-client stream concurrency cap was hit. | Honor Retry-After and retry. |
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.
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, 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-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 with 400 bad_request. |
X-Hoody-Computer | header | string | No | Per-request bound remote computer (omitted = local). Rejected (400) on routes with no computer dimension. |
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, 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. |
realm | query | string | No | Per-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. |
Request body
Section titled “Request body”| Field | Type | Required | Description |
|---|---|---|---|
level | string | No | normal, concise, terse, or minimal. Any other value is refused with 400 bad_request and details.field set to level. |
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"}'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://67e89abc123def456789abcd-890abcdef12345678901cdef-agent-1.node-example-1.computers.hoody.com' });
await client.agent.sessions.setVerbosity('{id}', { level: 'concise' });Responses
Section titled “Responses”Applied.
Media type: application/json
{ "status": "ok"}The setting applies while a gate is parked.
| Field | Type | Description |
|---|---|---|
status | string | ok on success. |
Media type: application/json
{ "code": "bad_request", "message": "invalid request"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The request was malformed or carried invalid parameters. | Correct the request body or query parameters. |
realm_scope_unsupported | Realm scope unsupported | A per-request scope header this route does not take: a realm or computer header on a route without that dimension, or, on an agent pinned to one realm, a different realm. | Omit the header, or name the realm the agent is pinned to. |
invalid_realm | Invalid realm selector | The realm selector is malformed (not "", global, or a 24-hex id). | Pass a valid realm selector. |
Media type: application/json
{ "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
forbidden | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL, for example with hoody agent …. |
Media type: application/json
{ "code": "not_found", "message": "resource not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
not_found | Not found | The requested resource does not exist. | Verify the path and identifier. |
Media type: application/json
{ "code": "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 configured size limit (default 8 MiB). Reduce the request body. | 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": "service_unavailable", "message": "service unavailable"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
service_unavailable | Service unavailable | The daemon could not service the request because it was too busy or a per-client stream concurrency cap was hit. | Honor Retry-After and retry. |
Auto-reply loop
Section titled “Auto-reply loop”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.
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, 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-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 with 400 bad_request. |
X-Hoody-Computer | header | string | No | Per-request bound remote computer (omitted = local). Rejected (400) on routes with no computer dimension. |
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, 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. |
realm | query | string | No | Per-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. |
Request body
Section titled “Request body”| Field | Type | Required | Description |
|---|---|---|---|
armed | boolean | No | true to arm the auto-reply loop, false to disarm. |
rounds | integer | No | Number of auto-reply rounds budgeted. |
model | string | No | Replier model override. A speech model is refused with 422 model_unavailable and details.reason set to speech_model. |
allow_writes | boolean | No | Opt in to write-class actions during auto-reply. |
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}'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://67e89abc123def456789abcd-890abcdef12345678901cdef-agent-1.node-example-1.computers.hoody.com' });
await client.agent.sessions.autoReply.update('{id}', { armed: true, rounds: 5, model: 'anthropic/claude-haiku-4-5', allow_writes: false,});Responses
Section titled “Responses”Applied.
Media type: application/json
{ "status": "ok"}The setting applies while a gate is parked.
| Field | Type | Description |
|---|---|---|
status | string | ok on success. |
Media type: application/json
{ "code": "bad_request", "message": "invalid request"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The request was malformed or carried invalid parameters. | Correct the request body or query parameters. |
realm_scope_unsupported | Realm scope unsupported | A per-request scope header this route does not take: a realm or computer header on a route without that dimension, or, on an agent pinned to one realm, a different realm. | Omit the header, or name the realm the agent is pinned to. |
invalid_realm | Invalid realm selector | The realm selector is malformed (not "", global, or a 24-hex id). | Pass a valid realm selector. |
Media type: application/json
{ "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
forbidden | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL, for example with hoody agent …. |
Media type: application/json
{ "code": "not_found", "message": "resource not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
not_found | Not found | The requested resource does not exist. | Verify the path and identifier. |
Media type: application/json
{ "code": "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 configured size limit (default 8 MiB). Reduce the request body. | Reduce the request body below the configured limit (default 8 MiB); split a large payload into smaller requests. |
Media type: application/json
{ "code": "model_unavailable", "message": "model \"minimax/speech-2.8-turbo\" is a speech model, not a chat model", "details": { "reason": "speech_model" }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
model_unavailable | Speech model | The model is a speech model, which cannot answer chat. details.reason is speech_model. Nothing was changed. | Pick a chat model from GET /api/v1/agent/models. |
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": "service unavailable"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
service_unavailable | Service unavailable | The daemon could not service the request because it was too busy or a per-client stream concurrency cap was hit. | Honor Retry-After and retry. |
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.
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, 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-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 with 400 bad_request. |
X-Hoody-Computer | header | string | No | Per-request bound remote computer (omitted = local). Rejected (400) on routes with no computer dimension. |
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, 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. |
realm | query | string | No | Per-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. |
Request body
Section titled “Request body”| Field | Type | Required | Description |
|---|---|---|---|
allow_writes | boolean | No | New write-class opt-in state. |
The SDK provides these facade methods:
client.agent.sessions.autoReply.disableWrites(id, data, options?)setsallow_writes=false.client.agent.sessions.autoReply.enableWrites(id, data, options?)setsallow_writes=true.
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}'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://67e89abc123def456789abcd-890abcdef12345678901cdef-agent-1.node-example-1.computers.hoody.com' });
await client.agent.sessions.autoReply.disableWrites('{id}', {});Responses
Section titled “Responses”Applied.
Media type: application/json
{ "status": "ok"}The setting applies while a gate is parked.
| Field | Type | Description |
|---|---|---|
status | string | ok on success. |
Media type: application/json
{ "code": "bad_request", "message": "invalid request"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The request was malformed or carried invalid parameters. | Correct the request body or query parameters. |
realm_scope_unsupported | Realm scope unsupported | A per-request scope header this route does not take: a realm or computer header on a route without that dimension, or, on an agent pinned to one realm, a different realm. | Omit the header, or name the realm the agent is pinned to. |
invalid_realm | Invalid realm selector | The realm selector is malformed (not "", global, or a 24-hex id). | Pass a valid realm selector. |
Media type: application/json
{ "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
forbidden | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL, for example with hoody agent …. |
Media type: application/json
{ "code": "not_found", "message": "resource not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
not_found | Not found | The requested resource does not exist. | Verify the path and identifier. |
Media type: application/json
{ "code": "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 configured size limit (default 8 MiB). Reduce the request body. | 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": "service_unavailable", "message": "service unavailable"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
service_unavailable | Service unavailable | The daemon could not service the request because it was too busy or a per-client stream concurrency cap was hit. | Honor Retry-After and retry. |
Shell environment
Section titled “Shell environment”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.
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, 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-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 with 400 bad_request. |
X-Hoody-Computer | header | string | No | Per-request bound remote computer (omitted = local). Rejected (400) on routes with no computer dimension. |
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, 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. |
realm | query | string | No | Per-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. |
Request body
Section titled “Request body”| Field | Type | Required | Description |
|---|---|---|---|
enabled | boolean | No | Whether to inject the HOODY_* shell-environment contract. |
The SDK provides these facade methods:
client.agent.sessions.disableHoodyEnv(id, data, options?)setsenabled=false.client.agent.sessions.enableHoodyEnv(id, data, options?)setsenabled=true.
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}'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://67e89abc123def456789abcd-890abcdef12345678901cdef-agent-1.node-example-1.computers.hoody.com' });
await client.agent.sessions.disableHoodyEnv('{id}', {});Responses
Section titled “Responses”Applied.
Media type: application/json
{ "status": "ok"}The setting applies while a gate is parked.
| Field | Type | Description |
|---|---|---|
status | string | ok on success. |
Media type: application/json
{ "code": "bad_request", "message": "invalid request"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The request was malformed or carried invalid parameters. | Correct the request body or query parameters. |
realm_scope_unsupported | Realm scope unsupported | A per-request scope header this route does not take: a realm or computer header on a route without that dimension, or, on an agent pinned to one realm, a different realm. | Omit the header, or name the realm the agent is pinned to. |
invalid_realm | Invalid realm selector | The realm selector is malformed (not "", global, or a 24-hex id). | Pass a valid realm selector. |
Media type: application/json
{ "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
forbidden | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL, for example with hoody agent …. |
Media type: application/json
{ "code": "not_found", "message": "resource not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
not_found | Not found | The requested resource does not exist. | Verify the path and identifier. |
Media type: application/json
{ "code": "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 configured size limit (default 8 MiB). Reduce the request body. | 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": "service_unavailable", "message": "service unavailable"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
service_unavailable | Service unavailable | The daemon could not service the request because it was too busy or a per-client stream concurrency cap was hit. | Honor Retry-After and retry. |
After-compaction message
Section titled “After-compaction message”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.
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, 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-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 with 400 bad_request. |
X-Hoody-Computer | header | string | No | Per-request bound remote computer (omitted = local). Rejected (400) on routes with no computer dimension. |
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, 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. |
realm | query | string | No | Per-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. |
Request body
Section titled “Request body”| Field | Type | Required | Description |
|---|---|---|---|
text | string | Yes | The message text, at most 16384 bytes in UTF-8. Empty or whitespace-only text removes the message. |
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."}'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://67e89abc123def456789abcd-890abcdef12345678901cdef-agent-1.node-example-1.computers.hoody.com' });
await client.agent.sessions.setAfterCompaction('{id}', { text: 'You are the payments service reviewer. Run the unit tests before reporting results.',});Responses
Section titled “Responses”Saved.
Media type: application/json
{ "status": "ok", "bytes": 82}| Field | Type | Description |
|---|---|---|
status | string | ok. |
bytes | integer | The size of the saved text in bytes. 0 means the message was removed. |
Media type: application/json
{ "code": "bad_request", "message": "invalid request"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
bad_request | Bad request | The request was malformed or carried invalid parameters. | Correct the request body or query parameters. |
realm_scope_unsupported | Realm scope unsupported | A per-request scope header this route does not take: a realm or computer header on a route without that dimension, or, on an agent pinned to one realm, a different realm. | Omit the header, or name the realm the agent is pinned to. |
invalid_realm | Invalid realm selector | The realm selector is malformed (not "", global, or a 24-hex id). | Pass a valid realm selector. |
Media type: application/json
{ "code": "forbidden", "message": "Hoody Kit programs are reached through their URLs only"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
forbidden | Forbidden (Source IP Guard) | Refused by the Source IP Guard: Hoody Kit programs are reached through their URLs only. | Call the agent through its URL, for example with hoody agent …. |
Media type: application/json
{ "code": "not_found", "message": "resource not found"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
not_found | Not found | The requested resource does not exist. This includes a closed session. | Verify the path and identifier. |
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 configured size limit (default 8 MiB). Reduce the request body. | 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. |
store_failed | Agent store failed | One of the agent’s own stores could not be read, parsed, locked, or written, so the operation did not complete. The message names the store, for example “the agent’s settings file is damaged and was left unchanged”. A damaged store is left unchanged rather than rewritten. | Retry once. If it persists, repair the named store inside the computer. The agent’s log (GET /api/v1/agent/logs) records a “store failure” entry with the store, the failure kind (io, corrupt, or lock), and a path-free cause such as “open: permission denied” or “invalid JSON at offset 12”. It does not name the file’s path. |
Media type: application/json
{ "code": "restriction_unknown", "message": "the login's realm restriction could not be read — retry"}| Error Code | Title | Description | Resolution |
|---|---|---|---|
restriction_unknown | Login restriction unknown | The agent cannot read yet which realms its login may serve. GET /api/v1/agent/hoody/auth/status reports restriction unknown, so the agent refuses realm-scoped requests until it can read the restriction. Nothing was read or changed. | Retry after the restriction is readable. |