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