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",
"model": "bota_pin",
"firmware_version": "1.2.0"
}'
const response = await fetch('https://api.bota.dev/v1/devices', {
method: 'POST',
headers: {
'Authorization': 'Bearer sk_live_...',
'Content-Type': 'application/json',
},
body: JSON.stringify({
serial_number: 'SN-2025-001234',
model: 'bota_pin',
firmware_version: '1.2.0',
}),
});
const device = await response.json();
import requests
response = requests.post(
'https://api.bota.dev/v1/devices',
headers={
'Authorization': 'Bearer sk_live_...',
'Content-Type': 'application/json',
},
json={
'serial_number': 'SN-2025-001234',
'model': 'bota_pin',
'firmware_version': '1.2.0',
},
)
device = response.json()
{
"id": "dev_abc123",
"serial_number": "SN-2025-001234",
"model": "bota_pin",
"firmware_version": "1.2.0",
"status": "unbound",
"end_user_id": null,
"metadata": {},
"created_at": "2025-01-15T10:30:00Z",
"updated_at": "2025-01-15T10:30:00Z"
}
{
"error": {
"code": "resource_already_exists",
"message": "Device with serial_number 'SN-2025-001234' is already registered"
}
}
Devices
Register Device
Register a wearable device in your project
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",
"model": "bota_pin",
"firmware_version": "1.2.0"
}'
const response = await fetch('https://api.bota.dev/v1/devices', {
method: 'POST',
headers: {
'Authorization': 'Bearer sk_live_...',
'Content-Type': 'application/json',
},
body: JSON.stringify({
serial_number: 'SN-2025-001234',
model: 'bota_pin',
firmware_version: '1.2.0',
}),
});
const device = await response.json();
import requests
response = requests.post(
'https://api.bota.dev/v1/devices',
headers={
'Authorization': 'Bearer sk_live_...',
'Content-Type': 'application/json',
},
json={
'serial_number': 'SN-2025-001234',
'model': 'bota_pin',
'firmware_version': '1.2.0',
},
)
device = response.json()
{
"id": "dev_abc123",
"serial_number": "SN-2025-001234",
"model": "bota_pin",
"firmware_version": "1.2.0",
"status": "unbound",
"end_user_id": null,
"metadata": {},
"created_at": "2025-01-15T10:30:00Z",
"updated_at": "2025-01-15T10:30:00Z"
}
{
"error": {
"code": "resource_already_exists",
"message": "Device with serial_number 'SN-2025-001234' is already registered"
}
}
Register a device using its serial number. The response includes the Bota device ID (
dev_*) that you use for later device APIs such as bind, heartbeat, commands, and settings.
Store the returned
id alongside the device serial number in your system. If the mapping is unavailable later, recover it with GET /devices?serial_number={serial_number}.Authentication
Requires an API key withdevices: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",
"model": "bota_pin",
"firmware_version": "1.2.0"
}'
const response = await fetch('https://api.bota.dev/v1/devices', {
method: 'POST',
headers: {
'Authorization': 'Bearer sk_live_...',
'Content-Type': 'application/json',
},
body: JSON.stringify({
serial_number: 'SN-2025-001234',
model: 'bota_pin',
firmware_version: '1.2.0',
}),
});
const device = await response.json();
import requests
response = requests.post(
'https://api.bota.dev/v1/devices',
headers={
'Authorization': 'Bearer sk_live_...',
'Content-Type': 'application/json',
},
json={
'serial_number': 'SN-2025-001234',
'model': 'bota_pin',
'firmware_version': '1.2.0',
},
)
device = response.json()
Request Body
string
required
Device serial number (lifetime-unique hardware identity). A serial remains reserved after device deletion and cannot be registered as a new device row.
string
required
Device model. One of
bota_pin, bota_pin_pro, or bota_note.string
Current firmware version on the device.
object
Arbitrary key-value metadata.
Response
Returns the newly registered device object.{
"id": "dev_abc123",
"serial_number": "SN-2025-001234",
"model": "bota_pin",
"firmware_version": "1.2.0",
"status": "unbound",
"end_user_id": null,
"metadata": {},
"created_at": "2025-01-15T10:30:00Z",
"updated_at": "2025-01-15T10:30:00Z"
}
{
"error": {
"code": "resource_already_exists",
"message": "Device with serial_number 'SN-2025-001234' is already registered"
}
}
Response Fields
| Field | Type | Description |
|---|---|---|
id | string | Device identifier (dev_*) |
serial_number | string | Physical serial number |
model | string | Device model (bota_pin or bota_note) |
firmware_version | string | null | Current firmware version |
status | string | unbound or bound |
end_user_id | string | null | Bound end user (eu_*), null if unbound |
battery_percent | integer | null | Battery level (0-100), null if no heartbeat received |
storage_used_mb | integer | null | Storage used in MB |
storage_total_mb | integer | null | Total storage capacity in MB |
signal_strength_dbm | integer | null | Signal strength in dBm |
last_heartbeat_at | string | null | Last heartbeat timestamp (ISO 8601) |
recording_state | object | null | Current recording state (device_state, pending_recordings, flags, connection_type[]) |
metadata | object | Custom key-value metadata |
created_at | string | Creation timestamp (ISO 8601) |
updated_at | string | Last update timestamp (ISO 8601) |
Resolving a Device ID from a Serial Number
For a newly registered device, use theid returned by this endpoint.
For an already registered device, use the exact List Devices serial_number filter. If registration returns 409 and the filter returns a device, reuse its dev_* ID. If the filter returns an empty data array, the serial is reserved by a device that is registered elsewhere, deleted, or inaccessible to this project. The API does not disclose which case applies.Was this page helpful?