Measurements

A measurement moves through three states — created, started, ended — and the API lets you drive it either in one call or in two.

The routes

The create-and-execute routes are the ones to reach for. The two-step form exists for when you need the identifier before you have the media — the widget uses it that way.

Describing the person

Several variables cannot be computed from the signal alone. userData is where you say what is needed.

Every field is optional. What you omit simply narrows what can be computed:

Choosing variables

Two optional arrays narrow what is computed:

{
  "desiredVariables": ["hr", "br"],
  "unwantedVariables": ["faceBmi"]
}

Omit both and the measurement computes everything your account is entitled to.

Sending a recorded video

POST /measures/rppg/video
Authorization: Bearer <apiKey>
Content-Type: multipart/form-data

The call below goes to Production. Send it to Test while you are still validating a pipeline — measurements made there never appear in your Production data.

curl -sX POST https://api.saphere.ai/measures/rppg/video \
  -H "Authorization: Bearer $SAPHERE_API_KEY" \
  -F "video=@./capture.mp4;type=video/mp4" \
  -F "userData[sex]=F" \
  -F "userData[age]=35" \
  -F "userData[weight]=58" \
  -F "userData[height]=171" \
  -F "userData[smokingStatus]=non-smoker" \
  -F "tags=cohort-a,pilot"

The response is the completed measurement — the same shape the widget delivers.

Sending images

POST /measures/rppg/images

Everything else matches the video route.

Reading a measurement back

GET /measures/{measureId}
Authorization: Bearer <apiKey>

Measures belonging to another client return 404, in plain text, exactly as a non-existent one does.

Deleting a measurement

DELETE /measures/{measureId}
Authorization: Bearer <apiKey>

This removes the stored media — captures, images, video, signals — and then the measurement row. The call is safely repeatable: a missing object is not an error, so a delete interrupted halfway can simply be issued again.

The result

{
  "id": "3f1a5c88-0b2d-4e6a-9c11-7d5e8a2b4f60",
  "status": "ended",
  "type": "rppg",
  "createdAt": "2026-08-24T14:57:44.000Z",
  "startedAt": "2026-08-24T14:57:46.000Z",
  "endedAt": "2026-08-24T14:58:22.000Z",
  "returnedVariables": ["hr", "br", "strs", "bp"],
  "signal": { "qualityScore": { "value": 100, "error": null } },
  "variables": {
    "hr":   { "value": { "mean": 72.4 }, "error": null },
    "br":   { "value": { "mean": 15.1 }, "error": null },
    "strs": { "value": { "level": 2, "scale": { "min": 1, "max": 5 } }, "error": null },
    "bp":   { "value": null, "error": "MISSING_USER_DATA_AGE" }
  },
  "userData": { "sex": "F", "weight": 58, "height": 171 },
  "tags": ["cohort-a"]
}

returnedVariables is an entitlement, not an outcome

This is the field most often misread. It lists the variables your client account is allowed to receive, narrowed by any desiredVariables / unwantedVariables you passed. It does not list what succeeded.

Value shapes

Every variable is one of two things: a value with error: null, or value: null with an error code.

Always branch on error first:

const hr = result.variables.hr
if (hr?.error === null)
    console.log("heart rate:", hr.value.mean)
else if (hr)
    console.warn("heart rate unavailable:", hr.error)
else
    console.warn("heart rate not granted to this account")

The quality indicator

"signal": { "qualityScore": { "value": 100, "error": null } }

To judge whether a measurement is usable, read the individual variables and their error codes.

Build that judgement against Test data first: entitlements and quota are set per account, so what a Test client returns is not necessarily what your Production client will. Environments sets out the separation.