List Devices

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

const response = await fetch('https://api.bota.dev/v1/devices?limit=10', {
  headers: {
    'Authorization': 'Bearer sk_live_...',
  },
});

const { data, has_more } = await response.json();

import requests

response = requests.get(
    'https://api.bota.dev/v1/devices',
    headers={'Authorization': 'Bearer sk_live_...'},
    params={'limit': 10},
)

result = response.json()
devices = result['data']

{
  "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_..."

const response = await fetch('https://api.bota.dev/v1/devices?limit=10', {
  headers: {
    'Authorization': 'Bearer sk_live_...',
  },
});

const { data, has_more } = await response.json();

import requests

response = requests.get(
    'https://api.bota.dev/v1/devices',
    headers={'Authorization': 'Bearer sk_live_...'},
    params={'limit': 10},
)

result = response.json()
devices = result['data']

{
  "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_..."

const response = await fetch('https://api.bota.dev/v1/devices?limit=10', {
  headers: {
    'Authorization': 'Bearer sk_live_...',
  },
});

const { data, has_more } = await response.json();

import requests

response = requests.get(
    'https://api.bota.dev/v1/devices',
    headers={'Authorization': 'Bearer sk_live_...'},
    params={'limit': 10},
)

result = response.json()
devices = result['data']

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.

serial_number

string

Return the device whose serial number exactly matches this value (1-64 characters). The lookup is scoped to the authenticated project and returns at most one item. When combined with end_user_id, this filter takes precedence.

Find a Device by Serial Number

Use the serial_number filter to recover the Bota device ID (dev_*) for a device visible to your project:

Node.js

const targetSerial = 'SN-2025-001234';
const url = new URL('https://api.bota.dev/v1/devices');
url.searchParams.set('serial_number', targetSerial);

const response = await fetch(url, {
  headers: { Authorization: 'Bearer sk_test_...' },
});
const { data } = await response.json();
const device = data[0];

if (device) {
  console.log(device.id);
}

Matching is exact and case-sensitive. An empty data array means the serial number does not exist or is not accessible to the authenticated project; the API does not reveal which case applies. If registration returns 409 Conflict, query this filter. Reuse the returned dev_* ID when a match is found. If the result is empty, the device belongs elsewhere or is otherwise inaccessible.

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)

​Authentication

​Query Parameters

​Find a Device by Serial Number

​Response

​Response Fields