Agent: Sessions

Download Page (.md)

Agent Sessions let you create, inspect, fork, prompt, and tear down a single-writer conversation context. A session is opened frozen to its start binding (realm, container, cwd, tool mode, directory scope, backend) — every later command either inherits or rejects that binding. Use these endpoints to list persisted sessions, dispatch turns (synchronously, streamed, or fire-and-forget), answer parked gates, attach to a live stream, and live-tune the chat agent, model, effort, and verbosity.

All routes are reached through the Hoody proxy at https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.icu. A per-request realm header is rejected on these routes.

Session discovery

`GET /api/v1/agent/sessions`

List sessions for the requesting working directory (open and closed). The attached flag marks live sessions. Pagination is honored — pass ?page=N&limit=M for a window, or omit limit to receive the full set.

Parameters

Name	In	Type	Required	Description
`include_system`	query	boolean	No	When true, also include daemon-owned system/resident sessions in the listing.
`page`	query	integer	No	1-based page number for pagination.
`limit`	query	integer	No	Maximum items per page (0 = no pagination).
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container (omitted = local).
`X-Hoody-Realm`	header	string	No	Per-request realm selector: `global` or a 24-hex id. Rejected on this route.
`realm`	query	string	No	In-query alias of the `X-Hoody-Realm` header. Rejected on this route.

Response

{
  "items": [
    {
      "id": "5f3a1b2c8d4e9f0012345678",
      "title": "Refactor auth middleware",
      "cwd": "/home/user/projects/api",
      "attached": true,
      "updated_at": 1739991234
    },
    {
      "id": "5f3a1b2c8d4e9f0012345679",
      "title": "Investigate flaky test",
      "cwd": "/home/user/projects/api",
      "attached": false,
      "updated_at": 1739987541
    }
  ],
  "meta": {
    "total": 2,
    "page": 1,
    "limit": 20
  }
}

{
  "code": "bad_request",
  "message": "invalid page or limit"
}

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 realm header was supplied to this active-only route.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not reach the service through the public endpoint.	Reach the agent through hoody-proxy, not by connecting to the container directly.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

SDK

await client.agent.sessions.listSessionsIterator({ page: 1, limit: 20 })

cURL

curl -X GET "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.icu/api/v1/agent/sessions?page=1&limit=20" \
  -H "X-Hoody-Cwd: /home/user/projects/api"

`GET /api/v1/agent/sessions/cwds`

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

Parameters

Name	In	Type	Required	Description
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container.
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected on this route.
`realm`	query	string	No	In-query alias of the `X-Hoody-Realm` header. Rejected on this route.

Response

{
  "cwds": [
    "/home/user/projects/api",
    "/home/user/projects/web",
    "/home/user/notes"
  ]
}

{
  "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 realm header was supplied to this active-only route.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not reach the service through the public endpoint.	Reach the agent through hoody-proxy, not by connecting to the container directly.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

SDK

await client.agent.sessions.listSessionCwds()

cURL

curl -X GET "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.icu/api/v1/agent/sessions/cwds" \
  -H "X-Hoody-Cwd: /home/user/projects/api"

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

Return the persisted summary for a session (live or closed). Live sessions also expose the frozen start binding and attached: true.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container.
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected on this route.
`realm`	query	string	No	In-query alias of the `X-Hoody-Realm` header. Rejected on this route.

Response

{
  "id": "5f3a1b2c8d4e9f0012345678",
  "title": "Refactor auth middleware",
  "cwd": "/home/user/projects/api",
  "attached": true,
  "agent": "default",
  "model": "anthropic/claude-opus-4-8",
  "frozen": {
    "realm": "global",
    "container": "local",
    "tool_mode": "rw",
    "dir_scope": "home"
  },
  "updated_at": 1739991234
}

{
  "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 realm header was supplied to this active-only route.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not reach the service through the public endpoint.	Reach the agent through hoody-proxy, not by connecting to the container directly.

{
  "code": "not_found",
  "message": "resource not found"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

SDK

await client.agent.sessions.getSession("5f3a1b2c8d4e9f0012345678")

cURL

curl -X GET "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.icu/api/v1/agent/sessions/5f3a1b2c8d4e9f0012345678"

Session lifecycle

`POST /api/v1/agent/sessions`

Open a new agent session, fork an existing one, or attach to one in progress. The session is frozen at start to its realm, container, cwd, tool_mode, dir_scope, and backend. To delegate to an external CLI agent, set backend: "acp" and delegated_agent: "claude".

Parameters

Name	In	Type	Required	Description
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container.
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected on this route.
`realm`	query	string	No	In-query alias of the `X-Hoody-Realm` header. Rejected on this route.

Request Body

Name	Type	Required	Description
`realm`	string	No	Realm selector to scope the session (frozen at start).
`container`	string	No	Container id/selector to run tools on (frozen at start).
`cwd`	string	No	Working directory for the session (frozen at start).
`config_dir`	string	No	Config directory override.
`model`	string	No	Model for this session. Overrides the chat agent’s pinned model for this session only. Rejected with `attach` or `backend: "acp"`.
`agent`	string	No	Initial chat-agent name. Rejected with `fork` or `attach`.
`tool_mode`	string	No	Initial tool mode (frozen at start).
`dir_scope`	string	No	Initial directory-access scope: `home` or `full` (frozen at start).
`attach`	string	No	Attach to an existing session instead of creating one.
`fork`	string	No	Fork from an existing session.
`fork_turn_idx`	integer	No	Turn index to fork at (with `fork`).
`backend`	string	No	Session backend: `""` (Hoody LLM) or `"acp"` (BYOA delegated agent).
`delegated_agent`	string	No	BYOA agent when `backend: "acp"`: `claude`.
`headless`	boolean	No	Start the session in headless posture.

{
  "agent": "default",
  "cwd": "/home/user/projects/api",
  "model": "anthropic/claude-opus-4-8",
  "tool_mode": "rw",
  "dir_scope": "home"
}

Response

{
  "id": "5f3a1b2c8d4e9f0012345678",
  "attached": true,
  "agent": "default",
  "model": "anthropic/claude-opus-4-8",
  "frozen": {
    "realm": "global",
    "container": "local",
    "cwd": "/home/user/projects/api",
    "tool_mode": "rw",
    "dir_scope": "home",
    "backend": ""
  }
}

{
  "code": "delegated_agent_invalid",
  "message": "delegated_agent must be \"claude\""
}

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_blocked`	Realm blocked	The requested realm is blocked or corrupt; the request fails closed before dispatch.	Select a valid, reachable realm.
`realm_corrupt`	Realm record corrupt	The attach target’s persisted realm binding is corrupt.	Recreate the session in a valid realm.
`realm_conflict`	Realm conflict	The supplied realm conflicts with the parent’s (fork) or the session’s frozen (attach) realm binding.	Omit the realm header to inherit, or match the existing binding.
`invalid_realm`	Invalid realm selector	The realm selector is malformed.	Pass a valid realm selector.
`container_conflict`	Container conflict	The supplied container conflicts with the parent’s or the session’s frozen container binding.	Omit the container header to inherit, or match the existing binding.
`delegated_agent_invalid`	Delegated agent invalid	The `delegated_agent` value is not a known BYOA backend.	Use `claude` — the only BYOA backend.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not reach the service through the public endpoint.	Reach the agent through hoody-proxy, not by connecting to the container directly.

{
  "code": "not_found",
  "message": "resource not found"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

{
  "code": "session_busy",
  "message": "session is already live in another connection"
}

Error Code	Title	Description	Resolution
`session_busy`	Session busy	The session is already live in another connection (single-writer-per-session).	Close the other attach, or attach a fork instead.
`session_not_attachable`	Session not attachable	The attach target is a daemon-managed session (e.g. a todo worker) and cannot be attached over HTTP.	Attach a user session, or fork the target instead of attaching it.

{
  "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 cap (default 8 MiB).	Reduce the request body below the configured limit; split into smaller requests.

{
  "code": "cwd_not_found",
  "message": "working directory does not exist"
}

Error Code	Title	Description	Resolution
`cwd_not_found`	Working directory not found	The requested working directory does not exist on the daemon host.	Create the directory or pass an existing cwd.
`container_gone`	Bound container no longer exists	The session’s frozen remote container no longer exists in its realm.	Start a new session and pick another container (or this computer).

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor `Retry-After` and retry.

SDK

await client.agent.sessions.createSession({
  agent: "default",
  cwd: "/home/user/projects/api",
  model: "anthropic/claude-opus-4-8",
  tool_mode: "rw",
  dir_scope: "home"
})

cURL

curl -X POST "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.icu/api/v1/agent/sessions" \
  -H "Content-Type: application/json" \
  -H "X-Hoody-Cwd: /home/user/projects/api" \
  -d '{
    "agent": "default",
    "cwd": "/home/user/projects/api",
    "model": "anthropic/claude-opus-4-8",
    "tool_mode": "rw",
    "dir_scope": "home"
  }'

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

Close the live session connection. Pass ?hard=true to also remove the persisted record. For a session created with a body config_dir override, send the same directory as the X-Hoody-Config-Dir header on a hard delete — otherwise the record resolves under the home sessions dir and returns 404.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`hard`	query	boolean	No	When true, also remove the persisted session record.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override selecting the persisted record store.
`X-Hoody-Container`	header	string	No	Per-request bound remote container.
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected on this route.
`realm`	query	string	No	In-query alias of the `X-Hoody-Realm` header. Rejected on this route.

Response

{
  "closed": true,
  "hard": false,
  "id": "5f3a1b2c8d4e9f0012345678"
}

{
  "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 realm header was supplied to this active-only route.	Omit the realm header on this route, or open a session to scope by realm.
`invalid_realm`	Invalid realm selector	The realm selector is malformed.	Pass a valid realm selector.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not reach the service through the public endpoint.	Reach the agent through hoody-proxy, not by connecting to the container directly.

{
  "code": "not_found",
  "message": "resource not found"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor `Retry-After` and retry.

SDK

await client.agent.sessions.deleteSession("5f3a1b2c8d4e9f0012345678", { hard: true })

cURL

curl -X DELETE "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.icu/api/v1/agent/sessions/5f3a1b2c8d4e9f0012345678?hard=true"

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

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

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container.
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected on this route.
`realm`	query	string	No	In-query alias of the `X-Hoody-Realm` header. Rejected on this route.

Response

{
  "closed": true,
  "id": "5f3a1b2c8d4e9f0012345678"
}

{
  "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 realm header was supplied to this active-only route.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not reach the service through the public endpoint.	Reach the agent through hoody-proxy, not by connecting to the container directly.

{
  "code": "not_found",
  "message": "resource not found"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

{
  "code": "payload_too_large",
  "message": "request body exceeds the configured size limit"
}

Error Code	Title	Description	Resolution
`payload_too_large`	Payload too large	The request body exceeds the configured size cap (default 8 MiB).	Reduce the request body below the configured limit; split into smaller requests.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor `Retry-After` and retry.

SDK

await client.agent.sessions.closeSession("5f3a1b2c8d4e9f0012345678")

cURL

curl -X POST "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.icu/api/v1/agent/sessions/5f3a1b2c8d4e9f0012345678/close"

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

Stop the active turn at the server layer. The session and background tasks are spared (this is distinct from /close). Also aborts an in-flight in-session direct tool run (POST /sessions/{id}/tools/{name}:run) — it holds the same serial turn slot.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container.
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected on this route.
`realm`	query	string	No	In-query alias of the `X-Hoody-Realm` header. Rejected on this route.

Response

{
  "canceled": true,
  "id": "5f3a1b2c8d4e9f0012345678"
}

{
  "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 realm header was supplied to this active-only route.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not reach the service through the public endpoint.	Reach the agent through hoody-proxy, not by connecting to the container directly.

{
  "code": "not_found",
  "message": "resource not found"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

{
  "code": "payload_too_large",
  "message": "request body exceeds the configured size limit"
}

Error Code	Title	Description	Resolution
`payload_too_large`	Payload too large	The request body exceeds the configured size cap (default 8 MiB).	Reduce the request body below the configured limit; split into smaller requests.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor `Retry-After` and retry.

SDK

await client.agent.sessions.cancelSession("5f3a1b2c8d4e9f0012345678")

cURL

curl -X POST "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.icu/api/v1/agent/sessions/5f3a1b2c8d4e9f0012345678/cancel"

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

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

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container.
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected on this route.
`realm`	query	string	No	In-query alias of the `X-Hoody-Realm` header. Rejected on this route.

Request Body

Name	Type	Required	Description
`turn_idx`	integer	No	Turn index to truncate history to (and including).

{
  "turn_idx": 3
}

Response

{
  "trimmed": true,
  "turn_idx": 3
}

{
  "code": "bad_request",
  "message": "invalid turn_idx"
}

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 realm header was supplied to this active-only route.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not reach the service through the public endpoint.	Reach the agent through hoody-proxy, not by connecting to the container directly.

{
  "code": "not_found",
  "message": "resource not found"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

{
  "code": "payload_too_large",
  "message": "request body exceeds the configured size limit"
}

Error Code	Title	Description	Resolution
`payload_too_large`	Payload too large	The request body exceeds the configured size cap (default 8 MiB).	Reduce the request body below the configured limit; split into smaller requests.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor `Retry-After` and retry.

SDK

await client.agent.sessions.trimSession("5f3a1b2c8d4e9f0012345678", { turn_idx: 3 })

cURL

curl -X POST "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.icu/api/v1/agent/sessions/5f3a1b2c8d4e9f0012345678/trim" \
  -H "Content-Type: application/json" \
  -d '{ "turn_idx": 3 }'

Session I/O - reads

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

Read the persisted conversation for a session (live or closed) without attaching. Returns the event.replay message projection plus turn boundaries, fresh to the last persist point. after_turn=N skips completed turns 1..N (exclusive; 0 = full; past-end values clamp).

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`after_turn`	query	integer	No	Exclusive completed-turn skip cursor (0 = full transcript).
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override selecting the record store.
`X-Hoody-Container`	header	string	No	Per-request bound remote container.
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected on this route.
`realm`	query	string	No	In-query alias of the `X-Hoody-Realm` header. Rejected on this route.

Response

{
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "Investigate the failing test." }
      ]
    },
    {
      "role": "assistant",
      "content": [
        { "type": "text", "text": "I'll check the test logs first." },
        { "type": "tool_use", "id": "tool_1", "name": "bash", "input": { "cmd": "cat test.log" } }
      ]
    }
  ],
  "turn_boundaries": [0],
  "turns_total": 4,
  "turns_returned": 3
}

{
  "code": "bad_request",
  "message": "invalid after_turn"
}

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 realm header was supplied to this active-only route.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not reach the service through the public endpoint.	Reach the agent through hoody-proxy, not by connecting to the container directly.

{
  "code": "not_found",
  "message": "resource not found"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

SDK

await client.agent.sessions.getSessionTranscript("5f3a1b2c8d4e9f0012345678", { after_turn: 0 })

cURL

curl -X GET "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.icu/api/v1/agent/sessions/5f3a1b2c8d4e9f0012345678/transcript?after_turn=0"

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

Return 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 instead.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container.
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected on this route.
`realm`	query	string	No	In-query alias of the `X-Hoody-Realm` header. Rejected on this route.

Response

{
  "events": [
    { "seq": 41, "type": "text", "delta": "I'll check the test logs first." },
    { "seq": 42, "type": "tool_use", "name": "bash", "input": { "cmd": "cat test.log" } },
    { "seq": 43, "type": "tool_result", "output": "ok" }
  ],
  "min_seq": 41,
  "max_seq": 43
}

{
  "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 realm header was supplied to this active-only route.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not reach the service through the public endpoint.	Reach the agent through hoody-proxy, not by connecting to the container directly.

{
  "code": "not_found",
  "message": "resource not found"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor `Retry-After` and retry.

SDK

await client.agent.sessions.replaySession("5f3a1b2c8d4e9f0012345678")

cURL

curl -X GET "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.icu/api/v1/agent/sessions/5f3a1b2c8d4e9f0012345678/replay"

`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. Resume from ?since=<seq> or the Last-Event-ID header against 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. WebSocket clients may post inline answer frames (confirm, answer, cancel, workflow_message).

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`since`	query	integer	No	Resume from this gateway int64 seq.
`Last-Event-ID`	header	string	No	SSE resume cursor (the in-header alias of `?since`).
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container.
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected on this route.
`realm`	query	string	No	In-query alias of the `X-Hoody-Realm` header. Rejected on this route.

Response

WebSocket upgrade accepted (WS transport). No body; the connection switches to the WS frame protocol.

event: text
id: 42
data: {"delta":"I'll check the test logs first."}

event: tool_use
id: 43
data: {"name":"bash","input":{"cmd":"cat test.log"}}

{
  "code": "realm_scope_unsupported",
  "message": "realm scope not supported on this route"
}

Error Code	Title	Description	Resolution
`realm_scope_unsupported`	Realm scope unsupported	A per-request realm header was supplied to this active-only route.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not reach the service through the public endpoint.	Reach the agent through hoody-proxy, not by connecting to the container directly.

{
  "code": "not_found",
  "message": "resource not found"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor `Retry-After` and retry.

SDK

await client.agent.sessions.streamSession("5f3a1b2c8d4e9f0012345678", { since: 41 })

cURL

curl -X GET "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.icu/api/v1/agent/sessions/5f3a1b2c8d4e9f0012345678/stream?since=41" \
  -H "Accept: text/event-stream"

Session I/O - writes

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

Dispatch a user turn (fire-and-observe). Returns a job_id; observe agent_done on the session’s stream. A new turn is refused when the session has a parked gate (409 gate_parked) or a turn is already running (409 turn_in_flight) — single-writer, no duplicate parked turns.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container.
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected on this route.
`realm`	query	string	No	In-query alias of the `X-Hoody-Realm` header. Rejected on this route.

Request Body

Name	Type	Required	Description
`text`	string	No	The user message text for this turn.
`tool_mode`	string	No	Optional per-turn tool mode override.
`dir_scope`	string	No	Optional per-turn directory-access scope override: `home` or `full`.

{
  "text": "Investigate the failing auth test."
}

Response

{
  "job_id": "5f3a1b2c8d4e9f001234abcd",
  "status": "dispatched"
}

{
  "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 realm header was supplied to this active-only route.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not reach the service through the public endpoint.	Reach the agent through hoody-proxy, not by connecting to the container directly.

{
  "code": "not_found",
  "message": "resource not found"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

{
  "code": "gate_parked",
  "message": "a gate is parked on this session",
  "details": {
    "pending_gate": {
      "generation": 3,
      "id": "gate-3",
      "type": "confirm"
    }
  }
}

Error Code	Title	Description	Resolution
`gate_parked`	Gate parked	A confirm/question gate is parked on this session. The parked gate is surfaced under `details.pending_gate`.	Answer the parked gate (`/confirm` or `/answer`) and retry.
`turn_in_flight`	Turn in flight	A turn is already running on this session; the single serial turn slot is occupied.	Wait for the running turn to finish (observe `agent_done` on the session stream), then retry.

{
  "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 cap (default 8 MiB).	Reduce the request body below the configured limit; split into smaller requests.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor `Retry-After` and retry.

SDK

await client.agent.sessions.postSessionMessage("5f3a1b2c8d4e9f0012345678", { text: "Investigate the failing auth test." })

cURL

curl -X POST "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.icu/api/v1/agent/sessions/5f3a1b2c8d4e9f0012345678/messages" \
  -H "Content-Type: application/json" \
  -d '{ "text": "Investigate the failing auth test." }'

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

Dispatch a turn and stream the resulting events over SSE from the seq captured just before the dispatch — only this turn’s events. 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.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`policy`	query	string	No	`auto_approve` auto-answers confirm gates for the life of the stream.
`X-Hoody-Gate-Policy`	header	string	No	Confirm-gate posture: `auto_approve` adopts the headless auto-answer posture.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container.
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected on this route.
`realm`	query	string	No	In-query alias of the `X-Hoody-Realm` header. Rejected on this route.

Request Body

Name	Type	Required	Description
`text`	string	No	The user message text for this turn.
`tool_mode`	string	No	Optional per-turn tool mode override.
`dir_scope`	string	No	Optional per-turn directory-access scope override: `home` or `full`.

{
  "text": "Refactor the auth middleware to use async/await."
}

Response

event: text
id: 47
data: {"delta":"I'll start by reading the current middleware."}

event: tool_use
id: 48
data: {"name":"read","input":{"path":"src/middleware/auth.ts"}}

{
  "code": "bad_request",
  "message": "invalid gate policy"
}

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 realm header was supplied to this active-only route.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not reach the service through the public endpoint.	Reach the agent through hoody-proxy, not by connecting to the container directly.

{
  "code": "not_found",
  "message": "resource not found"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

{
  "code": "gate_parked",
  "message": "a gate is parked on this session",
  "details": {
    "pending_gate": {
      "generation": 3,
      "id": "gate-3",
      "type": "confirm"
    }
  }
}

Error Code	Title	Description	Resolution
`gate_parked`	Gate parked	A confirm/question gate is parked on this session.	Answer the parked gate (`/confirm` or `/answer`) and retry.
`turn_in_flight`	Turn in flight	A turn is already running on this session.	Wait for the running turn to finish (observe `agent_done` on the session stream), then retry.

{
  "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 cap (default 8 MiB).	Reduce the request body below the configured limit; split into smaller requests.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	A pre-stream dispatch failure occurred before SSE opened.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor `Retry-After` and retry.

SDK

await client.agent.sessions.promptStream("5f3a1b2c8d4e9f0012345678", { text: "Refactor the auth middleware." })

cURL

curl -X POST "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.icu/api/v1/agent/sessions/5f3a1b2c8d4e9f0012345678/prompt:stream" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{ "text": "Refactor the auth middleware to use async/await." }'

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

Dispatch a turn and block until agent_done. By default (interactive posture) it returns {pending_gate} the moment a turn parks — it NEVER auto-approves implicitly. Repeated prompt:sync against a parked session returns 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 with approved: true — off by default.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`policy`	query	string	No	`auto_approve` adopts the headless auto-answer posture.
`X-Hoody-Gate-Policy`	header	string	No	Confirm-gate posture: `auto_approve` adopts the headless auto-answer posture.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container.
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected on this route.
`realm`	query	string	No	In-query alias of the `X-Hoody-Realm` header. Rejected on this route.

Request Body

Name	Type	Required	Description
`text`	string	No	The user message text for this turn.
`tool_mode`	string	No	Optional per-turn tool mode override.
`dir_scope`	string	No	Optional per-turn directory-access scope override: `home` or `full`.

{
  "text": "Summarize the current test failures."
}

Response

{
  "status": "done",
  "reply": "There are 3 failing tests, all related to token expiry handling."
}

{
  "code": "bad_request",
  "message": "invalid gate policy"
}

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 realm header was supplied to this active-only route.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not reach the service through the public endpoint.	Reach the agent through hoody-proxy, not by connecting to the container directly.

{
  "code": "not_found",
  "message": "resource not found"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

{
  "code": "turn_in_flight",
  "message": "a turn is already running on this session"
}

Error Code	Title	Description	Resolution
`turn_in_flight`	Turn in flight	A turn is already running on this session.	Wait for the running turn to finish, then retry.

{
  "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 cap (default 8 MiB).	Reduce the request body below the configured limit; split into smaller requests.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor `Retry-After` and retry.

SDK

await client.agent.sessions.promptSync("5f3a1b2c8d4e9f0012345678", { text: "Summarize the current test failures." })

cURL

curl -X POST "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.icu/api/v1/agent/sessions/5f3a1b2c8d4e9f0012345678/prompt:sync" \
  -H "Content-Type: application/json" \
  -d '{ "text": "Summarize the current test failures." }'

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

Inject user feedback or input into a running workflow (maps to session.workflow_message -> workflowMsgChan, not commandChan).

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container.
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected on this route.
`realm`	query	string	No	In-query alias of the `X-Hoody-Realm` header. Rejected on this route.

Request Body

Name	Type	Required	Description
`text`	string	No	Feedback/input text fed to the running workflow.

{
  "text": "Stop at step 2 and report progress."
}

Response

{
  "delivered": true,
  "id": "5f3a1b2c8d4e9f0012345678"
}

{
  "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 realm header was supplied to this active-only route.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not reach the service through the public endpoint.	Reach the agent through hoody-proxy, not by connecting to the container directly.

{
  "code": "not_found",
  "message": "resource not found"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

{
  "code": "payload_too_large",
  "message": "request body exceeds the configured size limit"
}

Error Code	Title	Description	Resolution
`payload_too_large`	Payload too large	The request body exceeds the configured size cap (default 8 MiB).	Reduce the request body below the configured limit; split into smaller requests.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor `Retry-After` and retry.

SDK

await client.agent.sessions.postWorkflowMessage("5f3a1b2c8d4e9f0012345678", { text: "Stop at step 2 and report progress." })

cURL

curl -X POST "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.icu/api/v1/agent/sessions/5f3a1b2c8d4e9f0012345678/workflow/messages" \
  -H "Content-Type: application/json" \
  -d '{ "text": "Stop at step 2 and report progress." }'

Gate handling

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

Answer a parked ask-the-user question. Returns 409 no_pending_gate / stale_gate / gate_already_answered / gate_type_mismatch on mismatch.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container.
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected on this route.
`realm`	query	string	No	In-query alias of the `X-Hoody-Realm` header. Rejected on this route.

Request Body

Name	Type	Required	Description
`gate_id`	string	No	Optional echo of the parked gate id (stale/mismatch returns 409).
`generation`	integer	No	Optional echo of the parked gate generation.
`answer`	string	No	Free-form answer text.
`text`	string	No	Alternate answer text field (forwarded alongside `answer`).
`answers`	object	No	Structured per-field answers for a multi-field question.

{
  "gate_id": "gate-3",
  "generation": 3,
  "answer": "Yes, proceed with the migration."
}

Response

{
  "answered": true,
  "gate_id": "gate-3",
  "generation": 3
}

{
  "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 realm header was supplied to this active-only route.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not reach the service through the public endpoint.	Reach the agent through hoody-proxy, not by connecting to the container directly.

{
  "code": "not_found",
  "message": "resource not found"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

{
  "code": "stale_gate",
  "message": "the gate id/generation does not match the parked gate"
}

Error Code	Title	Description	Resolution
`no_pending_gate`	No pending gate	No confirm/question gate is parked for this session.	Dispatch a turn and answer the gate it parks; check the pending gate via `GET /sessions/{id}`.
`stale_gate`	Stale gate	The supplied gate id/generation does not match the currently parked gate.	Re-read the pending gate and answer the current id/generation.
`gate_already_answered`	Gate already answered	The parked gate was already answered by an earlier request (first valid answer wins).	Wait for the next gate; do not re-answer.
`gate_type_mismatch`	Gate type mismatch	The parked gate is a different type than this endpoint answers.	Use the endpoint matching the parked gate type (`/confirm` for a confirm gate, `/answer` for a question gate).

{
  "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 cap (default 8 MiB).	Reduce the request body below the configured limit; split into smaller requests.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

SDK

await client.agent.sessions.answerQuestion("5f3a1b2c8d4e9f0012345678", {
  gate_id: "gate-3",
  generation: 3,
  answer: "Yes, proceed with the migration."
})

cURL

curl -X POST "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.icu/api/v1/agent/sessions/5f3a1b2c8d4e9f0012345678/answer" \
  -H "Content-Type: application/json" \
  -d '{ "gate_id": "gate-3", "generation": 3, "answer": "Yes, proceed with the migration." }'

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

Run 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.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container.
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected on this route.
`realm`	query	string	No	In-query alias of the `X-Hoody-Realm` header. Rejected on this route.

Request Body

Name	Type	Required	Description
`mode`	string	No	Suggestion mode (default `suggest`).
`model`	string	No	Helper model override; empty uses the configured helper.
`gen`	integer	No	Generation counter to correlate the suggestion event.

{
  "mode": "suggest",
  "gen": 3
}

Response

{
  "job_id": "5f3a1b2c8d4e9f001234abce",
  "status": "dispatched"
}

{
  "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 realm header was supplied to this active-only route.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not reach the service through the public endpoint.	Reach the agent through hoody-proxy, not by connecting to the container directly.

{
  "code": "not_found",
  "message": "resource not found"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

{
  "code": "no_pending_gate",
  "message": "no gate is parked for this session"
}

Error Code	Title	Description	Resolution
`no_pending_gate`	No pending gate	No confirm/question gate is parked for this session.	Dispatch a turn and answer the gate it parks; check the pending gate via `GET /sessions/{id}`.
`assist_in_flight`	Assist in flight	An `answer:assist` suggestion job is already running for this session.	Wait for the prior suggestion (observe `event.question_suggestion` / poll the job), then retry.

{
  "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 cap (default 8 MiB).	Reduce the request body below the configured limit; split into smaller requests.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor `Retry-After` and retry.

SDK

await client.agent.sessions.answerAssist("5f3a1b2c8d4e9f0012345678", { mode: "suggest", gen: 3 })

cURL

curl -X POST "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.icu/api/v1/agent/sessions/5f3a1b2c8d4e9f0012345678/answer:assist" \
  -H "Content-Type: application/json" \
  -d '{ "mode": "suggest", "gen": 3 }'

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

Approve or deny a parked tool/dir confirmation. Returns 409 no_pending_gate when nothing is parked; 409 stale_gate / gate_already_answered on mismatch.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container.
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected on this route.
`realm`	query	string	No	In-query alias of the `X-Hoody-Realm` header. Rejected on this route.

Request Body

Name	Type	Required	Description
`gate_id`	string	No	Optional echo of the parked gate id (stale/mismatch returns 409).
`generation`	integer	No	Optional echo of the parked gate generation.
`approved`	boolean	No	`true` to approve, `false` to deny (defaults to `true` if omitted).
`persist_dirs`	boolean	No	Persist an approved directory grant to `settings.json`.

{
  "gate_id": "gate-3",
  "generation": 3,
  "approved": true,
  "persist_dirs": false
}

Response

{
  "answered": true,
  "approved": true,
  "gate_id": "gate-3",
  "generation": 3
}

{
  "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 realm header was supplied to this active-only route.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not reach the service through the public endpoint.	Reach the agent through hoody-proxy, not by connecting to the container directly.

{
  "code": "not_found",
  "message": "resource not found"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

{
  "code": "no_pending_gate",
  "message": "no gate is parked for this session"
}

Error Code	Title	Description	Resolution
`no_pending_gate`	No pending gate	No confirm/question gate is parked for this session.	Dispatch a turn and answer the gate it parks; check the pending gate via `GET /sessions/{id}`.
`stale_gate`	Stale gate	The supplied gate id/generation does not match the currently parked gate.	Re-read the pending gate and answer the current id/generation.
`gate_already_answered`	Gate already answered	The parked gate was already answered by an earlier request (first valid answer wins).	Wait for the next gate; do not re-answer.
`gate_type_mismatch`	Gate type mismatch	The parked gate is a different type than this endpoint answers.	Use the endpoint matching the parked gate type (`/confirm` for a confirm gate, `/answer` for a question gate).

{
  "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 cap (default 8 MiB).	Reduce the request body below the configured limit; split into smaller requests.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

SDK

await client.agent.sessions.confirmGate("5f3a1b2c8d4e9f0012345678", {
  gate_id: "gate-3",
  generation: 3,
  approved: true
})

cURL

curl -X POST "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.icu/api/v1/agent/sessions/5f3a1b2c8d4e9f0012345678/confirm" \
  -H "Content-Type: application/json" \
  -d '{ "gate_id": "gate-3", "generation": 3, "approved": true }'

Live session config

These PATCH endpoints mutate a live session in place. The change is echoed as a session event and observed by attached streams.

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

Switch the chat agent on a live session.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container.
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected on this route.
`realm`	query	string	No	In-query alias of the `X-Hoody-Realm` header. Rejected on this route.

Request Body

Name	Type	Required	Description
`agent`	string	No	Chat-agent name to switch to.

{
  "agent": "code-reviewer"
}

Response

{
  "applied": true,
  "agent": "code-reviewer"
}

{
  "code": "bad_request",
  "message": "invalid agent name"
}

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 realm header was supplied to this active-only route.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not reach the service through the public endpoint.	Reach the agent through hoody-proxy, not by connecting to the container directly.

{
  "code": "not_found",
  "message": "resource not found"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

{
  "code": "payload_too_large",
  "message": "request body exceeds the configured size limit"
}

Error Code	Title	Description	Resolution
`payload_too_large`	Payload too large	The request body exceeds the configured size cap (default 8 MiB).	Reduce the request body below the configured limit; split into smaller requests.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor `Retry-After` and retry.

SDK

await client.agent.sessions.setSessionAgent("5f3a1b2c8d4e9f0012345678", { agent: "code-reviewer" })

cURL

curl -X PATCH "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.icu/api/v1/agent/sessions/5f3a1b2c8d4e9f0012345678/agent" \
  -H "Content-Type: application/json" \
  -d '{ "agent": "code-reviewer" }'

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

Synchronous live model switch. Applies the model inline and returns {status: ok, model, persisted} on success. persisted: false means the frontmatter write failed (the live switch stands but reverts next session). Returns 409 gate_parked / turn_in_flight while busy, 404 for unknown/closed sessions, 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. Peers converge via the emitted init_state event.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container.
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected on this route.
`realm`	query	string	No	In-query alias of the `X-Hoody-Realm` header. Rejected on this route.

Request Body

Name	Type	Required	Description
`model`	string	Yes	Model spec to switch to (provider-prefixed, e.g. `anthropic/claude-opus-4-8`, or `fusion/<slug>`). A blank value is rejected.

{
  "model": "anthropic/claude-opus-4-8"
}

Response

{
  "status": "ok",
  "model": "anthropic/claude-opus-4-8",
  "persisted": true
}

{
  "code": "bad_request",
  "message": "model must not be blank"
}

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 realm header was supplied to this active-only route.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not reach the service through the public endpoint.	Reach the agent through hoody-proxy, not by connecting to the container directly.

{
  "code": "session_not_found",
  "message": "session not found or not live"
}

Error Code	Title	Description	Resolution
`session_not_found`	Session not found	Unknown, closed (including the close-vs-switch race), cross-realm, or foreign-owner session — all collapsed into one code.	List sessions and retry against a live one.

{
  "code": "turn_in_flight",
  "message": "a turn is running (or parked on a gate) — retry when the session is idle"
}

Error Code	Title	Description	Resolution
`gate_parked`	Gate parked	A confirm/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 external agent owns its model; switching is unavailable.	Use the external agent’s own configuration.

{
  "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 cap (default 8 MiB).	Reduce the request body below the configured limit; split into smaller requests.

{
  "code": "model_unavailable",
  "message": "cannot switch to model \"x/y\": unknown provider"
}

Error Code	Title	Description	Resolution
`model_unavailable`	Model unavailable	Unknown model, missing credential, or invalid fusion composite.	Check the spec and provider credentials.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor `Retry-After` and retry.

{
  "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.

SDK

await client.agent.sessions.setSessionModel("5f3a1b2c8d4e9f0012345678", { model: "anthropic/claude-opus-4-8" })

cURL

curl -X PATCH "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.icu/api/v1/agent/sessions/5f3a1b2c8d4e9f0012345678/model" \
  -H "Content-Type: application/json" \
  -d '{ "model": "anthropic/claude-opus-4-8" }'

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

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

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container.
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected on this route.
`realm`	query	string	No	In-query alias of the `X-Hoody-Realm` header. Rejected on this route.

Request Body

Name	Type	Required	Description
`effort`	string	No	`low` / `medium` / `high` / `xhigh`, or `""` for the model default.

{
  "effort": "high"
}

Response

{
  "applied": true,
  "effort": "high"
}

{
  "code": "bad_request",
  "message": "invalid effort level"
}

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 realm header was supplied to this active-only route.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not reach the service through the public endpoint.	Reach the agent through hoody-proxy, not by connecting to the container directly.

{
  "code": "not_found",
  "message": "resource not found"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

{
  "code": "payload_too_large",
  "message": "request body exceeds the configured size limit"
}

Error Code	Title	Description	Resolution
`payload_too_large`	Payload too large	The request body exceeds the configured size cap (default 8 MiB).	Reduce the request body below the configured limit; split into smaller requests.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor `Retry-After` and retry.

SDK

await client.agent.sessions.setSessionEffort("5f3a1b2c8d4e9f0012345678", { effort: "high" })

cURL

curl -X PATCH "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.icu/api/v1/agent/sessions/5f3a1b2c8d4e9f0012345678/effort" \
  -H "Content-Type: application/json" \
  -d '{ "effort": "high" }'

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

Live verbosity change. Accepts normal, concise, terse, or minimal.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container.
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected on this route.
`realm`	query	string	No	In-query alias of the `X-Hoody-Realm` header. Rejected on this route.

Request Body

Name	Type	Required	Description
`level`	string	No	`normal` / `concise` / `terse` / `minimal`.

{
  "level": "concise"
}

Response

{
  "applied": true,
  "level": "concise"
}

{
  "code": "bad_request",
  "message": "invalid verbosity level"
}

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 realm header was supplied to this active-only route.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not reach the service through the public endpoint.	Reach the agent through hoody-proxy, not by connecting to the container directly.

{
  "code": "not_found",
  "message": "resource not found"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

{
  "code": "payload_too_large",
  "message": "request body exceeds the configured size limit"
}

Error Code	Title	Description	Resolution
`payload_too_large`	Payload too large	The request body exceeds the configured size cap (default 8 MiB).	Reduce the request body below the configured limit; split into smaller requests.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor `Retry-After` and retry.

SDK

await client.agent.sessions.setSessionVerbosity("5f3a1b2c8d4e9f0012345678", { level: "concise" })

cURL

curl -X PATCH "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.icu/api/v1/agent/sessions/5f3a1b2c8d4e9f0012345678/verbosity" \
  -H "Content-Type: application/json" \
  -d '{ "level": "concise" }'

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

Arm or disarm the self-driving auto-reply loop. Configures the round budget, the replier model, and the write-class opt-in.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container.
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected on this route.
`realm`	query	string	No	In-query alias of the `X-Hoody-Realm` header. Rejected on this route.

Request Body

Name	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.
`allow_writes`	boolean	No	Opt in to write-class actions during auto-reply.

{
  "armed": true,
  "rounds": 5,
  "model": "anthropic/claude-haiku-4-5",
  "allow_writes": false
}

Response

{
  "applied": true,
  "armed": true,
  "rounds": 5,
  "model": "anthropic/claude-haiku-4-5",
  "allow_writes": false
}

{
  "code": "bad_request",
  "message": "invalid auto-reply config"
}

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 realm header was supplied to this active-only route.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not reach the service through the public endpoint.	Reach the agent through hoody-proxy, not by connecting to the container directly.

{
  "code": "not_found",
  "message": "resource not found"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

{
  "code": "payload_too_large",
  "message": "request body exceeds the configured size limit"
}

Error Code	Title	Description	Resolution
`payload_too_large`	Payload too large	The request body exceeds the configured size cap (default 8 MiB).	Reduce the request body below the configured limit; split into smaller requests.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor `Retry-After` and retry.

SDK

await client.agent.sessions.setSessionAutoReply("5f3a1b2c8d4e9f0012345678", {
  armed: true,
  rounds: 5,
  model: "anthropic/claude-haiku-4-5",
  allow_writes: false
})

cURL

curl -X PATCH "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.icu/api/v1/agent/sessions/5f3a1b2c8d4e9f0012345678/auto-reply" \
  -H "Content-Type: application/json" \
  -d '{ "armed": true, "rounds": 5, "model": "anthropic/claude-haiku-4-5", "allow_writes": false }'

`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).

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container.
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected on this route.
`realm`	query	string	No	In-query alias of the `X-Hoody-Realm` header. Rejected on this route.

Request Body

Name	Type	Required	Description
`allow_writes`	boolean	No	New write-class opt-in state.

{
  "allow_writes": true
}

Response

{
  "applied": true,
  "allow_writes": true
}

{
  "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 realm header was supplied to this active-only route.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not reach the service through the public endpoint.	Reach the agent through hoody-proxy, not by connecting to the container directly.

{
  "code": "not_found",
  "message": "resource not found"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

{
  "code": "payload_too_large",
  "message": "request body exceeds the configured size limit"
}

Error Code	Title	Description	Resolution
`payload_too_large`	Payload too large	The request body exceeds the configured size cap (default 8 MiB).	Reduce the request body below the configured limit; split into smaller requests.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor `Retry-After` and retry.

SDK

await client.agent.sessions.setSessionAutoReplyWrites("5f3a1b2c8d4e9f0012345678", { allow_writes: true })

cURL

curl -X PATCH "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.icu/api/v1/agent/sessions/5f3a1b2c8d4e9f0012345678/auto-reply/writes" \
  -H "Content-Type: application/json" \
  -d '{ "allow_writes": true }'

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

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

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	Path identifier.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container.
`X-Hoody-Realm`	header	string	No	Per-request realm selector. Rejected on this route.
`realm`	query	string	No	In-query alias of the `X-Hoody-Realm` header. Rejected on this route.

Request Body

Name	Type	Required	Description
`enabled`	boolean	No	Whether to inject the `HOODY_*` shell-env contract.

{
  "enabled": false
}

Response

{
  "applied": true,
  "enabled": false
}

{
  "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 realm header was supplied to this active-only route.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not reach the service through the public endpoint.	Reach the agent through hoody-proxy, not by connecting to the container directly.

{
  "code": "not_found",
  "message": "resource not found"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

{
  "code": "payload_too_large",
  "message": "request body exceeds the configured size limit"
}

Error Code	Title	Description	Resolution
`payload_too_large`	Payload too large	The request body exceeds the configured size cap (default 8 MiB).	Reduce the request body below the configured limit; split into smaller requests.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request.	Honor `Retry-After` and retry.

SDK

await client.agent.sessions.setSessionHoodyEnv("5f3a1b2c8d4e9f0012345678", { enabled: false })

cURL

curl -X PATCH "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.icu/api/v1/agent/sessions/5f3a1b2c8d4e9f0012345678/hoody-env" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": false }'