> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bota.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Hierarchical Configuration

> Configure device settings at organization, project, end user, or device level with automatic inheritance and merge.

## 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:

```mermaid theme={null}
flowchart TD
    A["Organization"] --> B["Project"]
    B --> C["End User"]
    C --> D["Device"]
```

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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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](/guides/auto-processing) for details.

```json theme={null}
{
  "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.

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.bota.dev/v1/devices/dev_abc123/config \
    -H "Authorization: Bearer sk_live_..."
  ```

  ```javascript Node.js theme={null}
  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)
  ```

  ```python Python theme={null}
  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'])
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "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

```bash theme={null}
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.

<CodeGroup>
  ```bash cURL theme={null}
  # 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"
      }
    }'
  ```

  ```javascript Node.js theme={null}
  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',
      },
    }),
  });
  ```

  ```python Python theme={null}
  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',
          },
      },
  )
  ```
</CodeGroup>

### Delete a Section Override

Remove an override at a specific level. The entity will revert to inheriting the value from its parent.

```bash theme={null}
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.

```bash theme={null}
# 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.

```bash theme={null}
# 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.

```bash theme={null}
# 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 |

<Info>
  Legacy device settings endpoints (`GET/PUT/PATCH /dashboard/projects/:projectId/devices/:deviceId/settings`) continue to work and delegate to the hierarchical config system internally.
</Info>

***

<CardGroup cols={2}>
  <Card title="Auto-Processing Guide" icon="wand-magic-sparkles" href="/guides/auto-processing">
    Set up automatic transcription and summarization
  </Card>

  <Card title="Cellular Upload Guide" icon="tower-cell" href="/guides/cellular-upload">
    Configure upload settings for 4G devices
  </Card>

  <Card title="Core Concepts" icon="sitemap" href="/concepts">
    Understand entities and relationships
  </Card>

  <Card title="Update Device" icon="gear" href="/api-reference/devices/update">
    API reference for device updates
  </Card>
</CardGroup>