Health & Status API

Platform health, status, and metrics endpoints.

Endpoints

Method	Path	Description
GET	`/health`	Health report (bypasses IP allowlist)
GET	`/status`	Detailed daemon status
GET	`/metrics`	Prometheus metrics

GET /health

Returns a structured health report. This endpoint is always accessible regardless of IP allowlist configuration (orchestrator probes must work).

Request

curl http://localhost:4200/health

Response (200 OK)

{
  "status": "healthy",
  "uptime_secs": 51735,
  "agents": {
    "running": 5,
    "suspended": 1,
    "total": 6
  },
  "providers": {
    "healthy": 3,
    "degraded": 0,
    "unavailable": 0
  },
  "memory": {
    "state": "healthy"
  }
}

Status Values

Value	Meaning
`healthy`	All subsystems operating normally
`degraded`	At least one subsystem degraded, none unavailable
`unavailable`	At least one subsystem unavailable

Use Cases

Kubernetes liveness/readiness probes
Load balancer health checks
Monitoring systems (Nagios, Datadog, etc.)

Kubernetes Probe Example

livenessProbe:
  httpGet:
    path: /health
    port: 4200
  initialDelaySeconds: 10
  periodSeconds: 30

readinessProbe:
  httpGet:
    path: /health
    port: 4200
  initialDelaySeconds: 5
  periodSeconds: 10

GET /status

Returns detailed daemon status including provider information.

Request

curl http://localhost:4200/status

Response (200 OK)

{
  "uptime_secs": 51735,
  "health": {
    "overall": "Healthy",
    "monitoring_enabled": true
  },
  "providers": [
    {
      "id": "anthropic",
      "display_name": "Anthropic",
      "auth_status": "Configured",
      "model_count": 2
    },
    {
      "id": "groq",
      "display_name": "Groq",
      "auth_status": "Configured",
      "model_count": 3
    },
    {
      "id": "ollama",
      "display_name": "Ollama",
      "auth_status": "Configured",
      "model_count": 1
    }
  ]
}

Auth Status Values

Value	Meaning
`Configured`	API key env var is set and provider is reachable
`MissingKey`	API key env var is not set
`InvalidKey`	Key is set but rejected by provider

GET /metrics

Returns Prometheus exposition format metrics. Returns 404 if metrics are not enabled.

Request

curl http://localhost:4200/metrics

Response (200 OK, text/plain)

# HELP hoziron_uptime_seconds Platform uptime in seconds
# TYPE hoziron_uptime_seconds gauge
hoziron_uptime_seconds 51735

# HELP hoziron_agents_total Number of agents by state
# TYPE hoziron_agents_total gauge
hoziron_agents_total{state="running"} 5
hoziron_agents_total{state="suspended"} 1
hoziron_agents_total{state="total"} 6

# HELP hoziron_provider_healthy Provider health status
# TYPE hoziron_provider_healthy gauge
hoziron_provider_healthy{provider="anthropic"} 1
hoziron_provider_healthy{provider="groq"} 1
hoziron_provider_healthy{provider="ollama"} 1

Response (404 — metrics not enabled)

{
  "error": {
    "category": "NotFound",
    "message": "Metrics not enabled"
  }
}

Prometheus Scrape Config

scrape_configs:
  - job_name: 'hoziron'
    static_configs:
      - targets: ['hoziron.internal:4200']
    metrics_path: '/metrics'
    scrape_interval: 30s