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