From 4e442d69d23943972f3ae5b81874be4c7c554255 Mon Sep 17 00:00:00 2001
From: germondai <germondai@gmail.com>
Date: Thu, 18 Jun 2026 08:25:00 +0200
Subject: [PATCH] docs: add health and metrics API reference

---
 apps/docs/api-reference/health-stats.md | 86 +++++++++++++++++++++++++
 1 file changed, 86 insertions(+)
 create mode 100644 apps/docs/api-reference/health-stats.md

diff --git a/apps/docs/api-reference/health-stats.md b/apps/docs/api-reference/health-stats.md
new file mode 100644
index 0000000..c60b3fd
--- /dev/null
+++ b/apps/docs/api-reference/health-stats.md
@@ -0,0 +1,86 @@
+---
+title: Health & Stats
+description: GET /health and GET /stats — monitoring endpoints.
+---
+
+# Health & Stats
+
+Both endpoints require no authentication and are safe to expose to monitoring tools.
+
+---
+
+## `GET /health`
+
+Full system health check. Used by Docker Compose health checks and monitoring systems.
+
+### Response
+
+```json
+{
+  "status": "ok",
+  "uptime": 3842,
+  "redis": "ok",
+  "pool": {
+    "total": 5,
+    "busy": 1,
+    "available": 4,
+    "restarts": 0,
+    "avgRestarts": 0
+  }
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `status` | `"ok"` | Always `"ok"` when the API is reachable |
+| `uptime` | number | Seconds since the API process started |
+| `redis` | `"ok"` or `"error"` | Whether the Redis PING succeeded |
+| `pool.total` | number | Total browser instances in the pool |
+| `pool.busy` | number | Browsers currently processing a request |
+| `pool.available` | number | Browsers ready to accept a request |
+| `pool.restarts` | number | Total browser restarts since worker boot |
+| `pool.avgRestarts` | number | Average restarts per browser |
+
+Pool stats are read directly from the browser pool. If the pool hasn't initialised yet, pool values will be zero.
+
+### Curl
+
+```bash
+curl -s http://localhost:8191/health | jq
+```
+
+---
+
+## `GET /stats`
+
+Lightweight public stats for dashboards and landing pages.
+
+### Response
+
+```json
+{
+  "browsers": 5,
+  "available": 4,
+  "busy": 1,
+  "restarts": 0
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `browsers` | number | Total browser pool size |
+| `available` | number | Idle browsers |
+| `busy` | number | Browsers in use |
+| `restarts` | number | Total browser restarts since startup |
+
+### Curl
+
+```bash
+curl -s http://localhost:8191/stats | jq
+```
+
+### Prometheus / uptime monitoring
+
+Point an uptime monitor (e.g. UptimeRobot, Uptime Kuma) at `/health`. A 200 response with `"status": "ok"` and `"redis": "ok"` confirms full operation.
+
+For Prometheus, scrape `/stats` and parse the JSON — or add a `/metrics` endpoint as a future extension.