Skip to main content
PUT
/
v1
/
devices
/
{id}
/
settings
Update Device Settings
curl --request PUT \
  --url https://api.example.com/v1/devices/{id}/settings \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "upload": {
    "mode": "<string>",
    "streaming_enabled": true,
    "upload_delay_minutes": 123,
    "daily_data_limit_mb": 123,
    "allow_roaming": true,
    "pause_on_low_battery": true,
    "off_peak_hours": {
      "enabled": true,
      "start": "<string>",
      "end": "<string>",
      "timezone": "<string>"
    }
  },
  "audio": {
    "codec": "<string>",
    "sample_rate_khz": 123,
    "bitrate_kbps": 123
  },
  "power": {
    "auto_sleep_minutes": 123,
    "low_battery_threshold_percent": 123
  }
}
'
{
  "device_id": "dev_abc123xyz",
  "settings": {
    "upload": {
      "mode": "wifi_preferred",
      "streaming_enabled": false,
      "upload_delay_minutes": 5,
      "daily_data_limit_mb": 1000,
      "allow_roaming": false,
      "pause_on_low_battery": true
    },
    "audio": {
      "codec": "opus",
      "sample_rate_khz": 16,
      "bitrate_kbps": 32
    },
    "power": {
      "auto_sleep_minutes": 30,
      "low_battery_threshold_percent": 20
    }
  },
  "updated_at": "2025-01-13T10:35:22Z"
}

​
Overview

Replaces the complete settings configuration for a device. This endpoint performs a full replacement - any settings not included in the request body will be reset to defaults. For partial updates (e.g., only changing upload mode), use PATCH /v1/devices//settings instead.

​
Authentication

Requires a valid API key with devices:write scope. 
curl -X PUT https://api.bota.dev/v1/devices/dev_abc123xyz/settings \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "upload": {
      "mode": "wifi_preferred",
      "streaming_enabled": false,
      "upload_delay_minutes": 5,
      "daily_data_limit_mb": 1000,
      "allow_roaming": false,
      "pause_on_low_battery": true
    },
    "audio": {
      "codec": "opus",
      "sample_rate_khz": 16,
      "bitrate_kbps": 32
    }
  }'

​
Path Parameters

​
id
string
required
Device ID (e.g., dev_abc123xyz)

​
Request Body

​
upload
object
Upload behavior configuration (optional)
​
audio
object
Audio recording configuration (optional)
​
power
object
Power management configuration (optional)

​
Response

Returns the complete updated settings configuration.
​
device_id
string
The device ID
​
settings
object
Complete updated settings (see Get Device Settings for schema)
​
updated_at
string
ISO 8601 timestamp of update
{
  "device_id": "dev_abc123xyz",
  "settings": {
    "upload": {
      "mode": "wifi_preferred",
      "streaming_enabled": false,
      "upload_delay_minutes": 5,
      "daily_data_limit_mb": 1000,
      "allow_roaming": false,
      "pause_on_low_battery": true
    },
    "audio": {
      "codec": "opus",
      "sample_rate_khz": 16,
      "bitrate_kbps": 32
    },
    "power": {
      "auto_sleep_minutes": 30,
      "low_battery_threshold_percent": 20
    }
  },
  "updated_at": "2025-01-13T10:35:22Z"
}

​
Error Responses

{
  "error": {
    "type": "validation_error",
    "message": "Invalid upload settings",
    "details": [
      {
        "field": "upload.daily_data_limit_mb",
        "error": "Must be between 0 and 10000 MB"
      },
      {
        "field": "upload.mode",
        "error": "Invalid mode. Must be one of: ble_only, auto, wifi_preferred, 4g_preferred, wifi_only, 4g_only"
      }
    ]
  }
}

​
Important Notes

Full Replacement: This endpoint replaces ALL settings. Any namespace not included in the request will be reset to defaults. For partial updates, use PATCH instead.
BLE Provisioning: Settings are stored in the backend immediately. If the device is connected via BLE, use the React Native SDK to write settings to the device hardware. Otherwise, settings will be synced on next heartbeat.

​
Use Cases

  • Preset Configurations: Apply pre-defined setting templates (e.g., “Travel Mode”, “Battery Saver”)
  • Factory Reset: Reset all settings to defaults
  • Bulk Configuration: Apply consistent settings across multiple devices