Agent: Chat Agents

Download Page (.md)

The Agent Chat Agents API manages chat-agent definitions: list, create, copy, rename, reset, edit source, configure model/tools/turns, and delete. Each agent is a markdown file with frontmatter (model, tools, turns) and a system prompt. Results are realm-scoped to the gateway’s own realm; a client-supplied X-Hoody-Realm is ignored on these routes.

All endpoints live under the agent gateway at https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.icu.

Listing & Reading

`GET /api/v1/agent/agents`

List chat-agent definitions resolved for the requesting cwd/config_dir (built-in + custom). Supports pagination via page and limit.

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.
`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). Ignored on this realm-scoped route.
`realm`	query	string	No	In-query alias of `X-Hoody-Realm`.

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

await client.agent.agents.listAgentsIterator({ page: 1, limit: 20 });

Responses

{
  "items": [
    {
      "name": "code-reviewer",
      "description": "Reviews pull requests against the project style guide.",
      "model": "anthropic/claude-opus-4-8",
      "tools": ["Read", "Grep", "Bash"],
      "turns": 25,
      "origin": "custom"
    },
    {
      "name": "general-purpose",
      "description": "Default Hoody assistant agent.",
      "model": "anthropic/claude-sonnet-4-6",
      "tools": [],
      "turns": 50,
      "origin": "shipped"
    }
  ],
  "meta": {
    "total": 2,
    "page": 1,
    "limit": 20
  }
}

{
  "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 reach the service through the public endpoint.	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.	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.

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

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

Parameters

Name	In	Type	Required	Description
`name`	path	string	Yes	Agent name.
`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. Ignored on this scope.
`realm`	query	string	No	In-query alias of `X-Hoody-Realm`.

SDK

cURL
SDK

curl -X GET "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.icu/api/v1/agent/agents/code-reviewer/source" \
  -H "X-Hoody-Cwd: /home/user/project"

await client.agent.agents.getAgentSource("code-reviewer");

Responses

{
  "name": "code-reviewer",
  "content": "---\nmodel: anthropic/claude-sonnet-4-6\ntools: [Read, Grep, Bash]\nturns: 25\ndescription: Reviews pull requests against the project style guide.\n---\n\nYou are a meticulous code reviewer. Score each PR against the style guide, list issues in priority order, and never approve work you have not actually read.",
  "gen": 12
}

{
  "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 reach the service through the public endpoint.	Reach the agent through `hoody-proxy`.

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

{
  "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 (busy or concurrency cap hit).	Honor `Retry-After` and retry.

Creating & Editing Source

`POST /api/v1/agent/agents`

Create (or overwrite) a custom chat-agent definition from a name, frontmatter, and system prompt.

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. Ignored on this scope.
`realm`	query	string	No	In-query alias of `X-Hoody-Realm`.

Request Body

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

SDK

cURL
SDK

curl -X POST "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.icu/api/v1/agent/agents" \
  -H "Content-Type: application/json" \
  -H "X-Hoody-Cwd: /home/user/project" \
  -d '{
    "name": "docs-writer",
    "frontmatter": {
      "model": "anthropic/claude-sonnet-4-6",
      "tools": ["Read", "Write"],
      "turns": 20,
      "description": "Drafts and edits project documentation."
    },
    "system_prompt": "You are a technical writer. Use concise, action-oriented language and follow the project docs style guide."
  }'

await client.agent.agents.createAgent({
  name: "docs-writer",
  frontmatter: {
    model: "anthropic/claude-sonnet-4-6",
    tools: ["Read", "Write"],
    turns: 20,
    description: "Drafts and edits project documentation."
  },
  system_prompt: "You are a technical writer. Use concise, action-oriented language and follow the project docs style guide."
});

Responses

{
  "name": "docs-writer",
  "path": "/home/user/.hoody/agents/docs-writer.md",
  "created": true
}

{
  "code": "bad_request",
  "message": "name is required"
}

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 reach the service through the public endpoint.	Reach the agent through `hoody-proxy`.

{
  "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`, default 8 MiB).	Reduce the request body below the limit; 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.	Honor the `Retry-After` header and retry.

{
  "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 (busy or concurrency cap hit).	Honor `Retry-After` and retry.

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

Overwrite the raw markdown source of a chat-agent definition. Pass base_gen (returned by getAgentSource) for conflict detection.

Parameters

Name	In	Type	Required	Description
`name`	path	string	Yes	Agent name.
`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. Ignored on this scope.
`realm`	query	string	No	In-query alias of `X-Hoody-Realm`.

Request Body

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

SDK

cURL
SDK

curl -X PUT "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.icu/api/v1/agent/agents/code-reviewer/source" \
  -H "Content-Type: application/json" \
  -H "X-Hoody-Cwd: /home/user/project" \
  -d '{
    "content": "---\nmodel: anthropic/claude-opus-4-8\ntools: [Read, Grep, Bash]\nturns: 30\n---\n\nYou are a meticulous code reviewer.",
    "base_gen": 12
  }'

await client.agent.agents.putAgentSource("code-reviewer", {
  content: "---\nmodel: anthropic/claude-opus-4-8\ntools: [Read, Grep, Bash]\nturns: 30\n---\n\nYou are a meticulous code reviewer.",
  base_gen: 12
});

Responses

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

{
  "code": "bad_request",
  "message": "content is required"
}

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 reach the service through the public endpoint.	Reach the agent through `hoody-proxy`.

{
  "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 limit; 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.	Honor the `Retry-After` header and retry.

{
  "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 (busy or concurrency cap hit).	Honor `Retry-After` and retry.

Duplicating, Renaming, Resetting

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

Copy a chat-agent definition to a new name. The source {name} comes from the path; the destination is given in the body.

Parameters

Name	In	Type	Required	Description
`name`	path	string	Yes	Source agent name.
`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. Ignored on this scope.
`realm`	query	string	No	In-query alias of `X-Hoody-Realm`.

Request Body

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

SDK

cURL
SDK

curl -X POST "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.icu/api/v1/agent/agents/code-reviewer/copy" \
  -H "Content-Type: application/json" \
  -H "X-Hoody-Cwd: /home/user/project" \
  -d '{ "new_name": "code-reviewer-strict" }'

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

Responses

{
  "source": "code-reviewer",
  "destination": "code-reviewer-strict",
  "copied": true
}

{
  "code": "bad_request",
  "message": "new_name is required"
}

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 reach the service through the public endpoint.	Reach the agent through `hoody-proxy`.

{
  "code": "not_found",
  "message": "source agent 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 limit.

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

{
  "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 (busy or concurrency cap hit).	Honor `Retry-After` and retry.

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

Rename a custom chat-agent definition. The current {name} comes from the path; the new name is given in the body.

Parameters

Name	In	Type	Required	Description
`name`	path	string	Yes	Current agent name.
`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. Ignored on this scope.
`realm`	query	string	No	In-query alias of `X-Hoody-Realm`.

Request Body

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

SDK

cURL
SDK

curl -X POST "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.icu/api/v1/agent/agents/code-reviewer-strict/rename" \
  -H "Content-Type: application/json" \
  -H "X-Hoody-Cwd: /home/user/project" \
  -d '{ "new_name": "strict-reviewer" }'

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

Responses

{
  "from": "code-reviewer-strict",
  "to": "strict-reviewer",
  "renamed": true
}

{
  "code": "bad_request",
  "message": "new_name is required"
}

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 reach the service through the public endpoint.	Reach the agent through `hoody-proxy`.

{
  "code": "not_found",
  "message": "agent 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 limit.

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

{
  "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 (busy or concurrency cap hit).	Honor `Retry-After` and retry.

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

Restore one agent to its shipped default, discarding local customizations. Agents with no shipped default are refused (is_error: true).

Parameters

Name	In	Type	Required	Description
`name`	path	string	Yes	Agent name.
`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. Ignored on this scope.
`realm`	query	string	No	In-query alias of `X-Hoody-Realm`.

SDK

cURL
SDK

curl -X POST "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.icu/api/v1/agent/agents/general-purpose/reset-to-shipped" \
  -H "X-Hoody-Cwd: /home/user/project"

await client.agent.agents.resetAgentToShipped("general-purpose");

Responses

{
  "output": "agent 'general-purpose' restored to shipped default",
  "is_error": false
}

{
  "code": "bad_request",
  "message": "no shipped default for this agent"
}

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.	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 reach the service through the public endpoint.	Reach the agent through `hoody-proxy`.

{
  "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 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 (default 8 MiB).	Reduce the request body below the limit.

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

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

Configuration

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

Set (or, with model: "", remove) an agent’s frontmatter model line.

Parameters

Name	In	Type	Required	Description
`name`	path	string	Yes	Agent name.
`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. Ignored on this scope.
`realm`	query	string	No	In-query alias of `X-Hoody-Realm`.

Request Body

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

SDK

cURL
SDK

curl -X PATCH "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.icu/api/v1/agent/agents/code-reviewer/model" \
  -H "Content-Type: application/json" \
  -H "X-Hoody-Cwd: /home/user/project" \
  -d '{ "model": "anthropic/claude-opus-4-8" }'

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

Responses

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

{
  "code": "bad_request",
  "message": "invalid model spec"
}

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 reach the service through the public endpoint.	Reach the agent through `hoody-proxy`.

{
  "code": "not_found",
  "message": "agent 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 limit.

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

{
  "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 (busy or concurrency cap hit).	Honor `Retry-After` and retry.

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

Set (or, with an empty list, remove — meaning “all tools”) an agent’s frontmatter tools line.

Parameters

Name	In	Type	Required	Description
`name`	path	string	Yes	Agent name.
`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. Ignored on this scope.
`realm`	query	string	No	In-query alias of `X-Hoody-Realm`.

Request Body

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

SDK

cURL
SDK

curl -X PATCH "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.icu/api/v1/agent/agents/code-reviewer/tools" \
  -H "Content-Type: application/json" \
  -H "X-Hoody-Cwd: /home/user/project" \
  -d '{ "tools": ["Read", "Grep", "Bash", "Glob"] }'

await client.agent.agents.setAgentTools("code-reviewer", { tools: ["Read", "Grep", "Bash", "Glob"] });

Responses

{
  "name": "code-reviewer",
  "tools": ["Read", "Grep", "Bash", "Glob"],
  "applied": true
}

{
  "code": "bad_request",
  "message": "tools must be an array of strings"
}

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 reach the service through the public endpoint.	Reach the agent through `hoody-proxy`.

{
  "code": "not_found",
  "message": "agent 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 limit.

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

{
  "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 (busy or concurrency cap hit).	Honor `Retry-After` and retry.

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

Toggle a single tool on or off in an agent’s frontmatter tools line. Pass an optional enabled boolean in the body to set explicitly; omit it to flip the current state.

Parameters

Name	In	Type	Required	Description
`name`	path	string	Yes	Agent name.
`tool`	path	string	Yes	Tool name.
`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. Ignored on this scope.
`realm`	query	string	No	In-query alias of `X-Hoody-Realm`.

Request Body

The request body is a free-form object forwarded to the daemon. Reserved _-prefixed keys are ignored. The accepted fields are exactly those the operation reads; an optional enabled flag may be supplied (omit to flip the current state).

SDK

cURL
SDK

curl -X POST "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.icu/api/v1/agent/agents/code-reviewer/tools/Bash/toggle" \
  -H "Content-Type: application/json" \
  -H "X-Hoody-Cwd: /home/user/project" \
  -d '{ "enabled": false }'

await client.agent.agents.toggleAgentTool("code-reviewer", "Bash", { enabled: false });

Responses

{
  "name": "code-reviewer",
  "tool": "Bash",
  "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 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 reach the service through the public endpoint.	Reach the agent through `hoody-proxy`.

{
  "code": "not_found",
  "message": "agent 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 limit.

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

{
  "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 (busy or concurrency cap hit).	Honor `Retry-After` and retry.

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

Set an agent’s turns frontmatter value (max agent turns per dispatch).

Parameters

Name	In	Type	Required	Description
`name`	path	string	Yes	Agent name.
`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. Ignored on this scope.
`realm`	query	string	No	In-query alias of `X-Hoody-Realm`.

Request Body

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

SDK

cURL
SDK

curl -X PATCH "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.icu/api/v1/agent/agents/code-reviewer/turns" \
  -H "Content-Type: application/json" \
  -H "X-Hoody-Cwd: /home/user/project" \
  -d '{ "turns": 40 }'

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

Responses

{
  "name": "code-reviewer",
  "turns": 40,
  "applied": true
}

{
  "code": "bad_request",
  "message": "turns must be a positive integer"
}

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 reach the service through the public endpoint.	Reach the agent through `hoody-proxy`.

{
  "code": "not_found",
  "message": "agent 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 limit.

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

{
  "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 (busy or concurrency cap hit).	Honor `Retry-After` and retry.

Deletion

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

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

Parameters

Name	In	Type	Required	Description
`name`	path	string	Yes	Agent name.
`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. Ignored on this scope.
`realm`	query	string	No	In-query alias of `X-Hoody-Realm`.

SDK

cURL
SDK

curl -X DELETE "https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.icu/api/v1/agent/agents/docs-writer" \
  -H "X-Hoody-Cwd: /home/user/project"

await client.agent.agents.deleteAgent("docs-writer");

Responses

{
  "output": "agent 'docs-writer' deleted",
  "is_error": false
}

{
  "code": "bad_request",
  "message": "cannot delete the default chat agent"
}

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.	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 reach the service through the public endpoint.	Reach the agent through `hoody-proxy`.

{
  "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 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.	Honor the `Retry-After` header and retry.

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