# Agent: Chat Agents

**Page:** api/agent/agents

[Download Raw Markdown](./api/agent/agents.md)

---

{/* AUTO-GENERATED — Do not edit manually. Regenerate with: npm run docs:api:generate */}



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

#### SDK




```bash
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"
```




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




#### Responses




```json
{
  "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
  }
}
```




```json
{
  "code": "bad_request",
  "message": "invalid request"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `bad_request` | Bad request | The request was malformed or carried invalid parameters. | Correct the request body or query parameters. |
| `realm_scope_unsupported` | Realm scope unsupported | A per-request 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. |




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




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

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




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

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




### `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




```bash
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"
```




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




#### Responses




```json
{
  "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
}
```




```json
{
  "code": "bad_request",
  "message": "invalid request"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `bad_request` | Bad request | The request was malformed or carried invalid parameters. | Correct the request body or query parameters. |
| `realm_scope_unsupported` | Realm scope unsupported | A per-request 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. |




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




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

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




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

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




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

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




```json
{
  "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




```bash
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."
  }'
```




```javascript
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




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




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




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




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

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




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

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




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

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




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

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




```json
{
  "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




```bash
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
  }'
```




```javascript
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




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




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




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




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

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




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

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




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

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




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

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




```json
{
  "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




```bash
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" }'
```




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




#### Responses




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




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




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




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




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

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `payload_too_large` | Payload too large | The request body exceeds the configured size cap (default 8 MiB). | Reduce the request body below the limit. |




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

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




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

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




```json
{
  "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




```bash
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" }'
```




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




#### Responses




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




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




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




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




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

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `payload_too_large` | Payload too large | The request body exceeds the configured size cap (default 8 MiB). | Reduce the request body below the limit. |




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

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




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

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




```json
{
  "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




```bash
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"
```




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




#### Responses




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




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




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




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




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

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `payload_too_large` | Payload too large | The request body exceeds the configured size cap (default 8 MiB). | Reduce the request body below the limit. |




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

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




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

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




## 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




```bash
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" }'
```




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




#### Responses




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




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




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




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




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

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `payload_too_large` | Payload too large | The request body exceeds the configured size cap (default 8 MiB). | Reduce the request body below the limit. |




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

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




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

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




```json
{
  "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




```bash
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"] }'
```




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




#### Responses




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




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




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




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




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

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `payload_too_large` | Payload too large | The request body exceeds the configured size cap (default 8 MiB). | Reduce the request body below the limit. |




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

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




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

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




```json
{
  "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




```bash
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 }'
```




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




#### Responses




```json
{
  "name": "code-reviewer",
  "tool": "Bash",
  "enabled": false
}
```




```json
{
  "code": "bad_request",
  "message": "invalid request"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `bad_request` | Bad request | The request was malformed or carried invalid parameters. | Correct the request body or query parameters. |
| `realm_scope_unsupported` | Realm scope unsupported | A per-request 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. |




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




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




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

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `payload_too_large` | Payload too large | The request body exceeds the configured size cap (default 8 MiB). | Reduce the request body below the limit. |




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

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




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

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




```json
{
  "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




```bash
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 }'
```




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




#### Responses




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




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




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




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




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

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `payload_too_large` | Payload too large | The request body exceeds the configured size cap (default 8 MiB). | Reduce the request body below the limit. |




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

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




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

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




```json
{
  "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




```bash
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"
```




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




#### Responses




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




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




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




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




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

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




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

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





The `reset-to-shipped` and `delete` endpoints return the daemon's reply in the tool `{ output, is_error }` envelope. The HTTP status remains 200 even when the daemon-level action reports `is_error: true`; inspect the body to distinguish success from refusal.