> ## Documentation Index > Fetch the complete documentation index at: https://docs.stealthera.in/llms.txt > Use this file to discover all available pages before exploring further. # Safety — Location Track + Device Alarms > Returns GPS location history and device-scoped alarm log in a single response. Triggers **two** parallel reads (`healthData` history + `alarms` filtered by `deviceId`). **Replaces individual endpoint:** `/locationtrack` **Adds:** device-scoped alarm list (previously only available via the global `/api/alarms` endpoint). **Response shape:** ```json { "deviceId": "string", "locationtrack": { "deviceId": "string", "date": "YYYY-MM-DD", "tracks": [{ "lat": number, "lng": number, "time": "string" }], "lastLocation": { "lat": number, "lng": number } | null }, "alarms": [{ "id", "nickname", "deviceId", "type", "time", "location", "content" }] } ``` **Location sub-fields:** | Field | Type | Description | |---|---|---| | `tracks` | array | GPS points `[{ lat, lng, time, locateType }]` (`locateType`: `GPS` / `WiFi` / `Base station`) | | `lastLocation` | object\|null | Most recent GPS fix, or `null` | **Alarm fields:** | Field | Type | Description | |---|---|---| | `id` | string | Alarm document ID | | `type` | string | `Not worn` / `Sleep` / `Heart rate warning` / `Blood oxygen warning` / `Blood pressure warning` / `Temperature warning` / `Blood sugar warning` / `Blood potassium warning` / `Cardiovascular warning` / `Fall` / `Sedentary` / `Low battery` / `SOS` | | `time` | string | Timestamp (IST, YYYY-MM-DD HH:mm:ss) | | `content` | string | Human-readable description | ## OpenAPI ````yaml /openapi.yaml get /api/device/{deviceId}/safety openapi: 3.0.0 info: title: Stealthera API description: >- ## System Architecture ``` ┌──────────────┐ ┌───────────────────┐ ┌────────────────┐ ┌─────────────────────┐ │ │ │ │ │ │ │ │ │ Wearable │──────▶ │ Stealthera Cloud │──────▶ │ Stealthera API │──────▶ │ Client Platform │ │ Device │ │ │ │ │ │ │ └──────────────┘ └───────────────────┘ └────────────────┘ └─────────────────────┘ Stealthera Device Cloud Ingestion REST Endpoints Hospital Apps / HIS / Smartwatch Backend (This Document) EMR / Cloud Infra ``` Stealthera exposes standardized APIs which can be consumed by hospital applications, HIS platforms, EMR systems, or client-hosted cloud infrastructure. --- ## Overview The Stealthera API exposes normalized health, safety, and device data collected from Stealthera smartwatches. It is a **pull-based** API: a client is issued a base URL, an API key, and this document, then calls the endpoints below to retrieve data for the devices assigned to them. **Base URL:** `https://api.stealthera.in` **Device ID Example:** `863758060992848` ## Authentication Every request must include the API key in the `X-API-Key` header. Keys are issued per client. Requests without a valid key receive `401 Unauthorized`. ## Data Organization The watch pushes all of its data to the Stealthera Cloud through a small set of collective upload channels. Stealthera normalizes that data and re-exposes it as **logically grouped read endpoints**, so a client retrieves related metrics in a single call instead of one request per metric: - `/vitals` returns heart rate, blood pressure, blood oxygen, and body temperature together. - `/wellness` returns overview, sleep, heart health (ECG/AF summary), and stress together. - `/diagnostics` returns ECG records. - `/safety` returns location tracks and device alarms together. Per-reading metabolic values (blood sugar, blood ketone, uric acid, blood potassium, body composition) are exposed individually under **More Metrics** because they are measured on demand rather than continuously. ## Data Freshness & Resolution - The device list (`/api/health-data`) and the `overview` block return the **latest** values from the most recent upload. - Time-series metrics return per-day history. Resolution follows the device sampling cadence (typically per-minute where supported; blood pressure is reported as 24 hourly points). Sampling and upload intervals are configurable per deployment. - `lastSeen` / `updateTime` reflect the time of the most recent upload (IST). - All timestamps are India Standard Time (UTC+05:30), formatted `YYYY-MM-DD HH:mm:ss`. ## Responses & Errors All endpoints return `application/json` unless noted. Standard status codes: | Code | Meaning | |---|---| | `200` | Success (may include empty results) | | `401` | Missing or invalid API key | | `404` | Unknown `deviceId` | | `500` | Internal server error | Error responses use the shape `{ "error": "string" }`. **Empty states are not errors:** a metric with no data for the requested day returns an empty array (`[]`) for list fields and `null` for summary values, with `200`. --- ### Endpoint Groups - **Watch Upload** — binary data posted by the watch firmware - **Health Data** — aggregated live device list - **Grouped Device** — per-device health metrics returned in grouped batches (one read per group, used by the dashboard frontend) - **More Metrics** — individual per-device endpoints for blood sugar, blood ketone, uric acid, and blood potassium (separate reads) - **Device Info** — per-device hardware and network metadata - **SOS** — SOS events and call log history - **Alarms** — event / alert log --- ## Migration Note In v1.1 the ten individual device-detail endpoints (`/overview`, `/heartrate`, `/sleep`, `/bloodpressure`, `/bloodoxygen`, `/bodytemp`, `/hearthealth`, `/ecg`, `/pressure`, `/locationtrack`) were consolidated into four grouped endpoints to reduce round-trips and read costs. If you were calling any of those legacy paths, migrate to the grouped equivalents below. --- ## Note This document represents the current **v1.1 API specification**. Future versions will include: - Enhanced authentication and authorization - Device-to-patient mapping workflows - Expanded monitoring and audit capabilities - Advanced integration and interoperability features version: 1.1.0 servers: - url: https://api.stealthera.in security: - apiKey: [] tags: - name: Health Check - name: Watch Upload - name: Health Data - name: Grouped Device description: >- Grouped endpoints — each call triggers one history read and returns all metrics for that group. Used by the dashboard frontend to minimise round-trips. - name: More Metrics description: >- Individual per-reading endpoints for blood sugar, blood ketone, uric acid, blood potassium, and body composition. Each triggers its own read and is used by the "More" tabs in the dashboard. - name: Device Info description: Per-device hardware and network metadata. - name: SOS description: SOS events and call log history. - name: Alarms paths: /api/device/{deviceId}/safety: get: tags: - Grouped Device summary: Safety — Location Track + Device Alarms description: >- Returns GPS location history and device-scoped alarm log in a single response. Triggers **two** parallel reads (`healthData` history + `alarms` filtered by `deviceId`). **Replaces individual endpoint:** `/locationtrack` **Adds:** device-scoped alarm list (previously only available via the global `/api/alarms` endpoint). **Response shape:** ```json { "deviceId": "string", "locationtrack": { "deviceId": "string", "date": "YYYY-MM-DD", "tracks": [{ "lat": number, "lng": number, "time": "string" }], "lastLocation": { "lat": number, "lng": number } | null }, "alarms": [{ "id", "nickname", "deviceId", "type", "time", "location", "content" }] } ``` **Location sub-fields:** | Field | Type | Description | |---|---|---| | `tracks` | array | GPS points `[{ lat, lng, time, locateType }]` (`locateType`: `GPS` / `WiFi` / `Base station`) | | `lastLocation` | object\|null | Most recent GPS fix, or `null` | **Alarm fields:** | Field | Type | Description | |---|---|---| | `id` | string | Alarm document ID | | `type` | string | `Not worn` / `Sleep` / `Heart rate warning` / `Blood oxygen warning` / `Blood pressure warning` / `Temperature warning` / `Blood sugar warning` / `Blood potassium warning` / `Cardiovascular warning` / `Fall` / `Sedentary` / `Low battery` / `SOS` | | `time` | string | Timestamp (IST, YYYY-MM-DD HH:mm:ss) | | `content` | string | Human-readable description | parameters: - name: deviceId in: path schema: type: string required: true description: Device IMEI example: '863758060992848' responses: '200': description: Safety group content: application/json: schema: type: object properties: deviceId: type: string locationtrack: type: object alarms: type: array items: type: object '500': description: Internal server error content: application/json: schema: type: object properties: error: type: string components: securitySchemes: apiKey: type: apiKey in: header name: X-API-Key description: Per-client API key issued by Stealthera. ````