Metric Correlations

docs/REST-API.md

@@ -137,6 +137,24 @@ Single-agent returns one node. With `PEARDATA_PARENT=1`, `/nodes` and `/fleet` i
 - If you bind `0.0.0.0`, put REST behind a firewall, reverse proxy, or Holesail tunnel — do not expose raw metrics to the internet.
 - Future: optional bearer gate (`/api/v3/bearer_protection` parity).
 
+## Weights / Metric Correlations
+
+`GET /api/v1/weights` · `/api/v2/weights` · `/api/v3/weights` (same engine; also RPC `getWeights`)
+
+| Param | Notes |
+|-------|--------|
+| `method` | `volume` (default with window), `ks2`, `anomaly-rate`, `value`, `alerts` |
+| `after` / `before` | Highlight window (unix seconds or relative, e.g. `after=-60&before=0`) |
+| `baseline_after` / `baseline_before` | Optional; default = 4× highlight immediately preceding |
+| `points` | Resolution (default 500 for MC methods) |
+| `time_group` | Aggregation for `value` (default `cv`) |
+| `contexts` / `charts` / `dimensions` | Optional filters |
+| `limit` / `timeout` | Result cap / ms budget |
+
+Without a highlight window, `method` defaults to **alerts** (active anomaly/alert weights — used by Related panel boost).
+
+Response includes `method`, `view.highlight` / `view.baseline`, and `results[{ id, weight, context, family, info }]`. Higher `weight` = more changed / interesting.
+
 ## CORS
 
 `Access-Control-Allow-Origin` defaults to `*` (override with `PEARDATA_REST_CORS`).
@@ -145,7 +163,7 @@ Single-agent returns one node. With `PEARDATA_PARENT=1`, `/nodes` and `/fleet` i
 
 | Area | PearData |
 |------|----------|
-| ML weights / metric correlations | Per-chart anomaly weights; desktop related uses corr + weights |
+| Weights / Metric Correlations | `GET /api/v*/weights` — highlight-vs-baseline scoring (`method=volume\|ks2\|anomaly-rate\|value`) or alert weights when no window; see below |
 | Multi-node parent streaming | Single node; parent planned |
 | Cloud POST spaces APIs | Not implemented (agent GET style only) |
 | App/plugin charts (nginx, DB, …) | System/OS charts; plugins later |