# Agent: System **Page:** api/agent/system [Download Raw Markdown](./api/agent/system.md) --- {/* AUTO-GENERATED — Do not edit manually. Regenerate with: npm run docs:api:generate */} ## 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. ```json "Agent API…" ``` ```json { "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. | ```json { "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. | ```json { "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. | ```bash curl -X GET 'https://api.hoody.com/api/v1/agent/docs' ``` ```ts 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. ```json { "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" } } ``` ```bash curl -X GET 'https://api.hoody.com/api/v1/agent/health' ``` ```ts 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. ```text # 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 ``` ```json { "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. | ```json { "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. | ```bash curl -X GET 'https://api.hoody.com/api/v1/agent/metrics' ``` ```ts 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. ```json { "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": {} } } ``` ```json { "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. | ```json { "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. | ```json { "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. | ```bash curl -X GET 'https://api.hoody.com/api/v1/agent/openapi.json' ``` ```ts 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. ```yaml 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: {} ``` ```json { "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. | ```json { "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. | ```bash curl -X GET 'https://api.hoody.com/api/v1/agent/openapi.yaml' ``` ```ts const spec = await client.agent.system.openapiYAML(); ```