snxraven/peardata
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity
Files
0f865348053798a2a38880fe6c40a3505c49319a
peardata/docs/REST-API.md
T
Raven Scott 32928f19bd
CI / test (push) Successful in 1m8s
Details
Release rolling / release (push) Successful in 8m25s
Details
First Try: QVAC (QuantumVerse Automatic Computer)
2026-07-30 13:42:14 -04:00

226 lines
8.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# REST API (agent-compatible)
PearMonitor agents expose an optional HTTP API for local tooling (`/api/v1`, `/api/v2`, `/api/v3`).
Default bind: `http://127.0.0.1:18888`.
Disable: `PEARDATA_REST=0`.
Bind all interfaces (careful): `PEARDATA_REST_HOST=0.0.0.0`.
Core query/metadata paths are implemented for scripts, Grafana, and Prometheus scrapers.
Compatibility matrix vs upstream agent OpenAPI: [SWAGGER_PLAN.md](./SWAGGER_PLAN.md).
## Quick examples
```bash
# Agent info
curl -s http://127.0.0.1:18888/api/v3/info | jq
# Chart catalog (v1 style)
curl -s http://127.0.0.1:18888/api/v1/charts | jq '.charts | keys'
# Last 60s of CPU (v3)
curl -s 'http://127.0.0.1:18888/api/v3/data?chart=system.cpu&after=-60&points=60' | jq
# Contexts
curl -s http://127.0.0.1:18888/api/v3/contexts | jq
# Prometheus export
curl -s 'http://127.0.0.1:18888/api/v3/allmetrics?format=prometheus'
# Health
curl -s http://127.0.0.1:18888/api/v3/health | jq
```
## Endpoint matrix
### Info & identity
| Method | Path | Notes |
|--------|------|-------|
| GET | `/` or `/api` | Service index + P2P pubkey + HyperDB keys |
| GET | `/api/v1/info` | Agent info |
| GET | `/api/v2/info` | same |
| GET | `/api/v3/info` | **preferred** (includes `peardata.hyperdb`) |
| GET | `/api/v3/db` | HyperDB public/discovery keys + collections |
| GET | `/api/v3/versions` | Agent / protocol / API versions |
| GET | `/api/v3/me` | Anonymous REST identity note |
| GET | `/api/v3/settings` | Runtime knobs + **retention** + **storage usage** summary (Data Manager read model) |
| GET | `/api/v3/config` | alias of settings |
| GET | `/health`, `/api/v1/health`, `/api/v3/health` | Aggregate health |
### AI / QVAC tool helpers
Compact reads for local copilots (same payloads as P2P `getHostSnapshot` / `searchCharts` / `summarizeChart`). See [QVAC.md](./QVAC.md).
| Method | Path | Notes |
|--------|------|-------|
| GET | `/api/v3/ai/snapshot` | Health, KPIs, anomalies/alerts, catalog/storage summary |
| GET | `/api/v3/ai/charts?q=&limit=` | Catalog search |
| GET | `/api/v3/ai/chart/:id/summary?after=&points=&group=` | Windowed min/avg/max/last per dimension |
```bash
curl -s http://127.0.0.1:18888/api/v3/ai/snapshot | jq
curl -s 'http://127.0.0.1:18888/api/v3/ai/charts?q=disk&limit=20' | jq
curl -s 'http://127.0.0.1:18888/api/v3/ai/chart/system.cpu/summary?after=-120&points=120' | jq
```
### Nodes
| Method | Path |
|--------|------|
| GET | `/api/v2/nodes` |
| GET | `/api/v3/nodes` |
| GET | `/api/v3/node_instances` |
| GET | `/api/v3/fleet` |
| GET | `/api/v3/stream_path` |
Single-agent returns one node. With `PEARDATA_PARENT=1`, `/nodes` and `/fleet` include dialed children.
### Export
| Method | Path | Notes |
|--------|------|-------|
| GET | `/api/v3/export` | JSON snapshot; `?format=prometheus` for text; `?write=1` writes `PEARDATA_EXPORT_DIR` |
| GET | `/api/v3/tunnel` | HyperDHT REST tunnel status / public key |
### Contexts & charts
| Method | Path | Notes |
|--------|------|-------|
| GET | `/api/v3/contexts` | Context map |
| GET | `/api/v2/contexts` | same |
| GET | `/api/v3/context?context=` | One context |
| GET | `/api/v1/charts` | Full chart summary (legacy but useful) |
| GET | `/api/v1/chart?chart=` | One chart |
### Data queries
| Method | Path | Query params |
|--------|------|--------------|
| GET | `/api/v3/data` | `chart` or `context`, `after`, `before`, `points`, `group`, `tier`, `format` |
| GET | `/api/v2/data` | same |
| GET | `/api/v1/data` | same (legacy) |
**Params (agent-style)**
| Param | Default | Description |
|-------|---------|-------------|
| `chart` / `context` | required | Chart id or context id |
| `after` | `-60` | Absolute unix sec, or relative (negative) |
| `before` | `0` (now) | Absolute or relative |
| `points` | `60` | Max points returned (downsampled) |
| `group` | `average` | `average` \| `min` \| `max` \| `sum` |
| `tier` | `0` | `0` = 1s buffer, `1` = downsampled |
| `format` | `json` | `json` \| `csv` \| `array` |
### Search & weights
| Method | Path | Notes |
|--------|------|-------|
| GET | `/api/v3/q?q=` | Full-text over chart ids/titles |
| GET | `/api/v1\|v2\|v3/weights` | Metric Correlations + alert weights — see [Weights](#weights--metric-correlations); user guide: [weights-api](../user-guide/weights-api.md) |
| GET | `/api/v1\|v2\|v3/logs` | Log search — `source=anomaly\|audit\|journal`, `q`, `since`, `until`, `priority`, `unit`, `limit` — [user-guide/logs](../user-guide/logs.md) |
| GET | `/api/v1\|v2\|v3/processes` | Live process table — `sort`, `order`, `filter`, `q`, `limit`, `offset`, `pid` — [user-guide/processes](../user-guide/processes.md) |
### Alerts
| Method | Path |
|--------|------|
| GET | `/api/v3/alerts` |
| GET | `/api/v2/alerts` |
| GET | `/api/v1/alarms` |
| GET | `/api/v3/alert_transitions` |
| GET | `/api/v3/alert_config` |
| GET | `/api/v3/variable` |
### Export & badges
| Method | Path | Params |
|--------|------|--------|
| GET | `/api/v3/allmetrics` | `format=json\|prometheus\|shell` |
| GET | `/api/v1/allmetrics` | same |
| GET | `/api/v3/badge.svg` | `chart`, `dimensions`, `label` |
### Functions (stub)
| Method | Path | Notes |
|--------|------|-------|
| GET | `/api/v3/functions` | Lists job names; execution remains P2P `runJob` for auth |
## Auth model (REST)
- **Default:** localhost-only, no bearer required (like a typical local agent bind).
- **P2P remains the secure remote path** (Noise + roles).
- 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`)
Desktop walkthrough: [user-guide/metric-correlations.md](../user-guide/metric-correlations.md) · Parameter cheat sheet: [user-guide/weights-api.md](../user-guide/weights-api.md)
| 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.
Engine: `server/services/weights.js`. Unit tests: `test/weights.test.js`.
## Logs
`GET /api/v1/logs` · `/api/v2/logs` · `/api/v3/logs` (same engine; also RPC `queryLogs`)
Desktop walkthrough: [user-guide/logs.md](../user-guide/logs.md)
| Param | Notes |
|-------|--------|
| `source` | `journal` (default) \| `anomaly` \| `audit` — desktop prefers **journal** for admins |
| `q` | Case-insensitive substring over message / unit / severity |
| `since` / `until` | Absolute ms/sec, ISO, or relative (`-1h`) |
| `priority` | Journal max priority (`journalctl -p`) |
| `unit` | Journal unit (e.g. `peardata.service`) |
| `limit` / `cursor` | Cap (default 200, max 2000) + pagination offset |
**Auth:** REST is localhost-open (like other GETs). Over P2P, `audit` and `journal` require **admin**; `anomaly` allows viewer.
**Journal:** enabled by default (`PEARDATA_JOURNAL=0` to disable). Linux only; installer adds `peardata` to `systemd-journal`. Omitted `source` defaults to **journal**.
Engine: `server/services/logs.js`. Unit tests: `test/logs.test.js`.
### Data Manager (read via settings)
`GET /api/v3/settings` includes `retention` and a `storage` summary (data dir / corestore / memory rings). Mutating retention / prune is **P2P admin RPC** (`setRetentionConfig`, `pruneHistory`) — see [PROTOCOL.md](./PROTOCOL.md) and [user-guide/settings.md](../user-guide/settings.md).
## CORS
`Access-Control-Allow-Origin` defaults to `*` (override with `PEARDATA_REST_CORS`).
## Scope notes
| Area | PearData |
|------|----------|
| Weights / Metric Correlations | `GET /api/v*/weights` — highlight-vs-baseline scoring (`method=volume\|ks2\|anomaly-rate\|value`) or alert weights when no window; see above |
| Logs | `GET /api/v*/logs` — journal (default) / anomaly / audit; see above |
| Retention / storage | `GET /api/v*/settings` includes retention + usage; writes via P2P admin RPC |
| 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 |
| Functions via HTTP | Listed; run via P2P jobs |
## Implementation
- Router: `server/rest/routes.js`
- Server: `server/rest/http-server.js`
- Exporters: `server/rest/formatters.js`
Reference in New Issue View Git Blame Copy Permalink