Hierarchical Configuration

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:

Starts with built-in defaults
Merges organization-level overrides
Merges project-level overrides
Merges end user-level overrides (if the device is bound)
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
    }
  }
}

Power-management idle timeouts default to 180 seconds. Use -1 to keep a radio on indefinitely, 0 to power it down immediately after current work completes, or 10-2540 to wait before power-down.

`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_..."

const response = await fetch('https://api.bota.dev/v1/devices/dev_abc123/config', {
  headers: { 'Authorization': 'Bearer sk_live_...' },
});

const config = await response.json();
console.log(config.data.upload.daily_data_limit_mb); // 500 (inherited or overridden)

import requests

response = requests.get(
    'https://api.bota.dev/v1/devices/dev_abc123/config',
    headers={'Authorization': 'Bearer sk_live_...'},
)

config = response.json()
print(config['data']['upload']['daily_data_limit_mb'])

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"
    }
  }'

await fetch('https://api.bota.dev/v1/end-users/eu_abc123/config/processing', {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer sk_live_...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    auto_transcription: {
      enabled: true,
      provider: 'deepgram',
    },
  }),
});

requests.put(
    'https://api.bota.dev/v1/end-users/eu_abc123/config/processing',
    headers={
        'Authorization': 'Bearer sk_live_...',
        'Content-Type': 'application/json',
    },
    json={
        '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)

Method	Endpoint	Description
`GET`	`/v1/devices/:id/config`	Resolve all sections for a device
`GET`	`/v1/devices/:id/config/:section`	Resolve a single section
`PUT`	`/v1/devices/:id/config/:section`	Set a section override
`DELETE`	`/v1/devices/:id/config/:section`	Delete a section override
`GET`	`/v1/end-users/:id/config`	Resolve all sections for an end user
`PUT`	`/v1/end-users/:id/config/:section`	Set a section override
`DELETE`	`/v1/end-users/:id/config/:section`	Delete a section override

Dashboard API (Cognito JWT Auth)

Method	Endpoint	Description
`GET`	`/dashboard/organizations/:orgId/config`	Resolve org config
`PUT`	`/dashboard/organizations/:orgId/config/:section`	Set org override
`DELETE`	`/dashboard/organizations/:orgId/config/:section`	Delete org override
`GET`	`/dashboard/projects/:projectId/config`	Resolve project config
`PUT`	`/dashboard/projects/:projectId/config/:section`	Set project override
`DELETE`	`/dashboard/projects/:projectId/config/:section`	Delete 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

​Overview

​How It Works

​Inheritance Chain

​Merge Strategy

​Config Sections

​connection

​upload

​processing

​API Usage

​Read Resolved Config

​Read a Single Section

​Set a Section Override

​Delete a Section Override

​Scenarios

​Scenario 1: Organization-Wide Policy

​Scenario 2: Per-User Provider Selection

​Scenario 3: Device-Specific Override

​API Endpoints

​Public API (API Key Auth)

​Dashboard API (Cognito JWT Auth)

Auto-Processing Guide

Cellular Upload Guide

Core Concepts

Update Device

Overview

How It Works

Inheritance Chain

Merge Strategy

Config Sections

`connection`

`upload`

`processing`

API Usage

Read Resolved Config

Read a Single Section

Set a Section Override

Delete a Section Override

Scenarios

Scenario 1: Organization-Wide Policy

Scenario 2: Per-User Provider Selection

Scenario 3: Device-Specific Override

API Endpoints

Public API (API Key Auth)

Dashboard API (Cognito JWT Auth)