# Ysbryd Systems Cloud API

> REST API for Ysbryd Systems wireless sensor fleets: temperature (°F), humidity (%), CO2 (ppm),
> battery and signal health, per-site gateways, threshold alerts, and CSV export for compliance.
> Base URL: https://cloud.ysbrydsystems.com — JSON in/out, API-key auth.

Auth: send `X-API-Key: yscl_...` with every request. Get a key by POSTing portal credentials
(JSON `{"email", "password"}`) to `/auth/login`. Keys are per-customer and need an active
subscription. Edge rate limit: 60 req/min per IP (burst 30); `/api/sync` also 60/min per key;
login 5 req/min per IP and 15-min lockout after 5 fails.

Timestamps: `/api/readings` and `/api/export/csv` return `"2026-09-06T21:15:00Z"` (ISO-8601 UTC).
Some other fields (e.g. `latest.recorded_at` from `/api/sensors`) return HTTP-date strings
(`"Sun, 06 Sep 2026 21:15:23 GMT`) — parse both as UTC.

## Endpoints (agent-relevant)

- `GET /api/sensors` — your sensors + latest reading each
- `GET /api/readings?hours=24&sensor_id=sensor_17` — history; auto-aggregates long ranges (adds min/max per bucket); or `start`/`end` for exact windows
- `GET /api/fleet` — gateway online/offline, node counts, low-battery and stale-node rolls
- `GET /api/export/csv?sensors=all&start=...&end=...&compliance=true&tz=-6` — deduplicated CSV export
- `PUT /api/thresholds` — set alert bounds `{sensor_id, threshold_min, threshold_max}` (°F) or `co2_threshold_*` (ppm)
- `PUT /api/sensors/{id}/name` / `PUT /api/sensors/{id}/location` — relabel sensors
- `GET|PUT /api/alert-email` · `GET|PUT /api/alert-phone` · `GET|PUT /api/alert-slack` — alert delivery
- `GET|POST /api/alert-recipients`, `PUT|DELETE /api/alert-recipients/{id}`, `POST /api/alert-recipients/{id}/test` — recipient management
- `POST /api/alerts/{id}/acknowledge` — acknowledge an alert
- `POST /auth/login` — exchange credentials for the API key

Device endpoints `/api/sync`, `/api/heartbeat`, `/api/settings` are for Ysbryd gateways only.

## Full reference

- [OpenAPI 3.1 spec](https://cloud.ysbrydsystems.com/openapi.yaml) (machine-readable; JSON copy at /openapi.json)