End users (userRef)

Tag every measurement with userRef — an opaque identifier of your end user — and the API turns from a stream of anonymous measurements into a per-user health record you can build product features on.

The ref

• Format: ^[A-Za-z0-9._:@-]{1,64}$ — safe to use in a URL path segment.
• It is your identifier, opaque to us. Do not send PII (no e-mails, no names): send a hash or your internal user id.
• Everything is scoped to the API key that signs the request. Another key — even in the same organization — sees an empty history for the same ref.

Writing it

Pass userRef (optional everywhere) when you:

• submit a measurement: POST /sdk/v1/measurements;
• mint a cloud session: POST /sdk/v1/cloud/sessions — the measurement the inference node stores inherits the ref, and a fallback batch job keeps it;
• queue a batch job: POST /sdk/v1/cloud/jobs.

A malformed ref is a 400 validation_error. When the ref was set, measurement and job payloads additively carry userRef back.

Reading

All three endpoints are HMAC-signed GETs (authentication).

GET /sdk/v1/users

Distinct refs of your key with aggregates, ordered by last activity:

{
  "items": [
    {
      "userRef": "u_42",
      "measurements": 7,
      "firstSeenAt": 1756000000000,
      "lastSeenAt": 1756400000000,
      "avgQuality": 0.84
    }
  ],
  "total": 3
}

page / perPage (1..100, default 20) paginate.

GET /sdk/v1/users/{ref}/measurements

The user's history, newest first, in the standard measurement shape. Supports page, perPage, from / to (millisecond timestamps) and include=assessment.

GET /sdk/v1/users/{ref}/baseline

A personal baseline: per-metric median ± 2·MAD over the user's usable measurements (complete, quality good/fair) from the last 30 days, capped at the 200 most recent. Metrics: heartRateBpm, rmssdMs, sdnnMs, breathingRate, stressIndex, systolicMmHg, diastolicMmHg, spo2Pct.

{
  "userRef": "u_42",
  "status": "ok",
  "windowDays": 30,
  "minSamples": 5,
  "sampleCount": 12,
  "metrics": {
    "heartRateBpm": { "median": 68, "mad": 3, "low": 62, "high": 74, "unit": "bpm", "samples": 12 }
  },
  "disclaimers": ["Estimate for wellness use only. Not a medical device."]
}

Honesty rules:

• fewer than 5 values for every metric → status: "insufficient_data" and an empty metrics (still HTTP 200);
• low/high is an informational corridor, not a medical norm; a constant series has mad: 0 and a degenerate corridor.

CSV export in the console gains a trailing userRef column, and the integration measurements table can filter by ref.