Agent: System

Operational endpoints for the agent service — standardized health check, Prometheus metrics, the live OpenAPI spec (JSON/YAML), and the API documentation UI. Use these endpoints for monitoring, observability, and API discovery.

`GET` `/api/v1/agent/docs`

API documentation UI. Renders the Swagger/Redoc UI for the agent’s OpenAPI document. Auth-gated; no conformance weight; may be dropped.

This endpoint takes no parameters.

"<!DOCTYPE html><html><head><title>Agent API</title>…</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 arrive through hoody-proxy: its source IP is private/local (in-container loopback, the bridge, the host, or a sibling container). The gateway has no service-level auth — authorization is owned by hoody-proxy, which is the only party that can reach it (TPROXY preserves the real public client IP). Kit network-position trust.	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.

cURL
SDK

curl -X GET 'https://api.hoody.com/api/v1/agent/docs'

const html = await client.agent.system.docs();

`GET` `/api/v1/agent/health`

Kit-wide standardized health check. The only unauthenticated route; always returns HTTP 200 JSON. Returns a 9-field health payload.

This endpoint takes no parameters.

{
  "status": "ok",
  "uptime": 12345,
  "version": "1.2.3",
  "build": "abc1234",
  "startedAt": "2024-01-15T10:00:00Z",
  "hostname": "agent-pod-7f8d9",
  "pid": 42,
  "memory": {
    "rss": 134217728,
    "heapTotal": 67108864,
    "heapUsed": 41943040
  },
  "deps": {
    "daemon": "reachable",
    "store": "reachable"
  }
}

cURL
SDK

curl -X GET 'https://api.hoody.com/api/v1/agent/health'

const health = await client.agent.system.healthCheck();

`GET` `/api/v1/agent/metrics`

Prometheus metrics. Returns Prometheus text exposition of the hoody_agent_* metric series. Namespaced per operator hard-req #1.

This endpoint takes no parameters.

# HELP hoody_agent_requests_total Total number of agent requests
# TYPE hoody_agent_requests_total counter
hoody_agent_requests_total{operation="health",status="200"} 1234
hoody_agent_requests_total{operation="metrics",status="200"} 567
# 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",operation="health"} 1100
hoody_agent_request_duration_seconds_bucket{le="0.01",operation="health"} 1200
hoody_agent_request_duration_seconds_bucket{le="+Inf",operation="health"} 1234
hoody_agent_request_duration_seconds_sum{operation="health"} 12.345
hoody_agent_request_duration_seconds_count{operation="health"} 1234

{
  "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 (in-container loopback, the bridge, the host, or a sibling container). The gateway has no service-level auth — authorization is owned by hoody-proxy, which is the only party that can reach it (TPROXY preserves the real public client IP). Kit network-position trust.	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.

cURL
SDK

curl -X GET 'https://api.hoody.com/api/v1/agent/metrics'

const metrics = await client.agent.system.metrics();

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

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

This endpoint takes no parameters.

{
  "openapi": "3.1.0",
  "info": {
    "title": "Hoody Agent API",
    "version": "1.2.3",
    "description": "Hoody agent service API."
  },
  "servers": [
    {
      "url": "https://api.hoody.com",
      "description": "Production"
    }
  ],
  "paths": {
    "/api/v1/agent/health": {
      "get": {
        "summary": "Standardized health check.",
        "operationId": "agent_healthCheck"
      }
    }
  },
  "components": {
    "schemas": {},
    "securitySchemes": {}
  }
}

{
  "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 (in-container loopback, the bridge, the host, or a sibling container). The gateway has no service-level auth — authorization is owned by hoody-proxy, which is the only party that can reach it (TPROXY preserves the real public client IP). Kit network-position trust.	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.

cURL
SDK

curl -X GET 'https://api.hoody.com/api/v1/agent/openapi.json'

const spec = await client.agent.system.openapiJSON();

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

Live-generated OpenAPI 3.1 document (YAML). info is pinned to the top. Fully namespaced; no bare alias.

This endpoint takes no parameters.

openapi: 3.1.0
info:
  title: Hoody Agent API
  version: 1.2.3
  description: Hoody agent service API.
servers:
  - url: https://api.hoody.com
    description: Production
paths:
  /api/v1/agent/health:
    get:
      summary: Standardized health check.
      operationId: agent_healthCheck
components:
  schemas: {}
  securitySchemes: {}

{
  "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 (in-container loopback, the bridge, the host, or a sibling container). The gateway has no service-level auth — authorization is owned by hoody-proxy, which is the only party that can reach it (TPROXY preserves the real public client IP). Kit network-position trust.	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.

cURL
SDK

curl -X GET 'https://api.hoody.com/api/v1/agent/openapi.yaml'

const spec = await client.agent.system.openapiYAML();

Agent: System

GET /api/v1/agent/docs

GET /api/v1/agent/health

GET /api/v1/agent/metrics

GET /api/v1/agent/openapi.json

GET /api/v1/agent/openapi.yaml

`GET` `/api/v1/agent/docs`

`GET` `/api/v1/agent/health`

`GET` `/api/v1/agent/metrics`

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

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