diff --git a/docs/phoenixmldb/deployment/server-mode.md b/docs/phoenixmldb/deployment/server-mode.md
index 44ce45e..af71e57 100644
--- a/docs/phoenixmldb/deployment/server-mode.md
+++ b/docs/phoenixmldb/deployment/server-mode.md
@@ -196,7 +196,7 @@ var client = new PhoenixmlClient(
 Every REST endpoint requires either an **API key** in the `X-Api-Key` header or a **JWT** in
 `Authorization: Bearer <token>`. Anonymous requests get `401`. Only these are open:
 
-- `/health`, `/health/live`, `/health/ready`
+- `/health`, `/health/live`, `/health/ready`: status only; the detailed `/health/details` needs an admin credential (see [Health Endpoints](#health-endpoints))
 - the Swagger UI, and only in the Development environment
 
 ```bash
@@ -319,13 +319,37 @@ var results = await client.QueryAsync(...);
 
 ## Monitoring
 
-### Health Endpoint
+### Health Endpoints
+
+The REST server exposes four health endpoints. The three public ones return **status only**: a
+plain-text body of `Healthy`, `Degraded` or `Unhealthy`, with no check names, data or error text.
+
+| Endpoint | Auth | Checks | HTTP status |
+|---|---|---|---|
+| `/health/live` | anonymous | none: liveness only | `200` while the process is up |
+| `/health/ready` | anonymous | database, query engine, transform engine | `200` Healthy or Degraded, `503` Unhealthy |
+| `/health` | anonymous | the same as `/health/ready` | as `/health/ready` |
+| `/health/details` | **admin** (`RequireAdmin`) | every registered check | detailed JSON report |
 
 ```bash
-curl http://localhost:5432/health
-# {"status":"healthy","version":"1.0.0","uptime":"3d 4h"}
+curl -i https://localhost:5001/health/ready
+# HTTP/1.1 200 OK
+# Healthy
+
+curl -H "X-Api-Key: $ADMIN_KEY" https://localhost:5001/health/details   # names, status, durations, data
 ```
 
+`/health/details` returns `401` without a credential and `403` for a key without admin
+permission.
+
+**Probes.** Point a liveness probe at `/health/live`, and a readiness probe or load balancer at
+`/health/ready`. `/health/ready` actually runs the checks; before phoenixml `main` 170adf3 it
+checked nothing and always returned `200`.
+
+**No health response contains exception text.** Failures are logged on the server. The detailed
+report carries a fixed code instead: `database_unavailable`, `query_engine_unavailable` or
+`transform_engine_unavailable`.
+
 ### Metrics Endpoint
 
 ```bash
diff --git a/docs/release-notes.md b/docs/release-notes.md
index 23a98b9..2ffd7a2 100644
--- a/docs/release-notes.md
+++ b/docs/release-notes.md
@@ -24,6 +24,15 @@ setting and startup check.
 
 **The gRPC server has no authentication yet.** Don't expose it outside a trusted network.
 
+### Breaking for monitoring: health endpoints are status-only
+
+Since phoenixml `main` 170adf3 (issue #51), `/health`, `/health/live` and `/health/ready` return
+only `Healthy` / `Degraded` / `Unhealthy` as plain text: `200`, or `503` when unhealthy. The
+detailed JSON report moved to **`/health/details`**, which requires an admin credential. Anything
+that parsed JSON from `/health` must call `/health/details` instead. `/health/ready` now runs the
+database and engine checks; it used to always return `200`. See
+[Server Mode: Health Endpoints](phoenixmldb/deployment/server-mode.md#health-endpoints).
+
 ## Engines: PhoenixmlDb.Xslt and PhoenixmlDb.XQuery
 
 Since 2.0.0 the two engines release together as one **train**: the Xslt and XQuery versions