snxraven/peardata

Fork 0

Files

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

8.9 KiB

Raw Blame History

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.

Quick examples

# 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.

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

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; user guide: weights-api
GET	`/api/v1\|v2\|v3/logs`	Log search — `source=anomaly\|audit\|journal`, `q`, `since`, `until`, `priority`, `unit`, `limit` — user-guide/logs
GET	`/api/v1\|v2\|v3/processes`	Live process table — `sort`, `order`, `filter`, `q`, `limit`, `offset`, `pid` — user-guide/processes

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 · Parameter cheat sheet: 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

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 and 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

8.9 KiB Raw Blame History Unescape Escape