Mesures

Une mesure traverse trois états : created, started, puis ended. Vous pouvez la mener en un appel, ou en deux.

Les routes

Les routes « créer et exécuter » sont celles vers lesquelles se tourner. Elles répondent 201 Created ; exécuter une mesure existante répond 200 OK. Les deux rendent la mesure. La forme en deux temps existe pour les cas où il vous faut l’identifiant avant d’avoir le média — c’est ainsi que fonctionne le widget v1 : votre serveur crée la mesure, et le widget l’exécute. Une mesure ne s’exécute qu’une fois : en exécuter une déjà démarrée est refusé par un 400.

Cette page détaille les routes vidéo et images. Les corps des routes de captures et de signal sont dans la référence OpenAPI.

Décrire la personne

Plusieurs variables ne se calculent pas à partir du seul signal. userData est l’endroit où vous dites ce qu’il faut.

Tous les champs sont facultatifs. Ce que vous omettez ne fait que réduire ce qui peut être calculé :

bp se calibre personne par personne. Elle demande un externalId, et une mesure antérieure et complète de cette même personne pour laquelle une tension de référence a été saisie — seul le formulaire de fin de mesure du widget v1 en enregistre une aujourd’hui. Sans elle, bp revient avec NOT_CALIBRATED. GET /external-users/{externalId} répond { "externalId", "rppgCalibrated", "cppgCalibrated" }, ou 404 quand aucune de vos mesures ne porte cet identifiant.

Choisir les variables

Deux tableaux facultatifs réduisent ce qui est calculé :

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

Omettez les deux et la mesure calcule tout ce à quoi votre compte a droit.

Deux autres champs facultatifs se tiennent à côté. tags est une liste d’étiquettes à vous, 1000 au plus, rendue avec la mesure et qui sert à filtrer la liste. computeOptions règle la façon dont une variable s’exprime : { "bpClass": { "scale": 2 } } rend bpClass sur deux niveaux — normal, ou non — au lieu de trois.

Envoyer une vidéo enregistrée

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

L’appel ci-dessous s’adresse à la Production. Envoyez-le au Test tant que vous vérifiez encore votre chaîne : les mesures qui y sont faites n’apparaissent jamais dans vos données de Production.

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"

La réponse, 201 Created, est la mesure aboutie — la même forme que celle livrée par le widget.

Envoyer des images

POST /measures/rppg/images

Les autres parties sont celles de la route vidéo.

Relire une mesure

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

Les mesures appartenant à un autre client rendent 404, exactement comme une mesure inexistante.

Lister ses mesures

GET /measures
Authorization: Bearer <apiKey>

Vous ne voyez jamais que les vôtres. Les mesures d’un autre client ne sont pas refusées : elles sont simplement absentes.

La liste n’est pas triée, et son ordre n’est pas garanti d’un appel à l’autre : pour parcourir un grand ensemble page par page, réduisez-le par un filtre plutôt que de vous fier à skip seul. filters ne s’applique qu’à GET /measures — GET /measures/rppg et GET /measures/cppg l’acceptent sans l’appliquer.

Filtrer par étiquette

Un filtre est une condition — un champ, un opérateur, et les valeurs auxquelles le comparer :

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

Il voyage en un seul paramètre de query, écrit sérialisé ou éclaté — les deux sont acceptés et disent la même chose :

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

Dans une vraie adresse, la forme sérialisée est encodée en pourcentage comme toute valeur de query ; curl -G --data-urlencode 'filters={…}' s’en charge pour vous.

tags porte plusieurs valeurs : une condition y compare donc une liste à une liste. C’est ce à quoi servent les trois opérateurs :

Réunir plusieurs conditions

Pour en exiger plusieurs à la fois, réunissez-les par un and :

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

and ne se justifie qu’à partir de deux conditions — une condition seule n’a besoin d’aucune enveloppe.

Supprimer une mesure

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

Cet appel retire les médias conservés — captures, images, vidéo et signaux — puis la mesure elle-même, et répond 200 OK avec un corps vide. Un objet absent n’est pas une erreur, de sorte qu’une suppression interrompue à mi-course se relance simplement. Une fois une suppression menée à son terme, la mesure n’existe plus, et un second appel répond 404.

Le résultat

{
  "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"]
}

Une mesure qui n’est pas terminée s’arrête à son état : une mesure created ne porte ni startedAt ni rien de ce qui suit, une mesure started n’a ni endedAt, ni returnedVariables, ni signal, ni variables. userData vaut null quand rien n’a été fourni, et un champ que vous n’avez pas envoyé y vaut null ; une dateOfBirth revient sous la forme de l’age qu’elle donnait.

returnedVariables est un droit, non un résultat

C’est le champ le plus souvent mal lu. Il énumère les variables que votre compte client a le droit de recevoir, réduites par les desiredVariables / unwantedVariables que vous avez passés. Il n’énumère pas ce qui a réussi.

Formes des valeurs

Chaque variable est l’une de deux choses : une valeur avec error: null, ou value: null accompagné d’un code d’erreur.

scale donne l’étendue de level : de 1 à 5 pour strs, de 1 à 3 pour bpClass — ou de 1 à 2 quand vous avez demandé deux niveaux.

Testez toujours error en premier :

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

Codes d’erreur

Une erreur est un code sur lequel agir, non un message à afficher.

L’indicateur de qualité

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

signal vaut null quand la mesure n’avait aucun signal de pouls à évaluer — une mesure faite depuis des images, par exemple.

Pour juger si une mesure est exploitable, lisez les variables une à une et leurs codes d’erreur : une variable qui n’a pas pu être calculée nomme elle-même le motif, qui est l’information qu’un seuil remplaçait.

Établissez ce jugement sur des données de Test d’abord. Les droits et les crédits se règlent par compte, si bien que ce que rend un compte de Test n’est pas nécessairement ce que rendra votre compte de Production. Environnements expose la séparation.