Health — Docs

These endpoints do not require authentication. They are designed for load balancers, orchestrators (Kubernetes), and monitoring systems.

Liveness probe

GET/health

Returns OK if the process is running. Use as a liveness probe.

200Response

{
  "status": "ok"
}

No authentication required. Always returns 200 if the process is alive.

Readiness probe

GET/ready

Checks that all subsystems are initialized and the service can accept requests. Use as a readiness probe.

200Response

{
  "status": "ready",
  "checks": {
    "database": true,
    "embedding_model": true,
    "memory_engine": true
  }
}

Returns 503 if any subsystem is not ready:

503Response

{
  "status": "not_ready",
  "checks": {
    "database": true,
    "embedding_model": false,
    "memory_engine": false
  }
}

Cache metrics

GET/metrics/cache

Embedding cache statistics. Useful for monitoring cache hit rates and sizing.

200Response

{
  "hits": 12847,
  "misses": 1923,
  "hit_rate": 0.87,
  "size": 4096,
  "max_size": 10000,
  "evictions": 234
}

Tip

Monitor hit_rate to ensure your cache is properly sized. A hit rate below 0.7 suggests increasing cache size or reviewing access patterns.

Kubernetes example

livenessProbe:
  httpGet:
    path: /health
    port: 8080
  initialDelaySeconds: 5
  periodSeconds: 10

readinessProbe:
  httpGet:
    path: /ready
    port: 8080
  initialDelaySeconds: 10
  periodSeconds: 5

Next steps

Overview — API overview and base URL
Errors — Error response format