Device Ingestion API
EndpointPOST
AuthTokenAuthorization: Bearer header
Modules0
Telemetry Ingestion Endpoint
Devices send sensor readings via HTTPS POST. Each request is authenticated by the device's API token (issued when you add a device), processed through the alert engine, and stored in the telemetry database.
📡 POST /api/telemetry-ingest
Headers:
Authorization: Bearer <device_api_token>
Content-Type: application/json
Body — one reading per metric, as a flat object of numeric values:
{
"data": {
"systolic": 178,
"diastolic": 110,
"heart_rate": 122,
"spo2": 89,
"temperature": 37.2,
"fall_detected": 0
},
"recorded_at": "2026-08-24 12:00:00"
}
Boolean-style flags (fall_detected, panic_pressed, impact_detected, etc.)
are sent the same way, as 0/1 values inside "data" — the alert engine
matches on metric_name, so there's no separate "flags" object.
"recorded_at" is optional (defaults to server time when omitted).
Batch alternative — send explicit readings instead of "data":
{
"readings": [
{ "metric_name": "temperature", "metric_value": 37.2, "unit": "°C" },
{ "metric_name": "heart_rate", "metric_value": 122 }
]
}
Response (200):
{ "ok": true, "inserted": 2, "device_id": 42 }
Response (401):
{ "error": "Invalid device token." }
Response (400) — payload had no recognizable numeric metrics:
{ "error": "No metrics found in payload. Send {\"data\":{\"metric_name\":value,...}}, {\"readings\":[...]}, or {\"metric_name\":\"...\",\"metric_value\":...}." }
Every heartbeat (any successful POST to this endpoint) also marks the device online and updates its last-seen timestamp — you don't need a separate heartbeat call unless a device has no sensor data to report yet. See Webhooks for the standalone heartbeat-only endpoint.
Module-Specific Payload Examples
| Module | Metrics | Flags |
|---|---|---|
| health | systolic, diastolic, heart_rate, spo2, temperature, glucose | fall_detected, panic_pressed |
| vehicle | speed_kmh, heading, fuel_level | impact_detected, impact_g_force, geofence_breach |
| factory | gas_ppm, gas_type, temperature, humidity, smoke_level | fire_detected |
| home_infra | temperature | water_leak, power_failure, high_temperature |
| worker | steps | fall_detected, panic_pressed, inactivity |
| fleet | speed_kmh, fuel_level | geofence_breach |
📦 Ingestion Pipeline
1. Validate device token → 2. Insert into telemetry_logs → 3. Upsert device_metrics_latest → 4. Update device status → 5. Insert GPS if present → 6. Insert module event → 7. Run alert engine → 8. Return {"status":"ok"}