Concepts

Six terms cover 95% of what you'll see in the API, the dashboard, and these docs.

Account

Your company's tenant. Owns everything else: keys, device models, sessions, insights. Created when you sign up. You rarely interact with it directly; it's the parent of everything.

A hardware type, e.g. "XYZ Watch v1". Defines the modality channels (PPG green, accelerometer 3-axis, etc.) and their sample rates. You register these once in the dashboard and get back a device_model_id.

Bake this ID into your firmware or SDK build config. Every unit of this hardware type carries the same device_model_id.

Device

A physical unit of a device model. Identified by a device_id string you pick: MAC address, serial number, manufacturing ID, anything stable per unit. Resolved server-side on first connection; no separate registration step.

Session

A single streaming connection. Opens when a device connects to /stream/ingest, closes when the WebSocket disconnects. All frames, features, and insights are scoped to the session they came from.

A session is short-lived (minutes to hours). A device can open many sessions over its lifetime.

Insight

One health signal value:

{
  "type": "hr",
  "value": 72.4,
  "unit": "bpm",
  "ts": 1760000000000,
  "session_id": "ad225407-...",
  "confidence": 0.87,
  "sqi_class": "excellent"
}

Currently produced: hr (heart rate), spo2 (blood oxygen), rr (respiratory rate). Emitted at node-specific intervals (HR every ~2 s, SpO₂ and RR every ~5 s).

Every insight carries a Signal Quality Index: the confidence number (0..1) and the discrete sqi_class bucket ("excellent" ≥ 0.8, "acceptable" ≥ 0.5, "unfit" < 0.5). These summarize how much of the analysis window was actually covered by in-window, low-gap data. Treat unfit values as "estimating, don't trust yet" rather than authoritative readings. See /stream/subscribe → How to read confidence.

API key

How your client authenticates. Keys are prefixed raeh_ and scoped to your account.

Mint them in the dashboard under API Keys. You decide whether to ship one key to every user of your app, or mint per-user keys on your backend and hand each user their own. Both are supported.

See Authentication for the full flow.

How they fit together

account
  ├── device model    (registered once · the hardware type)
  │     └── device    (created on first connect · the physical unit)
  │           └── session        (one per connection)
  │                 └── insights (hr, spo2, rr · published in real time)
  └── api keys        (raeh_… for clients)