Skip to content

Health API

GET /api/health · GET /health

Two paths, one handler. No authentication.

curl -s https://api.venkai.fr/api/health

{"status": "ok", "database": "ok"}

It is a readiness probe, not a liveness probe

The handler opens a database connection and runs SELECT 1. If that fails it returns 503:

{"detail": "database unreachable: OperationalError"}

This matters. A container whose database has gone away is still perfectly alive: it accepts connections and answers 500 on every real route. A health check that returned a constant {"status":"ok"} would report that deployment as healthy at exactly the moment it is not — and that is the signal your uptime monitor, your compose healthcheck and your runbook all read.

One round trip makes the answer mean something.

Status Meaning Action
200 API up, database reachable —
503 API up, database unreachable Do not route traffic here
no response API down Restart / investigate

/health exists as an alias because documentation predating this endpoint says api.venkai.fr/health. A redirect would be one more hop to misconfigure in a proxy. It is excluded from the OpenAPI schema; /api/health is the canonical path.

Uses

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:8100/api/health"]
  interval: 30s
  timeout: 5s
  retries: 3

readinessProbe:
  httpGet: { path: /api/health, port: 8100 }
  initialDelaySeconds: 5
  periodSeconds: 10
livenessProbe:
  httpGet: { path: /api/health, port: 8100 }
  periodSeconds: 30
  failureThreshold: 5

Using the same endpoint for liveness is a compromise: a long database outage will restart pods that are not themselves broken. Set failureThreshold high enough that a brief blip does not cause a restart storm.

curl -fsS https://api.venkai.fr/api/health >/dev/null \
  && echo "venkai ok" || echo "venkai DOWN"

Not covered

Health reports reachability, nothing else. It does not check the embedding provider, migration state, disk space, or queue depth (there are no queues). A 200 means "the API can reach its store" and no more.

Endpoint Auth Returns
GET /api/usage ✅ Request counts by kind (remember, recall, read, admin), from server-side middleware
GET /api/activity ✅ Recent activity for the organization
GET /api/onboarding ✅ Onboarding checklist state for the dashboard
POST /api/telemetry ✅ Client-submitted events, opt-in
POST /api/feedback ✅ {project_id, context_id?, rating} where rating is positive or negative

/api/usage is counted by middleware on every authenticated /api/ request, so it reflects real traffic. /api/telemetry only contains what clients choose to post — the two are not comparable and should not be summed.