Architecture & Boundaries
Overview
Sensia is designed to be stateless and privacy-first.
- Your application owns the end-user relationship, device pairing, permissions, and biometric data collection.
- Sensia receives a standardized biometric snapshot (
current_session), optional historic data (past_sessionsandpast_targets) and returns the current score obtain by the user.
Responsibility Matrix
To maintain clean separation of concerns and compliance with health data privacy laws, responsibilities are split as follows:
| Task | Responsibility | Handled By | Details |
|---|---|---|---|
| Device Pairing & BLE Communication | Client | Mobile OS / Werable Vendor App | Handled automatically by iOS/Android or manufacturer companion apps. |
| User Consent & Health Permissions | Client | Application | Prompting the user for HealthKit, Health Connect, or OAuth vendor permissions. |
| Biometric Extraction | Client | Application / Backend | Querying raw heart rate, respiratory rate, and sleep stage intervals. |
| Payload Assembly & Normalization | Client | Backend / App | Formatting raw readings into Sensia's current_session schema. |
| API Key Security | Client | Backend | Making requests to Sensia using your private X-API-Key. Never expose API keys in mobile binaries. |
| Data Processing | Sensia | Sensia | Processing the incoming data, validating data schemas, and computing missing values. |
| Neural Inference & Scoring | Sensia | Sensia | Processing time-series features and producing cognitive/emotional metrics. |
| Data Retention of Biometrics | Client | Backend / App | Sensia does not store your raw biometric data; it processes requests ephemerally. |
If the column Handled By presents multiple options, usually the first option is preferred for security and privacy reasons. For example, while a mobile app could assemble the payload and call Sensia directly, it is strongly recommended to do this in your backend to avoid exposing your API key.
Two Primary Architectures
Depending on your product architecture, there are two standard patterns to feed data into Sensia:
Architecture A: On-Device Mobile Native (HealthKit / Health Connect)
Best suited for consumer mobile apps where users wear an Apple Watch, Wear OS device, or sync their wearables to Apple Health or Google Health Connect.
Learn how to implement this in the Mobile Native Guide.
Architecture B: Cloud-to-Cloud / Aggregator (OpenWearables, Terra, Vendor APIs)
Best suited for web platforms, multi-device enterprise systems, or backends utilizing unified wearable aggregator APIs (such as OpenWearables or Terra) or direct vendor cloud webhooks (Garmin Connect, Whoop, Oura).
Learn how to implement this in the Cloud Aggregators Guide.
Frequently Asked Questions
Can Sensia read directly from my user's Apple Watch without our app?
No. Apple HealthKit and Android Health Connect are privacy-sandboxed on the user's phone. Third-party cloud services cannot pull data from a user's phone without a client application installed on the phone that has requested and received user permission.
Why shouldn't our mobile app call Sensia directly?
While technically possible, calling POST https://api.sensia.ai/predict directly from a mobile client exposes your Sensia X-API-Key to reverse-engineering or decompilation. We strongly recommend proxying calls through your own backend where your API key remains secure.
What wearable hardware does Sensia support?
Because Sensia operates on standardized physiological inputs (Heart Rate, Respiratory Rate, and Sleep Data), Sensia is compatible with any wearable on the market that can record these metrics. The list of supported wearables includes, but is not limited to, Apple Watch, Garmin, Whoop, Oura Ring, Samsung Galaxy Watch, Fitbit, Suunto, Coros and medical-grade sensors. In general, any wearable device equipped with a PPG sensor is capable of producing the required data.
What if a wearable doesn't capture field X?
The Sensia model is robust to missing fields. If some data is unavailable from a specific wearable model, you can simply pass an empty array. However, supplying as many biometric indicators as possible produces the highest prediction fidelity.