Skip to main content
GET
/
devices
curl "https://api.bota.dev/v1/devices?limit=10" \
  -H "Authorization: Bearer sk_live_..."

{
  "data": [
    {
      "id": "dev_abc123",
      "serial_number": "SN-2025-001234",
      "model": "bota_pin",
      "firmware_version": "1.2.3",
      "status": "bound",
      "end_user_id": "eu_xyz789",
      "battery_percent": 85,
      "storage_used_mb": 512,
      "storage_total_mb": 32768,
      "signal_strength_dbm": -75,
      "last_heartbeat_at": "2025-01-15T11:30:00Z",
      "recording_state": {
        "device_state": "idle",
        "pending_recordings": 3,
        "connection_type": ["ble"]
      },
      "metadata": {},
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-01-15T11:00:00Z"
    },
    {
      "id": "dev_def456",
      "serial_number": "SN-2025-005678",
      "model": "bota_pin",
      "firmware_version": "1.1.0",
      "status": "unbound",
      "end_user_id": null,
      "battery_percent": null,
      "storage_used_mb": null,
      "storage_total_mb": null,
      "signal_strength_dbm": null,
      "last_heartbeat_at": null,
      "recording_state": null,
      "metadata": {},
      "created_at": "2025-01-14T09:00:00Z",
      "updated_at": "2025-01-14T09:00:00Z"
    }
  ],
  "has_more": false
}
Retrieve a paginated list of devices in your project, optionally filtered by end user.

​
Authentication

Requires an API key with devices:read scope. 
curl "https://api.bota.dev/v1/devices?limit=10" \
  -H "Authorization: Bearer sk_live_..."

​
Query Parameters

​
limit
integer
default:"25"
Maximum number of items to return (1-100).
​
offset
integer
default:"0"
Number of items to skip for pagination.
​
end_user_id
string
Filter devices by bound end user.

​
Response

Returns a paginated list of device objects. 
{
  "data": [
    {
      "id": "dev_abc123",
      "serial_number": "SN-2025-001234",
      "model": "bota_pin",
      "firmware_version": "1.2.3",
      "status": "bound",
      "end_user_id": "eu_xyz789",
      "battery_percent": 85,
      "storage_used_mb": 512,
      "storage_total_mb": 32768,
      "signal_strength_dbm": -75,
      "last_heartbeat_at": "2025-01-15T11:30:00Z",
      "recording_state": {
        "device_state": "idle",
        "pending_recordings": 3,
        "connection_type": ["ble"]
      },
      "metadata": {},
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-01-15T11:00:00Z"
    },
    {
      "id": "dev_def456",
      "serial_number": "SN-2025-005678",
      "model": "bota_pin",
      "firmware_version": "1.1.0",
      "status": "unbound",
      "end_user_id": null,
      "battery_percent": null,
      "storage_used_mb": null,
      "storage_total_mb": null,
      "signal_strength_dbm": null,
      "last_heartbeat_at": null,
      "recording_state": null,
      "metadata": {},
      "created_at": "2025-01-14T09:00:00Z",
      "updated_at": "2025-01-14T09:00:00Z"
    }
  ],
  "has_more": false
}

​
Response Fields

FieldTypeDescription
dataarrayList of device objects
has_morebooleanWhether more results are available

​
Device Object

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)