API Reference

Base URL — https://api.plexus.company

Auth — x-api-key: YOUR_API_KEY on every request.

Errors — 400 bad params · 401 missing/invalid key · 402 API access is turned off for the org because of a billing problem (Free orgs are never refused here) · 403 the key may not send this command (commands only) · 404 unknown device, on GET /v1/sources/{source_id} and export only; metrics and events for an unknown device return 200 with nothing in them · 422 validation error (malformed body or params) · 429 rate limit · 500 server error · 502 upstream gateway unreachable (commands only).

Error bodies — most errors are { "detail": "..." }. 402 nests its fields under detail — { "detail": { "error": "...", "message": "..." } }. 422 returns detail as an array of objects ({loc, msg, type}). 429 and every export error are { "error": "...", "message": "..." } instead.

Rate limit — 120 requests a minute per API key, across every /v1 REST endpoint. Over that you get 429 with a Retry-After header in seconds. WebSocket streams are not counted.

History by plan — Free reads its last 7 days. When a metrics, fleet or export query starts earlier than that, Plexus moves the start up and returns the start it used in the X-Plexus-History-Start response header.

Health — GET /health is public and unauthenticated; returns {"status":"ok"}.

Time windows — relative last params take an integer plus a unit — m, h, or d (e.g. 30m, 1h, 7d).

Endpoints

Resource	Description
Devices	List and inspect devices
Metrics	Query numeric metrics
Events	Query device events and log lines
Fleet	Org-wide aggregate stats
Export	Download metrics as a CSV or Parquet file
Commands	Send commands to a connected device
Live streams	Real-time telemetry, events, video over WebSocket

Getting your data out

Metrics and events stored in Plexus can be read back with this API.

For a file, use GET /v1/export. It downloads metrics for up to 50 devices as CSV or Parquet, raw or rolled up to 1 minute or 1 hour.

For JSON, or for events:

List devices with GET /v1/sources.
List a device's metric names with GET /v1/sources/{source_id}/metrics.
Query a time range with GET /v1/sources/{source_id}/metrics/query, using start and end. Pass interval=raw for raw points.
Pull events with GET /v1/sources/{source_id}/events, using start, end and limit.

A metrics query returns at most 10 000 rows. When truncated is true, split the window and query again. An events query returns at most 10 000 events. History goes back as far as your plan keeps it (7 days on Free). See Plans and limits.

This covers data stored in Plexus. Data from a connection is not served by this API. Plexus queries it live from your database when a dashboard asks for it.