Skip to main content
POST
/
devices
curl -X POST https://api.bota.dev/v1/devices \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "serial_number": "SN-2025-001234",
    "device_type": "bota_pin_v1",
    "firmware_version": "1.2.0"
  }'

{
  "id": "dev_abc123",
  "serial_number": "SN-2025-001234",
  "device_type": "bota_pin_v1",
  "firmware_version": "1.2.0",
  "status": "unbound",
  "end_user_id": null,
  "metadata": null,
  "created_at": "2025-01-15T10:30:00Z",
  "bound_at": null
}
Register a device using its serial number. If a device with the same serial number already exists, the existing device is returned.

​
Authentication

Requires an API key with devices:write scope. 
curl -X POST https://api.bota.dev/v1/devices \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "serial_number": "SN-2025-001234",
    "device_type": "bota_pin_v1",
    "firmware_version": "1.2.0"
  }'

​
Request Body

​
serial_number
string
required
Device serial number (unique identifier from hardware).
​
device_type
string
Type or model of device (e.g., bota_pin_v1).
​
firmware_version
string
Current firmware version on the device.
​
metadata
object
Arbitrary key-value metadata.

​
Response

Returns the device object. Returns 201 for newly created devices or 200 if a device with the same serial number already exists. 
{
  "id": "dev_abc123",
  "serial_number": "SN-2025-001234",
  "device_type": "bota_pin_v1",
  "firmware_version": "1.2.0",
  "status": "unbound",
  "end_user_id": null,
  "metadata": null,
  "created_at": "2025-01-15T10:30:00Z",
  "bound_at": null
}

​
Response Fields

FieldTypeDescription
idstringDevice identifier (dev_*)
serial_numberstringPhysical serial number
modelstringDevice model (bota_pin or bota_note)
firmware_versionstring | nullCurrent firmware version
statusstringunbound or bound
end_user_idstring | nullBound end user (eu_*), null if unbound
battery_percentinteger | nullBattery level (0-100), null if no heartbeat received
storage_used_mbinteger | nullStorage used in MB
storage_total_mbinteger | nullTotal storage capacity in MB
signal_strength_dbminteger | nullSignal strength in dBm
last_heartbeat_atstring | nullLast heartbeat timestamp (ISO 8601)
recording_stateobject | nullCurrent recording state (device_state, pending_recordings, flags, connection_type[])
metadataobjectCustom key-value metadata
created_atstringCreation timestamp (ISO 8601)
updated_atstringLast update timestamp (ISO 8601)
If a device with the same serial number already exists, the existing device is returned with a 200 status instead of 201.