Update Device

curl -X PATCH https://api.bota.dev/v1/devices/dev_abc123 \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "firmware_version": "1.3.0",
    "settings": {
      "connection": {
        "enabled_connections": { "wifi": true, "cellular": false },
        "upload_network_preference": ["wifi", "ble"]
      }
    }
  }'

const device = await bota.devices.update('dev_abc123', {
  firmware_version: '1.3.0',
  settings: {
    connection: {
      enabled_connections: { wifi: true, cellular: false },
      upload_network_preference: ['wifi', 'ble']
    }
  }
});

device = bota.devices.update('dev_abc123', {
  'firmware_version': '1.3.0',
  'settings': {
    'connection': {
      'enabled_connections': { 'wifi': True, 'cellular': False },
      'upload_network_preference': ['wifi', 'ble']
    }
  }
})

{
  "id": "dev_abc123",
  "serial_number": "SN-2025-001234",
  "model": "bota_pin",
  "firmware_version": "1.3.0",
  "status": "bound",
  "end_user_id": "eu_xyz789",
  "metadata": {},
  "settings": {
    "connection": {
      "enabled_connections": { "wifi": true, "cellular": false },
      "upload_network_preference": ["wifi", "ble"],
      "power_management": {
        "wifi_idle_timeout_seconds": 180,
        "cellular_idle_timeout_seconds": 180
      }
    },
    "upload": {
      "streaming_enabled": true,
      "streaming_chunk_kb": 256,
      "daily_data_limit_mb": 500,
      "allow_roaming": false,
      "pause_on_low_battery": true,
      "off_peak_hours": null
    },
    "audio": {
      "codec": "opus",
      "sample_rate_khz": 16,
      "bitrate_kbps": 32
    },
    "power": {
      "auto_sleep_minutes": 30,
      "low_battery_threshold_percent": 20
    }
  },
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T14:20:00Z"
}

{
  "error": {
    "code": "not_found",
    "message": "Device not found"
  }
}

PATCH

devices

{id}

curl -X PATCH https://api.bota.dev/v1/devices/dev_abc123 \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "firmware_version": "1.3.0",
    "settings": {
      "connection": {
        "enabled_connections": { "wifi": true, "cellular": false },
        "upload_network_preference": ["wifi", "ble"]
      }
    }
  }'

const device = await bota.devices.update('dev_abc123', {
  firmware_version: '1.3.0',
  settings: {
    connection: {
      enabled_connections: { wifi: true, cellular: false },
      upload_network_preference: ['wifi', 'ble']
    }
  }
});

device = bota.devices.update('dev_abc123', {
  'firmware_version': '1.3.0',
  'settings': {
    'connection': {
      'enabled_connections': { 'wifi': True, 'cellular': False },
      'upload_network_preference': ['wifi', 'ble']
    }
  }
})

{
  "id": "dev_abc123",
  "serial_number": "SN-2025-001234",
  "model": "bota_pin",
  "firmware_version": "1.3.0",
  "status": "bound",
  "end_user_id": "eu_xyz789",
  "metadata": {},
  "settings": {
    "connection": {
      "enabled_connections": { "wifi": true, "cellular": false },
      "upload_network_preference": ["wifi", "ble"],
      "power_management": {
        "wifi_idle_timeout_seconds": 180,
        "cellular_idle_timeout_seconds": 180
      }
    },
    "upload": {
      "streaming_enabled": true,
      "streaming_chunk_kb": 256,
      "daily_data_limit_mb": 500,
      "allow_roaming": false,
      "pause_on_low_battery": true,
      "off_peak_hours": null
    },
    "audio": {
      "codec": "opus",
      "sample_rate_khz": 16,
      "bitrate_kbps": 32
    },
    "power": {
      "auto_sleep_minutes": 30,
      "low_battery_threshold_percent": 20
    }
  },
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T14:20:00Z"
}

{
  "error": {
    "code": "not_found",
    "message": "Device not found"
  }
}

Overview

Updates device metadata (firmware version, custom metadata) and/or device settings (upload configuration, audio quality, power management). This endpoint performs a partial update - only fields included in the request body are modified.

Authentication

Requires a valid API key with devices:write scope.

curl -X PATCH https://api.bota.dev/v1/devices/dev_abc123 \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "firmware_version": "1.3.0",
    "settings": {
      "connection": {
        "enabled_connections": { "wifi": true, "cellular": false },
        "upload_network_preference": ["wifi", "ble"]
      }
    }
  }'

const device = await bota.devices.update('dev_abc123', {
  firmware_version: '1.3.0',
  settings: {
    connection: {
      enabled_connections: { wifi: true, cellular: false },
      upload_network_preference: ['wifi', 'ble']
    }
  }
});

device = bota.devices.update('dev_abc123', {
  'firmware_version': '1.3.0',
  'settings': {
    'connection': {
      'enabled_connections': { 'wifi': True, 'cellular': False },
      'upload_network_preference': ['wifi', 'ble']
    }
  }
})

Path Parameters

string

required

Device ID (e.g., dev_abc123)

Request Body

All fields are optional. Only include what you want to update.

firmware_version

string

Firmware version string (max 32 chars)

metadata

object

Custom key-value metadata

settings

object

Device configuration (upload, audio, power)

Show settings properties

connection

object

Connection configuration (which connections are enabled and network preference)

Show connection properties

enabled_connections

object

Which connections are available. Bluetooth is always enabled and cannot be disabled.

Show enabled_connections properties

wifi

boolean

Enable WiFi uploads (default: true)

cellular

boolean

Enable cellular uploads (default: true)

upload_network_preference

string[]

Ordered list of connection types for network preference. Values: wifi, ble, cellular. No duplicates. Default: ["wifi", "ble", "cellular"]

power_management

object

Radio idle timeout configuration. Powers down WiFi/cellular radio after inactivity to save battery.

Show power_management properties

wifi_idle_timeout_seconds

integer

WiFi radio idle timeout in seconds. -1 = never power down, 0 = power down immediately after work completes, positive values wait before power-down. Range: -1, 0, or 10-2540. Default: 180 (3 minutes).

cellular_idle_timeout_seconds

integer

Cellular radio idle timeout in seconds. -1 = never power down, 0 = power down immediately after work completes, positive values wait before power-down. Range: -1, 0, or 10-2540. Default: 180 (3 minutes).

upload

object

Upload behavior configuration

Show upload properties

streaming_enabled

boolean

Upload chunks while recording (streaming upload mode)

streaming_chunk_kb

integer

Streaming chunk size in KB. Range: 64-1024. Default: 256.

daily_data_limit_mb

integer

Max cellular data per day in MB (0-10000). 0 = unlimited.

allow_roaming

boolean

Allow cellular uploads when roaming

pause_on_low_battery

boolean

Pause uploads when battery is low

off_peak_hours

object

Schedule uploads during off-peak hours only

Show off_peak_hours properties

enabled

boolean

Enable off-peak scheduling

start

string

Start time in HH:MM format (e.g., "22:00")

end

string

End time in HH:MM format (e.g., "06:00")

timezone

string

IANA timezone (e.g., "America/New_York")

audio

object

Audio quality configuration

Show audio properties

codec

string

opus | aac | wav

sample_rate_khz

integer

16 | 24 | 48

bitrate_kbps

integer

8 - 320

power

object

Power management configuration

Show power properties

auto_sleep_minutes

integer

Auto-sleep timeout (1-120)

low_battery_threshold_percent

integer

Low battery threshold (5-30)

Response

Returns the updated device object with all settings (including defaults).

{
  "id": "dev_abc123",
  "serial_number": "SN-2025-001234",
  "model": "bota_pin",
  "firmware_version": "1.3.0",
  "status": "bound",
  "end_user_id": "eu_xyz789",
  "metadata": {},
  "settings": {
    "connection": {
      "enabled_connections": { "wifi": true, "cellular": false },
      "upload_network_preference": ["wifi", "ble"],
      "power_management": {
        "wifi_idle_timeout_seconds": 180,
        "cellular_idle_timeout_seconds": 180
      }
    },
    "upload": {
      "streaming_enabled": true,
      "streaming_chunk_kb": 256,
      "daily_data_limit_mb": 500,
      "allow_roaming": false,
      "pause_on_low_battery": true,
      "off_peak_hours": null
    },
    "audio": {
      "codec": "opus",
      "sample_rate_khz": 16,
      "bitrate_kbps": 32
    },
    "power": {
      "auto_sleep_minutes": 30,
      "low_battery_threshold_percent": 20
    }
  },
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T14:20:00Z"
}

{
  "error": {
    "code": "not_found",
    "message": "Device not found"
  }
}

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_*`)
`battery_percent`	integer \| null	Battery level (0-100)
`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
`metadata`	object	Custom key-value metadata
`settings`	object	Device settings including connection, upload, audio, and power configuration
`created_at`	string	Creation timestamp (ISO 8601)
`updated_at`	string	Last update timestamp (ISO 8601)

Examples

Update Connection Settings Only

cURL

curl -X PATCH https://api.bota.dev/v1/devices/dev_abc123 \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"settings": {"connection": {"upload_network_preference": ["cellular", "wifi", "ble"]}}}'

Configure Radio Idle Timeouts

cURL

curl -X PATCH https://api.bota.dev/v1/devices/dev_abc123 \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"settings": {"connection": {"power_management": {"wifi_idle_timeout_seconds": 300, "cellular_idle_timeout_seconds": 60}}}}'

Update Firmware Version

cURL

curl -X PATCH https://api.bota.dev/v1/devices/dev_abc123 \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"firmware_version": "1.4.0"}'

Update Custom Metadata

cURL

curl -X PATCH https://api.bota.dev/v1/devices/dev_abc123 \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"metadata": {"department": "Sales", "region": "West"}}'

Travel Mode Preset

cURL

curl -X PATCH https://api.bota.dev/v1/devices/dev_abc123 \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {
      "connection": {
        "enabled_connections": { "wifi": true, "cellular": false },
        "upload_network_preference": ["wifi", "ble"]
      },
      "upload": {
        "allow_roaming": false
      }
    }
  }'

Notes

Settings Merge: When updating settings, a deep merge is performed. Only the specified nested fields are updated; others remain unchanged.

Defaults Included: The response always includes complete settings with defaults filled in, even if you only updated one field.

Get Device - Fetch device details
Create Device - Create new device
Bind Device - Bind to end user

Get Device State Bind Device

​Overview

​Authentication

​Path Parameters

​Request Body

​Response

​Response Fields

​Examples

​Update Connection Settings Only

​Configure Radio Idle Timeouts

​Update Firmware Version

​Update Custom Metadata

​Travel Mode Preset

​Notes

​Related Endpoints

Overview

Authentication

Path Parameters

Request Body

Response

Response Fields

Examples

Update Connection Settings Only

Configure Radio Idle Timeouts

Update Firmware Version

Update Custom Metadata

Travel Mode Preset

Notes

Related Endpoints