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 },
        "heartbeat_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 },
      heartbeat_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 },
      'heartbeat_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 },
        "heartbeat_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 },
      heartbeat_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 },
      'heartbeat_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 },
        "heartbeat_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 },
      heartbeat_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 },
      'heartbeat_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.

string

Firmware version string (max 32 chars)

object

Custom key-value metadata

object

Device configuration (upload, audio, power)

Show settings properties

object

Connection configuration (which connections are enabled and network preference)

Show connection properties

object

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

Show enabled_connections properties

boolean

Enable WiFi uploads (default: true)

boolean

Enable cellular uploads (default: true)

object

Direct heartbeat channels. WiFi and cellular each default to true; Bluetooth relay is always enabled and routing order is fixed.

Show heartbeat_enabled_connections properties

boolean

Allow direct WiFi heartbeats.

boolean

Allow direct cellular heartbeats.

Disabling both direct paths is valid, but a Bluetooth connection is then required to re-enable one later. A channel is used only when both this flag and the matching enabled_connections flag are true.

string[]

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

object

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

Show power_management properties

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).

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).

object

Upload behavior configuration

Show upload properties

boolean

Upload chunks while recording (streaming upload mode)

integer

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

integer

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

boolean

Allow cellular uploads when roaming

boolean

Pause uploads when battery is low

object

Schedule uploads during off-peak hours only

Show off_peak_hours properties

boolean

Enable off-peak scheduling

string

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

string

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

string

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

object

Audio quality configuration

Show audio properties

string

opus | aac | wav

integer

16 | 24 | 48

integer

8 - 320

object

Power management configuration

Show power properties

integer

Auto-sleep timeout (1-120)

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

Overview

End Users

Devices

Recordings

Uploads

AI Ask

AI Processing

Resources

Update 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

​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