Agent: Discovery

List realms and the containers within a realm to bind an agent session to a target environment. These read-only endpoints expose the same discovery data as the in-process hoody.list_realms and hoody.list_containers helpers. Both routes are global-read — they are not part of Fleet management and return paginated envelopes suitable for populating a bind-target picker.

Note

All requests must arrive through the Hoody proxy. Direct connections to the container are rejected with forbidden. The agent’s per-realm scope is supplied via the X-Hoody-Realm header (or its ?realm= query alias), but these discovery routes are themselves realm-agnostic — sending a realm header returns realm_scope_unsupported.

GET /api/v1/agent/realms

Lists the realms visible to the token, with active and blocked flags, so a caller can pick a valid bind target for POST /sessions. Global-read; 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).
realm	query	string	No	Per-request realm selector — the query alias of the X-Hoody-Realm header. Accepted: "global" or a 24-hex id. Rejected (400 realm_scope_unsupported) on this route because the discovery endpoints have no realm dimension to scope.
X-Hoody-Cwd	header	string	No	Per-request working-directory scope: the .hoody project layer / record cwd / tool+workflow cwd.
X-Hoody-Config-Dir	header	string	No	Per-request --config-dir override selecting which on-disk .hoody install a stateless read/write resolves (HoodyPaths).
X-Hoody-Container	header	string	No	Per-request bound remote container (omitted = local). Rejected (400) on routes with no container dimension.
X-Hoody-Realm	header	string	No	Per-request realm selector: "global" or a 24-hex id (also accepted as ?realm=). Rejected (400 realm_scope_unsupported) on this route.

Response

200

{
  "items": [
    {
      "id": "890abcdef12345678901cdef",
      "name": "production",
      "active": true,
      "blocked": false
    },
    {
      "id": "abcdef12345678901cdef67",
      "name": "staging",
      "active": true,
      "blocked": false
    },
    {
      "id": "123def45678901cdef67abc",
      "name": "archive",
      "active": false,
      "blocked": true
    }
  ],
  "meta": {
    "total": 3,
    "page": 1,
    "limit": 20
  }
}

400

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

403

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

404

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

429

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

500

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

503

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

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

SDK Example

cURL

curl -X GET 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/realms' \
  -H 'Authorization: Bearer <token>'

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

for await (const realm of client.agent.discovery.listRealmsIterator()) {
  console.log(realm.id, realm.name, realm.active);
}

GET /api/v1/agent/containers

Lists the containers in a realm so a caller can pick a bind target. The realm is selected with ?realm=<id> (or the X-Hoody-Realm header); omit both to list globally. Global-read; 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).
realm	query	string	No	Per-request realm selector — the query alias of the X-Hoody-Realm header. Accepted: "global" or a 24-hex id. Filters the returned containers to the requested realm.
X-Hoody-Cwd	header	string	No	Per-request working-directory scope: the .hoody project layer / record cwd / tool+workflow cwd.
X-Hoody-Config-Dir	header	string	No	Per-request --config-dir override selecting which on-disk .hoody install a stateless read/write resolves (HoodyPaths).
X-Hoody-Container	header	string	No	Per-request bound remote container (omitted = local). Rejected (400) on routes with no container dimension.
X-Hoody-Realm	header	string	No	Per-request realm selector: "global" or a 24-hex id (also accepted as ?realm=). Filters the returned containers to the requested realm.

Response

200

{
  "items": [
    {
      "id": "67e89abc123def456789abcd",
      "name": "prod-runner-01",
      "realm": "890abcdef12345678901cdef",
      "status": "active",
      "endpoint": "wss://67e89abc123def456789abcd-890abcdef12345678901cdef-agent-1.node-us.containers.hoody.com"
    },
    {
      "id": "890abcdef12345678901cdef",
      "name": "staging-runner-02",
      "realm": "890abcdef12345678901cdef",
      "status": "active",
      "endpoint": "wss://67e89abc123def456789abcd-890abcdef12345678901cdef-agent-1.node-us.containers.hoody.com"
    }
  ],
  "meta": {
    "total": 2,
    "page": 1,
    "limit": 20
  }
}

400

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

403

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

404

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

429

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

500

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

503

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

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

SDK Example

cURL

curl -X GET 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/containers?realm=890abcdef12345678901cdef&limit=20' \
  -H 'Authorization: Bearer <token>' \
  -H 'X-Hoody-Realm: 890abcdef12345678901cdef'

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

for await (const container of client.agent.discovery.listContainersIterator({ realm: '890abcdef12345678901cdef', limit: 20 })) {
  console.log(container.id, container.name, container.status);
}