Agent: Chat Agents

The chat-agent endpoints manage chat-agent definitions stored under the resolving working directory. They expose list / create / copy / rename / delete lifecycle, read / write of the raw markdown source, and targeted frontmatter edits for the model, tool allow-list, and max-turns. Every read is realm-scoped to the gateway’s own realm; a client-supplied X-Hoody-Realm header is ignored. Mutating endpoints require a mutating posture on the daemon side.

List chat-agent definitions

GET /api/v1/agent/agents

Lists the chat-agent definitions resolved for the requesting cwd / config_dir (built-in + custom). Realm-scoped to the gateway’s own realm; a client-supplied realm selector is ignored.

Parameters

Name	In	Type	Required	Description
`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 (§6.1): the `.hoody` project layer / record cwd / tool+workflow cwd. Required by routes that resolve a cwd.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override (§6.1) selecting which on-disk `.hoody` install a stateless read/write resolves.
`X-Hoody-Container`	header	string	No	Per-request bound remote container (§6.1; omitted = local). Rejected (400) on routes with no container dimension.
`X-Hoody-Realm`	header	string	No	Per-request realm selector (§6.1): `"global"` or a 24-hex id (also accepted as `?realm=`). Rejected (400 `realm_scope_unsupported`) on active-only / no-realm routes.
`realm`	query	string	No	Per-request realm selector (§6.1) — the in:query alias of the `X-Hoody-Realm` header (read only when the header is absent): `"global"` or a 24-hex id.

Response

{
  "items": [
    {
      "name": "code-reviewer",
      "description": "Reviews PRs and suggests improvements",
      "model": "anthropic/claude-opus-4-8",
      "tools": ["read_file", "grep", "bash"],
      "turns": 25
    },
    {
      "name": "explorer",
      "description": "Explores a codebase to answer questions",
      "model": "anthropic/claude-sonnet-4-5",
      "tools": ["read_file", "list_dir", "grep"],
      "turns": 15
    }
  ],
  "meta": {
    "total": 12,
    "page": 1,
    "limit": 50
  }
}

{
  "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 an active-only / global-no-realm RPC, which has no realm dimension to scope.	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 arrive through hoody-proxy: its source IP is private/local (in-container loopback, the bridge, the host, or a sibling container). The gateway has no service-level auth — authorization is owned by hoody-proxy, which is the only party that can reach it (TPROXY preserves the real public client IP). Kit network-position trust.	Reach the agent through hoody-proxy (e.g. `hoody agent …` → platform → 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; the gateway throttled the request before dispatch.	Honor the `Retry-After` header and retry; reduce the request rate.

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

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

SDK

const { items, meta } = await client.agent.agents.listAgentsIterator({ page: 1, limit: 50 });

Read a chat agent’s source

GET /api/v1/agent/agents/{name}/source

Returns the raw markdown source (frontmatter + system prompt) of a chat-agent definition.

Parameters

Name	In	Type	Required	Description
`name`	path	string	Yes	Path identifier (the agent name).
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope (§6.1).
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override (§6.1).
`X-Hoody-Container`	header	string	No	Per-request bound remote container (§6.1; omitted = local).
`X-Hoody-Realm`	header	string	No	Per-request realm selector (§6.1).
`realm`	query	string	No	Per-request realm selector (§6.1) — the in:query alias of the `X-Hoody-Realm` header.

Response

{
  "name": "code-reviewer",
  "content": "---\nmodel: anthropic/claude-opus-4-8\ntools: [read_file, grep, bash]\nturns: 25\ndescription: Reviews PRs and suggests improvements\n---\n\nYou are a code reviewer. Read the diff, identify issues, and propose targeted fixes.\n",
  "gen": 7
}

{
  "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 an active-only / global-no-realm RPC.	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 arrive through hoody-proxy.	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; the gateway throttled the request before dispatch.	Honor the `Retry-After` header and retry; reduce the request rate.

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

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

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

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request (too busy, or a per-client stream concurrency cap was hit).	Honor `Retry-After` and retry.

SDK

const source = await client.agent.agents.getAgentSource({ name: "code-reviewer" });

Create a chat-agent definition

POST /api/v1/agent/agents

Creates (or overwrites) a custom chat-agent definition file from a name + frontmatter + system prompt.

Parameters

Name	In	Type	Required	Description
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope (§6.1).
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override (§6.1).
`X-Hoody-Container`	header	string	No	Per-request bound remote container (§6.1; omitted = local).
`X-Hoody-Realm`	header	string	No	Per-request realm selector (§6.1).
`realm`	query	string	No	Per-request realm selector (§6.1) — the in:query alias of the `X-Hoody-Realm` header.

Request Body

Field	Type	Required	Description
`name`	string	Yes	Agent name (the definition file stem).
`frontmatter`	object	No	Optional frontmatter keys (model / tools / turns / description).
`system_prompt`	string	No	The agent’s system prompt body.

{
  "name": "code-reviewer",
  "frontmatter": {
    "model": "anthropic/claude-opus-4-8",
    "tools": ["read_file", "grep", "bash"],
    "turns": 25,
    "description": "Reviews PRs and suggests improvements"
  },
  "system_prompt": "You are a code reviewer. Read the diff, identify issues, and propose targeted fixes."
}

Response

{
  "name": "code-reviewer",
  "path": "/home/user/project/.hoody/agents/code-reviewer.md",
  "created": 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 an active-only / global-no-realm RPC.	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 arrive through hoody-proxy.	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 (MaxBodyBytes). The gateway rejects an oversized body at the edge before the handler reads it.	Reduce the request body below the configured limit (default 8 MiB); split a large payload into smaller requests.

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

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

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

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

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

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request (too busy, or a per-client stream concurrency cap was hit).	Honor `Retry-After` and retry.

SDK

await client.agent.agents.createAgent({
  data: {
    name: "code-reviewer",
    frontmatter: {
      model: "anthropic/claude-opus-4-8",
      tools: ["read_file", "grep", "bash"],
      turns: 25,
      description: "Reviews PRs and suggests improvements"
    },
    system_prompt: "You are a code reviewer. Read the diff, identify issues, and propose targeted fixes."
  }
});

Copy a chat agent

POST /api/v1/agent/agents/{name}/copy

Copies a chat-agent definition to a new name.

Parameters

Name	In	Type	Required	Description
`name`	path	string	Yes	Path identifier (the source agent name).
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope (§6.1).
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override (§6.1).
`X-Hoody-Container`	header	string	No	Per-request bound remote container (§6.1; omitted = local).
`X-Hoody-Realm`	header	string	No	Per-request realm selector (§6.1).
`realm`	query	string	No	Per-request realm selector (§6.1) — the in:query alias of the `X-Hoody-Realm` header.

Request Body

Field	Type	Required	Description
`new_name`	string	Yes	Name for the copied agent.

{
  "new_name": "code-reviewer-strict"
}

Response

{
  "name": "code-reviewer-strict",
  "path": "/home/user/project/.hoody/agents/code-reviewer-strict.md",
  "source": "code-reviewer"
}

{
  "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 an active-only / global-no-realm RPC.	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 arrive through hoody-proxy.	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 (MaxBodyBytes).	Reduce the request body below the configured limit (default 8 MiB); split a large payload into smaller requests.

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

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

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

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

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

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request (too busy, or a per-client stream concurrency cap was hit).	Honor `Retry-After` and retry.

SDK

await client.agent.agents.copyAgent({
  name: "code-reviewer",
  data: { new_name: "code-reviewer-strict" }
});

Rename a chat agent

POST /api/v1/agent/agents/{name}/rename

Renames a custom chat-agent definition.

Parameters

Name	In	Type	Required	Description
`name`	path	string	Yes	Path identifier (the current agent name).
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope (§6.1).
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override (§6.1).
`X-Hoody-Container`	header	string	No	Per-request bound remote container (§6.1; omitted = local).
`X-Hoody-Realm`	header	string	No	Per-request realm selector (§6.1).
`realm`	query	string	No	Per-request realm selector (§6.1) — the in:query alias of the `X-Hoody-Realm` header.

Request Body

Field	Type	Required	Description
`new_name`	string	Yes	New agent name.

{
  "new_name": "code-reviewer-v2"
}

Response

{
  "name": "code-reviewer-v2",
  "old_name": "code-reviewer"
}

{
  "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 an active-only / global-no-realm RPC.	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 arrive through hoody-proxy.	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 (MaxBodyBytes).	Reduce the request body below the configured limit (default 8 MiB); split a large payload into smaller requests.

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

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

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

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

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

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request (too busy, or a per-client stream concurrency cap was hit).	Honor `Retry-After` and retry.

SDK

await client.agent.agents.renameAgent({
  name: "code-reviewer",
  data: { new_name: "code-reviewer-v2" }
});

Reset an agent to its shipped default

POST /api/v1/agent/agents/{name}/reset-to-shipped

Restores one agent to its shipped default, discarding local customizations. An agent with no shipped default is refused.

Parameters

Name	In	Type	Required	Description
`name`	path	string	Yes	Path identifier (the agent name).
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope (§6.1).
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override (§6.1).
`X-Hoody-Container`	header	string	No	Per-request bound remote container (§6.1; omitted = local).
`X-Hoody-Realm`	header	string	No	Per-request realm selector (§6.1).
`realm`	query	string	No	Per-request realm selector (§6.1) — the in:query alias of the `X-Hoody-Realm` header.

Response

{
  "output": "Agent 'code-reviewer' reset to shipped default.",
  "is_error": 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.
`tool_mutation_refused`	Tool mutation refused	A sessionless tool run resolved to a mutating tool with no confirmation posture. Sessionless runs are read-only by default.	Open a session and run the tool there, or supply `allow_mutations:true` / `confirm:true` on the sessionless run.
`realm_scope_unsupported`	Realm scope unsupported	A per-request realm header was supplied to an active-only / global-no-realm RPC.	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 arrive through hoody-proxy.	Reach the agent through hoody-proxy, not by connecting to the container directly.

{
  "code": "tool_not_found",
  "message": "no tool with that name"
}

Error Code	Title	Description	Resolution
`tool_not_found`	Tool not found	No tool with the given name exists in the catalogue or in the session’s effective tool list.	List the catalogue (`GET /tools`) or the session’s tools (`GET /sessions/{id}/tools`) and use a valid name.

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

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

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

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

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

SDK

await client.agent.agents.resetAgentToShipped({ name: "code-reviewer" });

Toggle a single tool for an agent

POST /api/v1/agent/agents/{name}/tools/{tool}/toggle

Toggles one tool on/off in an agent’s frontmatter tools line. Omit enabled to flip the current state; supply an explicit enabled to force on/off.

Parameters

Name	In	Type	Required	Description
`name`	path	string	Yes	Path identifier (the agent name).
`tool`	path	string	Yes	Path identifier (the tool name).
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope (§6.1).
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override (§6.1).
`X-Hoody-Container`	header	string	No	Per-request bound remote container (§6.1; omitted = local).
`X-Hoody-Realm`	header	string	No	Per-request realm selector (§6.1).
`realm`	query	string	No	Per-request realm selector (§6.1) — the in:query alias of the `X-Hoody-Realm` header.

Request Body

The body is a free-form pass-through to the daemon agents.toggle_tool RPC. Accepted fields are exactly those agents.toggle_tool reads; the most common is enabled.

{
  "enabled": true
}

Response

{
  "name": "code-reviewer",
  "tool": "bash",
  "enabled": 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 an active-only / global-no-realm RPC.	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 arrive through hoody-proxy.	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 (MaxBodyBytes).	Reduce the request body below the configured limit (default 8 MiB); split a large payload into smaller requests.

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

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

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

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

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

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request (too busy, or a per-client stream concurrency cap was hit).	Honor `Retry-After` and retry.

SDK

await client.agent.agents.toggleAgentTool({
  name: "code-reviewer",
  tool: "bash",
  data: { enabled: true }
});

Write a chat agent’s source

PUT /api/v1/agent/agents/{name}/source

Overwrites the raw markdown source of a chat-agent definition. Supply base_gen from a prior read to opt into conflict detection.

Parameters

Name	In	Type	Required	Description
`name`	path	string	Yes	Path identifier (the agent name).
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope (§6.1).
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override (§6.1).
`X-Hoody-Container`	header	string	No	Per-request bound remote container (§6.1; omitted = local).
`X-Hoody-Realm`	header	string	No	Per-request realm selector (§6.1).
`realm`	query	string	No	Per-request realm selector (§6.1) — the in:query alias of the `X-Hoody-Realm` header.

Request Body

Field	Type	Required	Description
`content`	string	Yes	The full markdown source (frontmatter + system prompt).
`base_gen`	integer	No	The `gen` returned by `agents.read_source`, for conflict detection.

{
  "content": "---\nmodel: anthropic/claude-sonnet-4-5\ntools: [read_file, grep]\nturns: 20\ndescription: Reviews PRs with a strict lens\n---\n\nYou are a strict code reviewer. Reject any change that lacks tests.\n",
  "base_gen": 7
}

Response

{
  "name": "code-reviewer",
  "gen": 8
}

{
  "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 an active-only / global-no-realm RPC.	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 arrive through hoody-proxy.	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 (MaxBodyBytes).	Reduce the request body below the configured limit (default 8 MiB); split a large payload into smaller requests.

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

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

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

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

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

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request (too busy, or a per-client stream concurrency cap was hit).	Honor `Retry-After` and retry.

SDK

await client.agent.agents.putAgentSource({
  name: "code-reviewer",
  data: {
    content: "---\nmodel: anthropic/claude-sonnet-4-5\ntools: [read_file, grep]\nturns: 20\ndescription: Reviews PRs with a strict lens\n---\n\nYou are a strict code reviewer. Reject any change that lacks tests.\n",
    base_gen: 7
  }
});

Set an agent’s model

PATCH /api/v1/agent/agents/{name}/model

Sets (or, with model: "", removes) an agent’s frontmatter model line.

Parameters

Name	In	Type	Required	Description
`name`	path	string	Yes	Path identifier (the agent name).
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope (§6.1).
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override (§6.1).
`X-Hoody-Container`	header	string	No	Per-request bound remote container (§6.1; omitted = local).
`X-Hoody-Realm`	header	string	No	Per-request realm selector (§6.1).
`realm`	query	string	No	Per-request realm selector (§6.1) — the in:query alias of the `X-Hoody-Realm` header.

Request Body

Field	Type	Required	Description
`model`	string	No	Model spec (e.g. `anthropic/claude-opus-4-8`); `""` removes the frontmatter model line.

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

Response

{
  "name": "code-reviewer",
  "model": "anthropic/claude-opus-4-8"
}

{
  "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 an active-only / global-no-realm RPC.	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 arrive through hoody-proxy.	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 (MaxBodyBytes).	Reduce the request body below the configured limit (default 8 MiB); split a large payload into smaller requests.

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

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

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

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

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

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request (too busy, or a per-client stream concurrency cap was hit).	Honor `Retry-After` and retry.

SDK

await client.agent.agents.setAgentModel({
  name: "code-reviewer",
  data: { model: "anthropic/claude-opus-4-8" }
});

Set an agent’s tool allow-list

PATCH /api/v1/agent/agents/{name}/tools

Sets (or, with an empty list, removes — “all tools”) an agent’s frontmatter tools line.

Parameters

Name	In	Type	Required	Description
`name`	path	string	Yes	Path identifier (the agent name).
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope (§6.1).
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override (§6.1).
`X-Hoody-Container`	header	string	No	Per-request bound remote container (§6.1; omitted = local).
`X-Hoody-Realm`	header	string	No	Per-request realm selector (§6.1).
`realm`	query	string	No	Per-request realm selector (§6.1) — the in:query alias of the `X-Hoody-Realm` header.

Request Body

Field	Type	Required	Description
`tools`	array	No	Tool names allowed for the agent; an empty list removes the line (= all tools).

{
  "tools": ["read_file", "grep", "bash"]
}

Response

{
  "name": "code-reviewer",
  "tools": ["read_file", "grep", "bash"]
}

{
  "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 an active-only / global-no-realm RPC.	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 arrive through hoody-proxy.	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 (MaxBodyBytes).	Reduce the request body below the configured limit (default 8 MiB); split a large payload into smaller requests.

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

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

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

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

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

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request (too busy, or a per-client stream concurrency cap was hit).	Honor `Retry-After` and retry.

SDK

await client.agent.agents.setAgentTools({
  name: "code-reviewer",
  data: { tools: ["read_file", "grep", "bash"] }
});

Set an agent’s max-turns

PATCH /api/v1/agent/agents/{name}/turns

Sets an agent’s max-turns frontmatter value.

Parameters

Name	In	Type	Required	Description
`name`	path	string	Yes	Path identifier (the agent name).
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope (§6.1).
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override (§6.1).
`X-Hoody-Container`	header	string	No	Per-request bound remote container (§6.1; omitted = local).
`X-Hoody-Realm`	header	string	No	Per-request realm selector (§6.1).
`realm`	query	string	No	Per-request realm selector (§6.1) — the in:query alias of the `X-Hoody-Realm` header.

Request Body

Field	Type	Required	Description
`turns`	integer	No	Max agent turns per dispatch.

{
  "turns": 30
}

Response

{
  "name": "code-reviewer",
  "turns": 30
}

{
  "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 an active-only / global-no-realm RPC.	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 arrive through hoody-proxy.	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 (MaxBodyBytes).	Reduce the request body below the configured limit (default 8 MiB); split a large payload into smaller requests.

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

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

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

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

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

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request (too busy, or a per-client stream concurrency cap was hit).	Honor `Retry-After` and retry.

SDK

await client.agent.agents.setAgentTurns({
  name: "code-reviewer",
  data: { turns: 30 }
});

Delete a custom chat agent

DELETE /api/v1/agent/agents/{name}

Deletes one custom chat-agent definition. Shipped-default agents and the configured default chat agent are refused by the daemon guard rails (use putAgentSource or resetAgentToShipped instead).

Parameters

Name	In	Type	Required	Description
`name`	path	string	Yes	Path identifier (the agent name).
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope (§6.1).
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override (§6.1).
`X-Hoody-Container`	header	string	No	Per-request bound remote container (§6.1; omitted = local).
`X-Hoody-Realm`	header	string	No	Per-request realm selector (§6.1).
`realm`	query	string	No	Per-request realm selector (§6.1) — the in:query alias of the `X-Hoody-Realm` header.

Response

{
  "output": "Agent 'code-reviewer' deleted.",
  "is_error": 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.
`tool_mutation_refused`	Tool mutation refused	A sessionless tool run resolved to a mutating tool with no confirmation posture. Sessionless runs are read-only by default.	Open a session and run the tool there, or supply `allow_mutations:true` / `confirm:true` on the sessionless run.
`realm_scope_unsupported`	Realm scope unsupported	A per-request realm header was supplied to an active-only / global-no-realm RPC.	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 arrive through hoody-proxy.	Reach the agent through hoody-proxy, not by connecting to the container directly.

{
  "code": "tool_not_found",
  "message": "no tool with that name"
}

Error Code	Title	Description	Resolution
`tool_not_found`	Tool not found	No tool with the given name exists in the catalogue or in the session’s effective tool list.	List the catalogue (`GET /tools`) or the session’s tools (`GET /sessions/{id}/tools`) and use a valid name.

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

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

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

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

SDK

await client.agent.agents.deleteAgent({ name: "code-reviewer" });