Skip to main content

​
Overview

Bota’s hierarchical configuration system lets you set default settings at a high level (organization or project) and override them at lower levels (end user or device) as needed. Settings automatically inherit down the chain, so you only need to configure what’s different. Benefits:
  • Set organization-wide defaults once, override per-project or per-device
  • Partial overrides — only specify fields you want to change
  • Deep merge — nested objects merge intelligently, not replace
  • Audit trail — track who changed what and when
Use Cases:
  • Disable cellular uploads organization-wide, but enable for specific field devices
  • Set a conservative daily data limit at the project level, with higher limits for power users
  • Enable auto-transcription for an entire project, but use a different ASR provider for specific devices
  • Apply clinical SOAP templates for healthcare end users, sales templates for others

​
How It Works

​
Inheritance Chain

Settings resolve from the most specific level to the most general: When you request config for a device, the system:
  1. Starts with built-in defaults
  2. Merges organization-level overrides
  3. Merges project-level overrides
  4. Merges end user-level overrides (if the device is bound)
  5. Merges device-level overrides
The result is a fully resolved configuration object.

​
Merge Strategy

The default merge strategy is merge_deep — partial overrides at any level are deep-merged with parent values. You only need to specify the fields you want to change. Example: 
Organization default:
  { "upload": { "daily_data_limit_mb": 500, "allow_roaming": false } }

Project override:
  { "upload": { "daily_data_limit_mb": 1000 } }

Resolved for devices in this project:
  { "upload": { "daily_data_limit_mb": 1000, "allow_roaming": false } }
                 ↑ overridden                   ↑ inherited
Some fields use special merge strategies. For example, daily_data_limit_mb uses min — the strictest (lowest) limit across all levels wins, ensuring child levels can’t exceed parent restrictions.

​
Config Sections

Configuration is organized into sections. Each section has its own schema and defaults.

​
connection

Network connectivity and power management settings. 
{
  "connection": {
    "enabled_connections": {
      "wifi": true,
      "cellular": true
    },
    "upload_network_preference": ["wifi", "ble", "cellular"],
    "power_management": {
      "wifi_idle_timeout_seconds": 180,
      "cellular_idle_timeout_seconds": 180
    }
  }
}

​
upload

Upload behavior, data limits, and scheduling. 
{
  "upload": {
    "streaming_enabled": true,
    "streaming_chunk_kb": 256,
    "daily_data_limit_mb": 500,
    "allow_roaming": false,
    "pause_on_low_battery": true,
    "off_peak_hours": {
      "enabled": false,
      "start": "02:00",
      "end": "06:00",
      "timezone": "UTC"
    }
  }
}

​
processing

Automatic transcription and summarization. See the Auto-Processing Guide for details. 
{
  "processing": {
    "auto_transcription": {
      "enabled": false,
      "provider": "whisper"
    },
    "auto_summary": {
      "enabled": false,
      "provider": "gemini",
      "template": "general_notes"
    }
  }
}

​
API Usage

​
Read Resolved Config

Retrieve the fully resolved configuration for any entity. The response includes all sections with inherited values merged in. 
curl https://api.bota.dev/v1/devices/dev_abc123/config \
  -H "Authorization: Bearer sk_live_..."
Response: 
{
  "data": {
    "connection": {
      "enabled_connections": { "wifi": true, "cellular": true },
      "upload_network_preference": ["wifi", "ble", "cellular"],
      "power_management": {
        "wifi_idle_timeout_seconds": 180,
        "cellular_idle_timeout_seconds": 180
      }
    },
    "upload": {
      "streaming_enabled": true,
      "daily_data_limit_mb": 500,
      "allow_roaming": false,
      "pause_on_low_battery": true
    },
    "processing": {
      "auto_transcription": { "enabled": false },
      "auto_summary": { "enabled": false }
    }
  }
}

​
Read a Single Section

curl https://api.bota.dev/v1/devices/dev_abc123/config/upload \
  -H "Authorization: Bearer sk_live_..."

​
Set a Section Override

Set a partial override at any level. Only the fields you include will be changed — everything else continues to inherit from the parent level. 
# Set project-level processing config
curl -X PUT https://api.bota.dev/v1/end-users/eu_abc123/config/processing \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "auto_transcription": {
      "enabled": true,
      "provider": "deepgram"
    }
  }'

​
Delete a Section Override

Remove an override at a specific level. The entity will revert to inheriting the value from its parent. 
curl -X DELETE https://api.bota.dev/v1/devices/dev_abc123/config/upload \
  -H "Authorization: Bearer sk_live_..."

​
Scenarios

​
Scenario 1: Organization-Wide Policy

Set a conservative data limit for all devices across the organization, with a higher limit for a specific project. 
# Organization default: 200 MB/day
curl -X PUT https://api.bota.dev/v1/organizations/org_xxx/config/upload \
  -H "Authorization: Bearer sk_live_..." \
  -d '{ "daily_data_limit_mb": 200 }'

# Project override: field sales team gets 1000 MB/day
curl -X PUT https://api.bota.dev/v1/projects/proj_sales/config/upload \
  -H "Authorization: Bearer sk_live_..." \
  -d '{ "daily_data_limit_mb": 1000 }'

​
Scenario 2: Per-User Provider Selection

A healthcare project uses Whisper by default, but one clinician prefers Deepgram for better medical terminology support. 
# Project default: auto-transcribe with Whisper
curl -X PUT https://api.bota.dev/v1/projects/proj_clinic/config/processing \
  -H "Authorization: Bearer sk_live_..." \
  -d '{
    "auto_transcription": { "enabled": true, "provider": "whisper" },
    "auto_summary": { "enabled": true, "template": "clinical_soap" }
  }'

# End user override: Dr. Smith uses Deepgram
curl -X PUT https://api.bota.dev/v1/end-users/eu_drsmith/config/processing \
  -H "Authorization: Bearer sk_live_..." \
  -d '{
    "auto_transcription": { "provider": "deepgram" }
  }'
Dr. Smith’s devices will use Deepgram for transcription but still inherit auto_summary settings (enabled, clinical_soap) from the project.

​
Scenario 3: Device-Specific Override

A specific device is used in a noisy environment and needs different upload settings. 
# This device uploads in smaller chunks and avoids streaming
curl -X PUT https://api.bota.dev/v1/devices/dev_noisy/config/upload \
  -H "Authorization: Bearer sk_live_..." \
  -d '{
    "streaming_enabled": false,
    "streaming_chunk_kb": 128
  }'

​
API Endpoints

​
Public API (API Key Auth)

MethodEndpointDescription
GET/v1/devices/:id/configResolve all sections for a device
GET/v1/devices/:id/config/:sectionResolve a single section
PUT/v1/devices/:id/config/:sectionSet a section override
DELETE/v1/devices/:id/config/:sectionDelete a section override
GET/v1/end-users/:id/configResolve all sections for an end user
PUT/v1/end-users/:id/config/:sectionSet a section override
DELETE/v1/end-users/:id/config/:sectionDelete a section override

​
Dashboard API (Cognito JWT Auth)

MethodEndpointDescription
GET/dashboard/organizations/:orgId/configResolve org config
PUT/dashboard/organizations/:orgId/config/:sectionSet org override
DELETE/dashboard/organizations/:orgId/config/:sectionDelete org override
GET/dashboard/projects/:projectId/configResolve project config
PUT/dashboard/projects/:projectId/config/:sectionSet project override
DELETE/dashboard/projects/:projectId/config/:sectionDelete project override
Legacy device settings endpoints (GET/PUT/PATCH /dashboard/projects/:projectId/devices/:deviceId/settings) continue to work and delegate to the hierarchical config system internally.

Auto-Processing Guide

Set up automatic transcription and summarization

Cellular Upload Guide

Configure upload settings for 4G devices

Core Concepts

Understand entities and relationships

Update Device

API reference for device updates