Health & Ops
The server exposes health check, readiness, diagnostics, and debug endpoints for use by load balancers, Kubernetes probes, and on-call engineers.
Endpoints overview
Section titled “Endpoints overview”| Endpoint | Purpose | Auth |
|---|---|---|
GET /health |
Full health status with checks | None |
GET /healthz |
Minimal liveness probe | None |
GET /ready |
Readiness probe | None |
GET /debug |
Go runtime stats (dev only) | superadmin_full |
GET /api/diagnostics |
Deep DB diagnostics | superadmin_full |
The liveness/readiness probes (/health, /healthz, /ready) are deliberately unauthenticated so load balancers and Kubernetes probes can reach them. The internal diagnostic surfaces (/debug, /api/diagnostics) expose platform-tier internals (DB connection target, pool state, pg_stat_activity) and are gated on an active superadmin_full grant (the core.superadmins role), never a token scope and never a bare admin scope.
/health — Full health check
Section titled “/health — Full health check”Returns a JSON object with overall status and per-subsystem checks.
curl https://api.example.com/health{ "status": "healthy", "timestamp": "2026-03-08T12:00:00Z", "uptime": "3h12m5s", "version": "1.2.3", "checks": { "database": "healthy" }}Returns 200 when healthy. Returns 503 Service Unavailable when any check fails.
/healthz — Minimal liveness probe
Section titled “/healthz — Minimal liveness probe”Returns plain text OK (200) or Service Unavailable (503). Use this for high-frequency Kubernetes liveness probes where JSON parsing overhead is undesirable.
curl https://api.example.com/healthz# OK/ready — Readiness probe
Section titled “/ready — Readiness probe”Returns a JSON object indicating whether the server is ready to receive traffic. The server may be alive (/healthz) but not yet ready (e.g. still running migrations).
curl https://api.example.com/ready{ "status": "ready" }or
{ "status": "not_ready", "message": "database migrations pending" }/debug — Runtime stats
Section titled “/debug — Runtime stats”Requires an active superadmin_full grant. Returns Go runtime memory statistics and database connection pool stats as JSON.
curl -H "Authorization: Bearer <superadmin-token>" http://localhost:3012/debug{ "go_runtime": { "goroutines": 42, "heap_alloc_mb": 128, "heap_sys_mb": 256, "gc_runs": 15 }, "db_pool": { "open_connections": 8, "in_use": 2, "idle": 6, "wait_count": 0 }}/api/diagnostics — Deep diagnostics
Section titled “/api/diagnostics — Deep diagnostics”The diagnostics endpoint provides live database pool inspection and slow-query detection. Useful for on-call investigation of performance issues.
Requires an active superadmin_full grant. The long_queries report redacts raw SQL text — it exposes only the query length (query_length) alongside pid, duration, and state, so an in-flight query’s literals (which may embed secrets or user data) never leave the server.
curl -H "Authorization: Bearer <superadmin-token>" https://api.example.com/api/diagnosticsResponse fields:
| Field | Description |
|---|---|
db_pool |
Bun connection pool statistics |
pg_stat_activity |
Active Postgres sessions from pg_stat_activity |
long_queries |
Queries running longer than 5 seconds |
settings |
Relevant PostgreSQL configuration settings |
table_sizes |
Top tables by disk size |
Example response:
{ "db_pool": { "open_connections": 10, "in_use": 3, "idle": 7 }, "pg_stat_activity": [ { "pid": 1234, "state": "active", "query_length": 42, "duration_sec": 0.1 } ], "long_queries": [], "settings": { "max_connections": "100", "shared_buffers": "128MB" }, "table_sizes": [ { "table": "kb.graph_objects", "size": "4210 MB" }, { "table": "kb.chunks", "size": "1024 MB" } ]}OpenAPI specification
Section titled “OpenAPI specification”The server auto-generates an OpenAPI 3.0 specification. Access it at:
GET /api/docs/openapi.jsonor in the admin UI:
https://admin.example.com/api-referenceYou can import the spec into Postman, Insomnia, or any OpenAPI-compatible tool.
Kubernetes probe configuration
Section titled “Kubernetes probe configuration”Recommended Kubernetes probe settings:
livenessProbe: httpGet: path: /healthz port: 3012 initialDelaySeconds: 10 periodSeconds: 10 failureThreshold: 3
readinessProbe: httpGet: path: /ready port: 3012 initialDelaySeconds: 5 periodSeconds: 5 failureThreshold: 3Monitoring integration
Section titled “Monitoring integration”For production monitoring, consider:
- Uptime monitoring — poll
/healthzevery 30s from an external probe - Alerting — alert when
/healthreturns non-healthychecks - Performance — use
/api/diagnosticsto investigate slow queries when latency spikes - Tracing — set
OTEL_EXPORTER_OTLP_ENDPOINTto enable OpenTelemetry tracing (no-op when unset)