Agent: System

The agent system namespace exposes the standardized observability and introspection surface that every Hoody container agent implements. Use these endpoints for unauthenticated health probes, Prometheus scraping, discovering the live API contract (JSON or YAML), and rendering the in-container API reference UI.

All routes are reached through the hoody-proxy on the standard per-project, per-container hostname: {projectId}-{containerId}-agent-1.{server}.containers.hoody.com.

Health and metrics

`GET /api/v1/agent/health`

Standardized health check. The only unauthenticated route on the agent. Always returns HTTP 200 with the kit-wide 9-field health payload.

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.system.healthCheck();

{
  "status": "ok",
  "uptime_s": 86432,
  "version": "1.42.0",
  "build_sha": "a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4",
  "started_at": "2026-01-14T08:00:12Z",
  "container_id": "890abcdef12345678901cdef",
  "kit": "agent",
  "proxy": "connected",
  "daemon": "ok"
}

`GET /api/v1/agent/metrics`

Prometheus exposition of the hoody_agent_* series. Returns the metrics in the standard Prometheus text format, suitable for direct scraping.

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.system.metrics();

# HELP hoody_agent_requests_total Total number of agent requests.
# TYPE hoody_agent_requests_total counter
hoody_agent_requests_total{action="execute"} 1242
hoody_agent_requests_total{action="health"} 87
# HELP hoody_agent_up Whether the agent is reachable (1) or not (0).
# TYPE hoody_agent_up gauge
hoody_agent_up 1

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

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	Forbidden — 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.

OpenAPI and reference UI

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

Live-generated OpenAPI 3.1 document for the agent. Includes Hoody x-* extensions. Fully namespaced — the document is never served at a bare alias.

This endpoint takes no parameters.

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

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.system.openapiJSON();

{
  "openapi": "3.1.0",
  "info": {
    "title": "Hoody Container Agent API",
    "version": "1.42.0",
    "description": "Live OpenAPI document for the agent instance."
  },
  "x-hoody-namespace": "agent",
  "paths": {
    "/api/v1/agent/health": {
      "get": {
        "operationId": "agent_healthCheck",
        "summary": "Standardized health check."
      }
    }
  }
}

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

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	Forbidden — 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 for the agent in YAML. The info block is pinned to the top of the document. Fully namespaced — never served at a bare alias.

This endpoint takes no parameters.

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

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.system.openapiYAML();

openapi: 3.1.0
info:
  title: Hoody Container Agent API
  version: 1.42.0
  description: Live OpenAPI document for the agent instance.
x-hoody-namespace: agent
paths:
  /api/v1/agent/health:
    get:
      operationId: agent_healthCheck
      summary: Standardized health check.

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

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	Forbidden — 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`

Renders the interactive API documentation UI for the agent. Returns an HTML page when the UI is enabled.

This endpoint takes no parameters.

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

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.system.docs();

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>Hoody Agent API</title>
  </head>
  <body>
    <div id="swagger-ui"></div>
    <script src="/assets/swagger-ui.js"></script>
  </body>
</html>

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

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	Forbidden — 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.