# 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

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.



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


```ts
await client.agent.system.healthCheck();
```


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



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


```ts
await client.agent.system.metrics();
```


```text
# 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
```


```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 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. |


```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. |



## `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.



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


```ts
await client.agent.system.openapiJSON();
```


```json
{
  "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"
}
```


```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 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. |


```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. |



## `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.



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


```ts
await client.agent.system.openapiYAML();
```


```yaml
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
```


```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 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. |


```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. |



## `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.



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


```ts
await client.agent.system.docs();
```


```html
<!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>
```


```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 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. |


```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. |