List 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
}

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

Field	Type	Description
`data`	array	List of device objects
`has_more`	boolean	Whether more results are available

Device Object

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)

Documentation Index

​Authentication

​Query Parameters

​Response

​Response Fields

​Device Object

Authentication

Query Parameters

Response

Response Fields

Device Object