From 66bc1333c93d4e6474ed126f693d7dd894ae76d8 Mon Sep 17 00:00:00 2001 From: "Aaron K. Clark" Date: Sat, 20 Jun 2026 03:49:38 -0400 Subject: [PATCH] docs: document /health liveness and /health/ready readiness probes (#16) The readiness endpoint already shipped (SELECT 1 against Postgres, 503 on failure, separate from the static liveness probe). The only unmet acceptance criterion in #16 was documentation: add a Health & probes subsection to the README API reference explaining the liveness-vs-readiness split and where to point orchestrator probes vs. load-balancer / deploy gates. Closes #16 Co-Authored-By: Claude Opus 4.8 (1M context) --- README.md | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index b48e504..c1e493f 100644 --- a/README.md +++ b/README.md @@ -197,8 +197,19 @@ All configuration is environment variables (see [`.env.example`](./.env.example) ## API reference All `/api/*` routes except the auth handshake require a valid session cookie; -unauthenticated calls get **401** with a `{"detail": "..."}` body. `/health` is -open. Error bodies are uniform `{"detail": "..."}` across 400/404/409/500. +unauthenticated calls get **401** with a `{"detail": "..."}` body. The `/health` +and `/health/ready` probes are open. Error bodies are uniform `{"detail": "..."}` +across 400/404/409/500. + +### Health & probes + +Two unauthenticated endpoints, split so a database hiccup drains traffic without +killing the process: + +| Method | Path | Notes | +| --- | --- | --- | +| `GET` | `/health` | **Liveness.** Cheap and static — `200 {"status":"ok"}`. Never touches the database, so a transient DB blip can't trip it into a restart loop. Point your orchestrator's liveness probe here. | +| `GET` | `/health/ready` | **Readiness.** Opens Postgres and runs `SELECT 1`. `200 {"status":"ready","database":"connected"}` when the DB is reachable (and startup migrations have run); `503 {"status":"unavailable","database":"disconnected"}` otherwise. Point load balancers / deploy gates here so traffic only arrives once the DB is up. | ### Auth