API

All endpoints are under /api/v1. Agent and read keys are issued per environment; send the key in the X-Pm-Key header.

POST /api/v1/ingest

Accepts batched samples as newline-delimited JSON, optionally gzipped. Agents hold a persistent connection and flush every few seconds; a batch may be large after a reconnect, since agents buffer locally while the backend is unreachable.

curl -X POST https://pinionmetrics.com/api/v1/ingest \
  -H "X-Pm-Key: $PM_AGENT_KEY" \
  -H "Content-Encoding: gzip" \
  --data-binary @batch.ndjson.gz

Returns 202 on accept. Without a key the request is rejected before the body is read:

{"error":"missing_api_key","detail":"send the agent key in X-Pm-Key; see /docs for the line protocol"}

GET /api/v1/export

Streams a full range as newline-delimited JSON. Exports are not paginated — a wide range over a busy environment is a single large response, so prefer a narrow range or an If-None-Match round trip when polling.

curl -H "X-Pm-Key: $PM_READ_KEY" \
  "https://pinionmetrics.com/api/v1/export?from=2026-10-01&to=2026-10-08&series=node.cpu"

GET /api/stream

Server-sent events for the live overview. One tick event every few seconds, with a comment line as keepalive. Open for as long as the panel is open.

curl -N https://pinionmetrics.com/api/stream

GET /api/series?range=1h|24h|7d

The aggregated series behind the overview charts. No key required; the window is capped and the resolution is reduced.

Retention

Raw samples are kept in the hot tier for 15 days, then rolled up to five-minute resolution and moved to object storage. Rollups are kept for 13 months.