Agent: System

The agent service exposes operational endpoints for monitoring and observability: a standardized health check for liveness probes and uptime monitors, a Prometheus metrics endpoint for scraping time-series data, and a version endpoint that reports the HTTP API contract version, build version, session protocol version, and capability list. All three endpoints are served directly by the container agent.

Health check

`GET /api/v1/agent/health`

Returns the kit-wide 9-field health payload. The response is the gateway’s own health payload; nothing here comes from the daemon. Always returns HTTP 200 with status: "ok".

This endpoint takes no parameters.

curl https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/health

import { HoodyClient } from 'hoody-sdk';

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

await client.agent.kit.getHealth();

{
  "status": "ok",
  "service": "hoody-agent",
  "built": "2026-01-12T08:30:00Z",
  "started": "2026-01-15T10:22:17Z",
  "memory": {
    "rss": 67108864,
    "heap": null
  },
  "fds": 18,
  "pid": 142,
  "ip": "203.0.113.42",
  "userAgent": "kube-probe/1.29"
}

Prometheus metrics

`GET /api/v1/agent/metrics`

Returns the Prometheus text exposition of the hoody_agent_* metric series. The endpoint is intended for a Prometheus scraper or compatible collector.

This endpoint takes no parameters.

curl https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/metrics

import { HoodyClient } from 'hoody-sdk';

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

await client.agent.kit.getMetrics();

# HELP hoody_agent_up Whether the agent process is up (1) or down (0).
# TYPE hoody_agent_up gauge
hoody_agent_up 1

# HELP hoody_agent_requests_total Total number of agent requests handled.
# TYPE hoody_agent_requests_total counter
hoody_agent_requests_total{result="ok"} 12847
hoody_agent_requests_total{result="error"} 23

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (Source IP Guard)	The request did not come through the program’s URL. Hoody Kit programs are reached through their URLs only.	Call the agent through its URL, for example with `hoody agent …`.

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

Agent API version

`GET /api/v1/agent/version`

Returns the HTTP API contract version (api_version), the build version, the session protocol version, the gateway’s realm pin (pinned_realm), and the capability list (one row per feature a client may depend on, each with supported (this build knows it) and available (its route or event is mounted here)). Answered by the gateway alone; no daemon call is involved. The response carries Cache-Control: no-store so a proxy never serves a stale capability list across a deploy.

Parameters

Name	In	Type	Required	Description
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope: the `.hoody` project layer / record cwd / tool and workflow cwd. Required by routes that resolve a cwd (for example `POST /todos`; `todos.create` also accepts a body `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 with `400` on routes with no container dimension.

curl https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.com/api/v1/agent/version

import { HoodyClient } from 'hoody-sdk';

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

await client.agent.kit.getVersion();

{
  "api_version": "1.4.2",
  "build_version": "1.4.2+abcdef0",
  "session_protocol_version": 2,
  "capabilities": [
    { "name": "agent.session", "supported": true, "available": true },
    { "name": "agent.system.healthCheck", "supported": true, "available": true },
    { "name": "agent.system.metrics", "supported": true, "available": true },
    { "name": "agent.system.getAgentVersion", "supported": true, "available": true }
  ]
}

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

Error Code	Title	Description	Resolution
`bad_request`	Bad request	The request was malformed or carried invalid parameters.	Correct the request body or query parameters.
`realm_scope_unsupported`	Realm scope unsupported	A per-request realm header was supplied to an active-only / global-no-realm RPC, which has no realm dimension to scope.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (Source IP Guard)	The request did not come through the program’s URL. Hoody Kit programs are reached through their URLs only.	Call the agent through its URL, for example with `hoody agent …`.

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

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

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

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

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

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

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

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