Health endpoints

Self-hosted Quackback exposes two health endpoints for load balancers, Docker healthchecks, and Kubernetes probes: a liveness check and a readiness check. Both are unauthenticated (no API key needed) and safe to poll frequently.

Liveness

GET /api/health/live

Confirms the process is up and serving HTTP. It does no I/O, so a slow database can never make it fail.

curl https://your-domain/api/health/live

{ "status": "ok" }

It always returns 200 if the process can respond at all. Use it for a container orchestrator's restart-on-failure check.

Note: GET /api/health (no suffix) is a legacy alias of /api/health/live, kept for existing setups. Use /api/health/live in new configuration.

Readiness

GET /api/health/ready

Confirms the instance can actually serve traffic: the database answers, migrations are up to date, and (on worker and all roles) the background job worker is running.

curl https://your-domain/api/health/ready

{
  "status": "ok",
  "role": "all",
  "checks": {
    "db": { "ok": true },
    "migrations": { "ok": true },
    "workers": {
      "ok": true,
      "expected": true,
      "running": true,
      "loops": 1,
      "inFlight": 0,
      "schemaMissing": 0,
      "refused": 0
    }
  }
}

• Returns 200 when every check passes, and 503 with the same shape otherwise.
• Each failed check carries a short error code: failed, timeout, or behind (migrations not yet caught up). Raw error details are never exposed.
• Each check has a 3-second budget, so a hung dependency reports timeout instead of hanging the probe.
• role reports the replying process's QUACKBACK_ROLE (all, web, or worker). On a web replica, workers.expected is false and the check passes, since no workers run there.

Tip: Use /api/health/ready for your load balancer's traffic check and Kubernetes' readinessProbe. Use /api/health/live for livenessProbe. Readiness can legitimately return 503 during a deploy or migration without meaning the process should be restarted.

Where these are used

• The healthcheck in docker-compose.prod.yml polls /api/health/ready. See Deploy with Docker.
• On Railway, set the service's health check path to /api/health/ready with a generous timeout. See Deploy to Railway.
• If background jobs aren't running, checks.workers shows expected: true with running: false. See Troubleshoot common issues.

Related articles

• Deploy with Docker
• Scale with multiple replicas
• Troubleshoot common issues
• API overview