Register Device

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

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 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",
    "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

serial_number

string

required

Device serial number (unique identifier from hardware).

model

string

required

Device model. One of bota_pin, bota_pin_pro, or bota_note.

firmware_version

string

Current firmware version on the device.

metadata

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 the id 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 device is registered elsewhere or is inaccessible to this project.

Delete End User List Devices

​Authentication

​Request Body

​Response

​Response Fields

​Resolving a Device ID from a Serial Number

Authentication

Request Body

Response

Response Fields

Resolving a Device ID from a Serial Number