Measurements

A measurement goes through three states: created, started, then ended. You can drive it in one call, or in two.

The routes

The create-and-run routes are the ones to reach for. They answer 201 Created; running an existing measure answers 200 OK. Both return the measurement. The two-step form exists for when you need the identifier before you have the file — that is how the v1 widget works: your server creates the measure, and the widget runs it. A measure runs once: running one that has already started is refused with 400.

This page details the video and images routes. The bodies of the captures and signal routes are in the OpenAPI reference.

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:

bp is calibrated per person. It needs an externalId, and an earlier, complete measurement of that same person for which a reference blood pressure was entered — only the end-of-measurement form of the v1 widget records one today. Without it, bp comes back with NOT_CALIBRATED. GET /external-users/{externalId} answers { "externalId", "rppgCalibrated", "cppgCalibrated" }, or 404 when none of your measurements carries that identifier.

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.

Two more optional fields sit beside them. tags is a list of your own labels, up to 1000, returned with the measure and usable to filter the list. computeOptions adjusts how a variable is expressed: { "bpClass": { "scale": 2 } } returns bpClass on two levels — normal, or not — instead of three.

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 checking your 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, 201 Created, is the completed measurement — the same shape the widget delivers.

Sending images

POST /measures/rppg/images

The other parts are those of the video route.

Reading a measurement back

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

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

Listing your measurements

GET /measures
Authorization: Bearer <apiKey>

You only ever see your own. Another client’s measurements are not refused, they are simply absent.

The list is not sorted, and its order is not guaranteed from one call to the next: to go through a large set page by page, narrow it with a filter rather than relying on skip alone. filters applies to GET /measures only — GET /measures/rppg and GET /measures/cppg accept it but do not apply it.

Filtering by tag

A filter is a condition — a field, an operator, and the values to compare it to:

{ "operator": "contains", "name": "tags", "values": ["cohort-a"] }

It travels as one query parameter, written either serialised or spread — both are accepted, and mean the same thing:

GET /measures?filters={"operator":"contains","name":"tags","values":["cohort-a"]}
GET /measures?filters[operator]=contains&filters[name]=tags&filters[values][0]=cohort-a

In a real URL the serialised form is percent-encoded like any query value; curl -G --data-urlencode 'filters={…}' does it for you.

tags holds several values, so a condition compares a list to a list. That is what the three operators are for:

Combining conditions

To require several conditions at once, assemble them with and:

{ "operator": "and", "operands": [{ "operator": "contains", "name": "tags", "values": ["cohort-a"] }] }

and earns its place only once you have more than one condition — a single condition needs no wrapper.

Deleting a measurement

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

This removes the stored media — captures, images, video and signals — and then the measurement itself, and answers 200 OK with an empty body. A file that is already gone is not an error, so a deletion interrupted halfway can simply be issued again. Once a deletion has completed, the measure no longer exists, and a second call answers 404.

The result

{
  "id": "3f1a5c88-0b2d-4e6a-9c11-7d5e8a2b4f60",
  "status": "ended",
  "createdAt": "2026-08-24T14:57:44.000Z",
  "startedAt": "2026-08-24T14:57:46.000Z",
  "endedAt": "2026-08-24T14:58:22.000Z",
  "desiredVariables": null,
  "unwantedVariables": null,
  "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_EXTERNAL_ID" }
  },
  "userData": {
    "externalId": null, "sex": "F", "age": 35,
    "weight": 58, "height": 171, "smokingStatus": "non-smoker"
  },
  "tags": ["cohort-a"]
}

A measure that has not ended stops at its state: a created one carries neither startedAt nor anything after it, a started one has no endedAt, returnedVariables, signal or variables. userData is null when none was given, and a field you did not send is null inside it; a dateOfBirth comes back as the age it gave.

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.

scale gives the range of level: 1 to 5 for strs, 1 to 3 for bpClass — or 1 to 2 when you asked for two levels.

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")

Error codes

An error is a code to act on, not a message to show.

The quality indicator

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

signal is null when the measurement had no pulse signal to assess — a measurement made from images, for instance.

To judge whether a measurement is usable, read the individual variables and their error codes: a variable that could not be computed names the reason itself, which is the information a threshold was standing in for.

Work that out on Test data first. Rights and credits are set per account, so what a Test account returns is not necessarily what your Production account will return. Environments sets out the separation.