REST API

The critical path (ingest + subscribe) is WebSocket. The REST API is for dashboard-like operations: managing device models, listing past sessions, querying historical insights.

Base URL and auth

https://api.raeh.io

Every request carries an API key:

Authorization: Bearer raeh_ABCdef123...

All responses are JSON. Timestamps are ISO-8601 UTC unless noted.

Device models

`POST /v1/device-models`

{
  "name": "xyz_watch_v1",
  "description": "XYZ Wearables watch, first generation",
  "firmware_version": "1.0.0",
  "modality_channels": [
    { "modality": "ppg_green", "sample_rate_hz": 100, "bit_depth": 16, "num_channels": 1 }
  ]
}

Response 201: { "id": "<uuid>", ... }.

Prefer using the dashboard for this; it handles sensor defaults and validation.

`GET /v1/device-models`

List all device models for your account.

`PUT /v1/device-models/{id}`

Update name, description, firmware version, or add modality channels. The device model ID stays the same.

`DELETE /v1/device-models/{id}`

Delete. Fails if the device model is referenced by any existing Device rows.

Modality channels

Nested under /v1/device-models/{dm_id}/modalities. Use these only if you need to add / edit / remove channels on a device model that already exists.

GET /v1/device-models/{dm_id}/modalities
POST /v1/device-models/{dm_id}/modalities
PUT /v1/device-models/{dm_id}/modalities/{ch_id}
DELETE /v1/device-models/{dm_id}/modalities/{ch_id}

Sessions

`GET /v1/sessions`

List recent sessions for your account.

Query parameters (optional):

Param	Type	Description
`limit`	int	Max rows (default 50, max 200).
`status`	`open` \| `closed`	Filter.

Response:

[
  {
    "id": "ad225407-...",
    "device_id": "xyz-watch-a3b5",
    "device_model_id": "573fdc48-...",
    "status": "closed",
    "started_at": "2026-04-14T16:41:05.000Z",
    "ended_at":   "2026-04-14T16:43:35.000Z"
  }
]

`GET /v1/sessions/{id}/insights`

All insights belonging to one session, chronological.

[
  {
    "type": "hr",
    "value": 72.4,
    "unit": "bpm",
    "ts": 1760000000000,
    "actual_start": 1759999970000,
    "actual_end":   1760000000000,
    "coverage": 1.0,
    "e2e_latency_ms": 1234,
    "session_id": "ad225407-..."
  }
]

Extra fields vs the live WebSocket payload:

Field	Description
`actual_start`, `actual_end`	The data-time window used for this computation.
`coverage`	Fraction of the window filled with data (0.0–1.0).
`e2e_latency_ms`	`ts − actual_end`. How long after the last input sample the insight was published.

Insights

`GET /v1/insights`

Query insights across all sessions. Useful for analytics dashboards or time-series charts.

Query parameters:

Param	Type	Description
`type`	string	Filter to one type (`hr`, `spo2`, `rr`).
`since`	ISO-8601	Only insights with `ts` on or after this timestamp.
`until`	ISO-8601	Only insights with `ts` before this timestamp.
`limit`	int	Max rows (default 100, max 1000).

List the algorithms your account is entitled to run. Returns an array of { id, name, slug, description }. Mainly informational; the pipeline runs all entitled algorithms automatically and you don't pick them per session.

Health

`GET /v1/stream/health`

Simple liveness check for the streaming subsystem. Returns { "ok": true } when ingest + subscribe are healthy. Does not require auth.

Errors

All endpoints use standard HTTP status codes:

Status	Meaning
`400`	Bad request: validation failed. Response body has details.
`401`	Missing or invalid API key.
`403`	Key valid but not permitted for this resource.
`404`	Resource not found.
`409`	Conflict, e.g. deleting a device model still referenced by devices.
`429`	Rate limit exceeded (not enforced today, but reserve the code).
`500`	Server error. Retry with backoff.

Error body shape:

{ "detail": "device_model with id … not found" }

Programmatic key management

Minting and revoking raeh_* API keys from your own backend (instead of the dashboard) is on the roadmap. If you need it sooner, get in touch.

OpenAPI

A machine-readable OpenAPI schema is available for code generation:

GET /openapi.json

This is subject to change; pin to a specific commit if you're generating client code from it in CI.