Skip to main content
POST
/
devices
/
{id}
/
heartbeat
curl -X POST https://api.bota.dev/v1/devices/dev_abc123/heartbeat \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "battery_percent": 85,
    "storage_used_mb": 512,
    "storage_total_mb": 32768,
    "device_state": "idle",
    "pending_recordings": 3,
    "connection_type": ["ble"]
  }'

{
  "status": "ok"
}
Report device health status including battery level, storage usage, and signal strength. Health data is stored on the device record and returned in Get Device and List Devices responses.

​
Authentication

This endpoint accepts two authentication methods depending on the device connectivity:
PathAuthUse case
4G/WiFi directDevice tokenDevice reports its own status directly
BLE relayAPI keyDeveloper’s backend relays status read from device over BLE
curl -X POST https://api.bota.dev/v1/devices/dev_abc123/heartbeat \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "battery_percent": 85,
    "storage_used_mb": 512,
    "storage_total_mb": 32768,
    "device_state": "idle",
    "pending_recordings": 3,
    "connection_type": ["ble"]
  }'

​
Path Parameters

​
id
string
required
The device’s unique identifier (e.g., dev_abc123), or me when using a device token. The me alias resolves to the device ID associated with the token, so the device doesn’t need to know its own Bota ID. When using an explicit device ID with a device token, it must match the token’s device.

​
Request Body

All fields are optional — send only the metrics your device can report.
​
battery_percent
integer
Current battery level (0-100).
​
storage_used_mb
integer
Storage used in megabytes.
​
storage_total_mb
integer
Total storage capacity in megabytes.
​
signal_strength_dbm
integer
Cellular signal strength in dBm (typically -50 to -120, where higher/less negative is better).
​
firmware_version
string
Current firmware version string (max 32 characters).
​
device_name
string
Device name (max 64 characters). Updated in the device record when provided.
​
device_state
string
Current device operational state (max 32 characters). One of: idle, recording, syncing, uploading, charging, lowBattery, storageFull, error.
​
pending_recordings
integer
Number of recordings on the device pending sync/upload.
​
flags
integer
Device status flags as a 1-byte bitmask (0-255). Bit 0: charging, Bit 1: low battery, Bit 2: storage full, Bit 3: WiFi connected, Bit 4: LTE connected, Bit 5: sync active.
​
connection_type
string[]
Active device connections. Array of: wifi, 4g, ble.

​
Response

Returns { "status": "ok" } on success. 
{
  "status": "ok"
}

​
Response Fields

FieldTypeDescription
statusstringok on success
ScenarioInterval
Normal operationEvery 15-30 minutes
Low battery (< 20%)Every 5 minutes
ChargingEvery 30-60 minutes
Poor signal (< -100 dBm)Every 5-10 minutes

​
Field Constraints

FieldTypeRange
battery_percentinteger0-100
storage_used_mbinteger>= 0
storage_total_mbinteger>= 0
signal_strength_dbminteger<= 0 (typically -50 to -120)
firmware_versionstringmax 32 characters
device_namestringmax 64 characters
device_statestringmax 32 characters
pending_recordingsinteger>= 0
flagsinteger0-255
connection_typestring[]Array of wifi, 4g, ble