Skip to main content
PATCH
/
v1
/
devices
/
{id}
/
settings
Patch Device Settings
curl --request PATCH \
  --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
  },
  "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_only",           // ✓ Updated
      "streaming_enabled": true,     // ✓ Unchanged
      "upload_delay_minutes": 0,     // ✓ Unchanged
      "daily_data_limit_mb": 1000,   // ✓ Updated
      "allow_roaming": false,        // ✓ Unchanged
      "pause_on_low_battery": true   // ✓ Unchanged
    },
    "audio": {
      "codec": "opus",
      "sample_rate_khz": 16,
      "bitrate_kbps": 32
    },
    "power": {
      "auto_sleep_minutes": 30,
      "low_battery_threshold_percent": 20
    }
  },
  "updated_at": "2025-01-13T11:22:15Z"
}

​
Overview

Updates specific device settings without affecting other configuration. This endpoint performs a partial update (merge) - only the fields included in the request body are modified. Use this endpoint when you only need to change specific settings (e.g., changing upload mode from auto to wifi_only) without affecting other configuration.

​
Authentication

Requires a valid API key with devices:write scope. 
curl -X PATCH https://api.bota.dev/v1/devices/dev_abc123xyz/settings \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "upload": {
      "mode": "wifi_only",
      "daily_data_limit_mb": 1000
    }
  }'

​
Path Parameters

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

​
Request Body

All fields are optional. Only include the specific settings you want to change.
​
upload
object
Upload behavior configuration (partial)
​
audio
object
Audio configuration (partial)
​
power
object
Power management (partial)

​
Response

Returns the complete settings configuration with your changes applied.
​
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_only",           // ✓ Updated
      "streaming_enabled": true,     // ✓ Unchanged
      "upload_delay_minutes": 0,     // ✓ Unchanged
      "daily_data_limit_mb": 1000,   // ✓ Updated
      "allow_roaming": false,        // ✓ Unchanged
      "pause_on_low_battery": true   // ✓ Unchanged
    },
    "audio": {
      "codec": "opus",
      "sample_rate_khz": 16,
      "bitrate_kbps": 32
    },
    "power": {
      "auto_sleep_minutes": 30,
      "low_battery_threshold_percent": 20
    }
  },
  "updated_at": "2025-01-13T11:22:15Z"
}

​
Examples

​
Example 1: Change Upload Mode Only

cURL
curl -X PATCH https://api.bota.dev/v1/devices/dev_abc123xyz/settings \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "upload": {
      "mode": "4g_preferred"
    }
  }'
All other upload settings (streaming, delay, data limit, etc.) remain unchanged.

​
Example 2: Enable Streaming Upload

cURL
curl -X PATCH https://api.bota.dev/v1/devices/dev_abc123xyz/settings \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "upload": {
      "streaming_enabled": true
    }
  }'

​
Example 3: Travel Mode (Disable Roaming)

cURL
curl -X PATCH https://api.bota.dev/v1/devices/dev_abc123xyz/settings \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "upload": {
      "allow_roaming": false,
      "daily_data_limit_mb": 200
    }
  }'

​
Example 4: Update Audio Quality

cURL
curl -X PATCH https://api.bota.dev/v1/devices/dev_abc123xyz/settings \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "audio": {
      "bitrate_kbps": 64
    }
  }'

​
Error Responses

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

​
PUT vs PATCH

When to use PATCH:
  • Changing specific settings (e.g., upload mode)
  • Mobile app settings UI (user toggles individual options)
  • Gradual configuration updates
When to use PUT:
  • Applying preset configurations
  • Factory reset scenarios
  • Bulk device provisioning

​
Important Notes

Merge Behavior: PATCH performs a deep merge. Nested objects are merged, not replaced. For example, updating upload.mode doesn’t affect upload.streaming_enabled.
Validation: All values are still validated even in partial updates. Invalid values will return a 400 error.

​
Use Cases

  • Quick Settings Changes: User toggles “Allow Roaming” in mobile app
  • Data Limit Adjustments: Increase/decrease daily 4G limit without affecting other settings
  • Upload Mode Switching: Change from auto to WiFi-only without reconfiguring everything
  • Gradual Configuration: Apply settings changes incrementally