# Agent: Discovery

**Page:** api/agent/discovery

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

---

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



## Agent: Discovery

The Discovery endpoints let an agent enumerate the realms and containers it is allowed to bind to before opening a session. Both are read-only, `global-read` operations — they are not part of Fleet management, and they exist solely to help a caller pick a valid target for `POST /api/v1/agent/sessions`.


Both endpoints accept the same per-request scope headers (`X-Hoody-Cwd`, `X-Hoody-Config-Dir`, `X-Hoody-Container`, `X-Hoody-Realm`). The realm-scope header is rejected on active-only / no-realm routes with `realm_scope_unsupported`.


## `GET /api/v1/agent/realms`

Lists the realms visible to the calling token (wrapper for `hoody.list_realms`), each annotated with `active` / `blocked` flags so the caller can pick a valid bind target.

### 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. |
| `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 query-string alias of the `X-Hoody-Realm` header, read only when the header is absent. |

This endpoint accepts no request body.

### SDK usage

```ts
const page = await client.agent.discovery.listRealmsIterator({
  page: 1,
  limit: 50,
});
```

### Response



```json
{
  "items": [
    {
      "id": "5f1b2c3d4e5f6a7b8c9d0e1f",
      "name": "production-eu",
      "active": true,
      "blocked": false,
      "createdAt": "2025-08-12T09:14:22Z"
    },
    {
      "id": "a1b2c3d4e5f6a7b8c9d0e1f2",
      "name": "staging-us",
      "active": true,
      "blocked": false,
      "createdAt": "2025-09-03T17:02:11Z"
    }
  ],
  "meta": {
    "total": 2,
    "page": 1,
    "limit": 50
  }
}
```

| Field | Type | Description |
|-------|------|-------------|
| `items` | array | The page of realms; each element is the forwarded daemon row's own shape. |
| `meta` | object | Pagination metadata. |
| `meta.total` | integer | Total number of items across all pages. |
| `meta.page` | integer | 1-based page number (present only when `limit` > 0). |
| `meta.limit` | integer | Items per page (present only when `limit` > 0). |


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

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


```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 arrive through `hoody-proxy`: its source IP is private/local. Authorization is owned by `hoody-proxy`. | Reach the agent through `hoody-proxy` (e.g. `hoody agent …` → platform → proxy), not by connecting to the container directly. |


```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; the gateway throttled the request before dispatch. | 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. |


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



## `GET /api/v1/agent/containers`

Lists the containers inside a selected realm (wrapper for `hoody.list_containers`) so a caller can pick a bind target. The realm is selected with `?realm=<id>` (or the `X-Hoody-Realm` header). `global-read`; read-only — not part of Fleet management.

### 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. |
| `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 query-string alias of the `X-Hoody-Realm` header, read only when the header is absent. |

This endpoint accepts no request body.

### SDK usage

```ts
const page = await client.agent.discovery.listContainersIterator({
  realm: "5f1b2c3d4e5f6a7b8c9d0e1f",
  page: 1,
  limit: 50,
});
```

### Response



```json
{
  "items": [
    {
      "id": "c1d2e3f4a5b6c7d8e9f0a1b2",
      "name": "api-gateway-01",
      "realmId": "5f1b2c3d4e5f6a7b8c9d0e1f",
      "status": "running",
      "bound": false
    },
    {
      "id": "d2e3f4a5b6c7d8e9f0a1b2c3",
      "name": "worker-03",
      "realmId": "5f1b2c3d4e5f6a7b8c9d0e1f",
      "status": "running",
      "bound": true
    }
  ],
  "meta": {
    "total": 2,
    "page": 1,
    "limit": 50
  }
}
```

| Field | Type | Description |
|-------|------|-------------|
| `items` | array | The page of containers; each element is the forwarded daemon row's own shape. |
| `meta` | object | Pagination metadata. |
| `meta.total` | integer | Total number of items across all pages. |
| `meta.page` | integer | 1-based page number (present only when `limit` > 0). |
| `meta.limit` | integer | Items per page (present only when `limit` > 0). |


```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, which has no realm dimension to scope. | 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 arrive through `hoody-proxy`: its source IP is private/local. Authorization is owned by `hoody-proxy`. | Reach the agent through `hoody-proxy` (e.g. `hoody agent …` → platform → proxy), not by connecting to the container directly. |


```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; the gateway throttled the request before dispatch. | 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. |


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