Agent: System

The agent service exposes a small set of operational endpoints used by the platform, observability tooling, and external API consumers. This page covers the standardized health check, the Prometheus metrics scrape, the live OpenAPI 3.1 document (JSON and YAML), and the interactive API documentation UI. The health endpoint is the only unauthenticated route in the service; the others must be reached through the Hoody proxy.

All endpoints live under the agent’s container-scoped subdomain:

https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.icu

`GET /api/v1/agent/health`

Standardized health check. Returns the kit-wide 9-field health payload. This is the only unauthenticated route in the agent; the response is always HTTP 200 JSON.

This endpoint takes no parameters.

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

await client.agent.system.healthCheck();

{
  "status": "ok",
  "version": "1.4.2",
  "uptime_s": 84213,
  "started_at": "2026-01-08T11:02:17Z",
  "container_id": "agent-1",
  "project_id": "proj_a8f3e2",
  "build_sha": "9d1c4b7",
  "runtime": "node",
  "checks": {
    "daemon": "ok",
    "storage": "ok"
  }
}

`GET /api/v1/agent/metrics`

Prometheus metrics. Returns the text exposition of the hoody_agent_* series, suitable for scraping by a Prometheus server.

This endpoint takes no parameters.

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

await client.agent.system.metrics();

# HELP hoody_agent_up Agent process is up and serving requests.
# TYPE hoody_agent_up gauge
hoody_agent_up 1
# HELP hoody_agent_requests_total Total HTTP requests handled by the agent.
# TYPE hoody_agent_requests_total counter
hoody_agent_requests_total{endpoint="/api/v1/agent/health",method="GET",status="200"} 1284
hoody_agent_requests_total{endpoint="/api/v1/agent/metrics",method="GET",status="200"} 57
# HELP hoody_agent_request_duration_seconds Request duration in seconds.
# TYPE hoody_agent_request_duration_seconds histogram
hoody_agent_request_duration_seconds_bucket{le="0.005"} 920
hoody_agent_request_duration_seconds_bucket{le="0.01"} 1240
hoody_agent_request_duration_seconds_bucket{le="+Inf"} 1341
hoody_agent_request_duration_seconds_sum 18.432
hoody_agent_request_duration_seconds_count 1341

{
  "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; the gateway throttled the request before dispatch.	Honor the Retry-After header and retry; reduce the request rate.

`GET /api/v1/agent/openapi.json`

Live-generated OpenAPI 3.1 document with Hoody x-* extensions. Fully namespaced; no bare alias. Returned as JSON.

This endpoint takes no parameters.

curl https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.icu/api/v1/agent/openapi.json

await client.agent.system.openapiJSON();

{
  "openapi": "3.1.0",
  "info": {
    "title": "Hoody Agent API",
    "version": "1.4.2",
    "description": "Agent service API reference."
  },
  "paths": {
    "/api/v1/agent/health": {
      "get": {
        "summary": "Standardized health check.",
        "responses": {
          "200": {
            "description": "Standardized health payload."
          }
        }
      }
    }
  },
  "x-hoody-namespace": "agent.system"
}

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

`GET /api/v1/agent/openapi.yaml`

Live-generated OpenAPI 3.1 document in YAML. The info block is pinned to the top of the document. Fully namespaced; no bare alias.

This endpoint takes no parameters.

curl https://{projectId}-{containerId}-agent-1.{server}.containers.hoody.icu/api/v1/agent/openapi.yaml

await client.agent.system.openapiYAML();

info:
  title: Hoody Agent API
  version: 1.4.2
  description: Agent service API reference.
openapi: 3.1.0
paths:
  /api/v1/agent/health:
    get:
      summary: Standardized health check.
      responses:
        "200":
          description: Standardized health payload.
x-hoody-namespace: agent.system

{
  "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; the gateway throttled the request before dispatch.	Honor the Retry-After header and retry; reduce the request rate.

`GET /api/v1/agent/docs`

Interactive API documentation UI. Returns the rendered HTML page that can be opened in a browser. May be disabled on some deployments.

This endpoint takes no parameters.

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

await client.agent.system.docs();

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Hoody Agent API</title>
  </head>
  <body>
    <main id="swagger-ui">
      <h1>Hoody Agent API</h1>
    </main>
  </body>
</html>

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