### Home Assistant Add-on Installation Steps

Source: https://context7.com/weirded/distributed-esphome/llms.txt

Instructions for installing the ESPHome Fleet add-on from a custom repository within the Home Assistant Add-on Store. A restart of Home Assistant is required after installation to load the companion integration.

```text
1. Settings → Add-ons → Add-on Store → ⋮ → Repositories
   Add: https://github.com/weirded/distributed-esphome

2. Install "ESPHome Fleet" → Start

3. Restart Home Assistant once to load the companion integration.
   HA shows an "ESPHome Fleet discovered" notification — accept it.
```

--------------------------------

### Install Git Hooks

Source: https://github.com/weirded/distributed-esphome/blob/main/dev-plans/RELEASE_CHECKLIST.md

Install the pre-push Git hook script. This hook runs tests and checks before allowing a push to the repository.

```bash
bash scripts/install-hooks.sh
```

--------------------------------

### Start Standalone Docker Compose Stack

Source: https://context7.com/weirded/distributed-esphome/llms.txt

Generates a random server token and starts the ESPHome Fleet server and a local worker using Docker Compose. Ensure the SERVER_TOKEN environment variable is set.

```bash
# Generate a random shared token and start the stack
SERVER_TOKEN=$(openssl rand -hex 32) docker compose up -d

# UI is reachable at http://<host>:8765
# Server logs show: "Running in standalone mode (no HA Supervisor detected)"
```

--------------------------------

### Get Server Info

Source: https://context7.com/weirded/distributed-esphome/llms.txt

Retrieves server metadata, health status, and configuration details. Essential for UI startup to check ESPHome installation status.

```bash
curl http://homeassistant.local:8765/ui/api/server-info \
  -H "Authorization: Bearer <server_token>"
```

```json
{
  "token": "abc123...",
  "port": 8765,
  "server_ip": "192.168.1.10",
  "server_addresses": ["192.168.1.10", "homeassistant"],
  "addon_version": "1.7.0",
  "min_image_version": 7,
  "esphome_install_status": "ready",   # "installing" | "ready" | "failed"
  "esphome_server_version": "2026.4.3",
  "default_worker_disk_quota_bytes": 10737418240
}
```

--------------------------------

### GET /ui/api/targets

Source: https://context7.com/weirded/distributed-esphome/llms.txt

Lists all ESPHome device configurations in the `/config/esphome/` directory, enriched with live device state information.

```APIDOC
## GET /ui/api/targets — List all ESPHome device configs

### Description
Returns every YAML target in `/config/esphome/` enriched with live device state (online status, running firmware, IP, HA entity link, last compile, git diff status, tags, schedule, pin, network facts).

### Method
GET

### Endpoint
/ui/api/targets

### Response
#### Success Response (200)
- Returns an array of device objects, each containing detailed information about an ESPHome configuration.
  - **target** (string) - The name of the YAML configuration file.
  - **friendly_name** (string) - A user-friendly name for the device.
  - **online** (boolean) - Indicates if the device is currently online.
  - **running_version** (string) - The firmware version currently running on the device.
  - **needs_update** (boolean) - Indicates if the device firmware needs an update.
  - **ip_address** (string) - The IP address of the device.
  - **address_source** (string) - The method used to discover the device's IP address.
  - **config_modified** (boolean) - Indicates if the device configuration has been modified.
  - **config_drifted_since_flash** (boolean) - Indicates if the configuration has drifted since the last flash.
  - **last_flashed_config_hash** (string) - The hash of the configuration that was last flashed.
  - **has_uncommitted_changes** (boolean) - Indicates if there are uncommitted changes in the configuration.
  - **pinned_version** (string or null) - The version the device is pinned to, if any.
  - **tags** (array of strings) - Tags associated with the device.
  - **schedule** (string) - The schedule for OTA updates.
  - **schedule_enabled** (boolean) - Indicates if the OTA update schedule is enabled.
  - **network_type** (string) - The network type of the device (e.g., 'wifi').
  - **esp_type** (string) - The type of ESP chip used (e.g., 'esp32').
  - **board** (string) - The development board used.
  - **bluetooth_proxy** (string) - Status of the Bluetooth proxy feature.
  - **ha_configured** (boolean) - Indicates if Home Assistant integration is configured.
  - **ha_connected** (boolean) - Indicates if the device is connected to Home Assistant.
  - **ha_device_id** (string) - The Home Assistant device ID.
  - **mac_address** (string) - The MAC address of the device.
  - **last_compile** (object) - Information about the last compilation.
    - **at** (integer) - Timestamp of the last compilation.
    - **state** (string) - The state of the last compilation ('success').
    - **ota_result** (string) - The result of the last OTA update.
    - **source** (string) - The source of the compilation information.
  - **archived** (boolean) - Indicates if the device configuration is archived.

### Request Example
```bash
curl http://homeassistant.local:8765/ui/api/targets \
  -H "Authorization: Bearer <server_token>"
```

### Response Example
```json
[
  {
    "target": "living-room-light.yaml",
    "friendly_name": "Living Room Light",
    "online": true,
    "running_version": "2026.3.1",
    "needs_update": true,
    "ip_address": "192.168.1.42",
    "address_source": "mdns",
    "config_modified": false,
    "config_drifted_since_flash": true,
    "last_flashed_config_hash": "a1b2c3d",
    "has_uncommitted_changes": false,
    "pinned_version": null,
    "tags": ["living-room", "production"],
    "schedule": "0 3 * * 0",
    "schedule_enabled": true,
    "network_type": "wifi",
    "esp_type": "esp32",
    "board": "esp32dev",
    "bluetooth_proxy": "active",
    "ha_configured": true,
    "ha_connected": true,
    "ha_device_id": "abc123",
    "mac_address": "AA:BB:CC:DD:EE:FF",
    "last_compile": {
      "at": 1714000000,
      "state": "success",
      "ota_result": "success",
      "source": "history"
    },
    "archived": false
  }
]
```
```

--------------------------------

### Start Next Development Cycle

Source: https://github.com/weirded/distributed-esphome/blob/main/dev-plans/RELEASE_CHECKLIST.md

Switch to the develop branch and run a script to bump the development version. This prepares the repository for the next cycle of development.

```bash
git checkout develop && bash scripts/bump-dev.sh
```

--------------------------------

### Create Routing Rule

Source: https://context7.com/weirded/distributed-esphome/llms.txt

Create a new routing rule. This example shows how to ensure ratgdo-tagged devices compile on windows-tagged workers.

```bash
# Create a rule: ratgdo-tagged devices must compile on windows-tagged workers
curl -X POST http://homeassistant.local:8765/ui/api/routing-rules \
  -H "Authorization: Bearer <server_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ratgdo on Windows",
    "device_match": [{"op": "any_of", "tags": ["ratgdo"]}],
    "worker_match": [{"op": "any_of", "tags": ["windows"]}]
  }'
```

--------------------------------

### GET /ui/api/server-info

Source: https://context7.com/weirded/distributed-esphome/llms.txt

Retrieves server metadata and health status, including the server token, port, IP addresses, ESPHome installation status, and minimum worker image version.

```APIDOC
## GET /ui/api/server-info — Server metadata and health

### Description
Returns the server token (for worker snippets), port, reachable IP addresses, ESPHome install status, and min worker image version. Used by the UI on startup to detect whether ESPHome is still installing.

### Method
GET

### Endpoint
/ui/api/server-info

### Response
#### Success Response (200)
- **token** (string) - The server token for worker authentication.
- **port** (integer) - The port the server is listening on.
- **server_ip** (string) - The primary IP address of the server.
- **server_addresses** (array) - A list of reachable IP addresses for the server.
- **addon_version** (string) - The version of the ESPHome addon.
- **min_image_version** (integer) - The minimum required worker image version.
- **esphome_install_status** (string) - The installation status of ESPHome ('installing', 'ready', 'failed').
- **esphome_server_version** (string) - The version of the ESPHome server.
- **default_worker_disk_quota_bytes** (integer) - The default disk quota for workers in bytes.

### Request Example
```bash
curl http://homeassistant.local:8765/ui/api/server-info \
  -H "Authorization: Bearer <server_token>"
```

### Response Example
```json
{
  "token": "abc123...",
  "port": 8765,
  "server_ip": "192.168.1.10",
  "server_addresses": ["192.168.1.10", "homeassistant"],
  "addon_version": "1.7.0",
  "min_image_version": 7,
  "esphome_install_status": "ready",
  "esphome_server_version": "2026.4.3",
  "default_worker_disk_quota_bytes": 10737418240
}
```
```

--------------------------------

### Compile ESPHome Firmware Service Call

Source: https://github.com/weirded/distributed-esphome/blob/main/dev-plans/WORKITEMS-1.7.1.md

Example of triggering the esphome_fleet.compile service on a schedule using Home Assistant Scheduler.

```YAML
alias: Compile ESPHome Firmware

trigger:
  - platform: time_pattern
    hours: "*/6"

condition:
  - condition: state
    entity_id: switch.firmware_update_enabled
    state: "on"

service: esphome_fleet.compile
service_data:
  target_name: my_target
  firmware_variant: my_variant
```

--------------------------------

### YAML Configuration for Device Tags

Source: https://github.com/weirded/distributed-esphome/blob/main/dev-plans/WORKITEMS-future.md

Example of how to define key/value tags for a device within the YAML comment block. These tags are used for organization and filtering.

```yaml
# distributed-esphome:
#   tags:
#     location: kitchen
#     floor: "1"
#     env: prod
#     owner: stefan
```

--------------------------------

### GET /ui/api/jobs/{id}/firmware

Source: https://context7.com/weirded/distributed-esphome/llms.txt

Downloads the compiled firmware binary for a given job ID. Supports different variants (factory, ota) and optional gzip compression.

```APIDOC
## GET /ui/api/jobs/{id}/firmware

### Description
Download a job's firmware binary. Supports `factory` (ESP32 full-flash) and `ota` (smaller OTA-safe) variants, plus optional gzip compression.

### Method
GET

### Endpoint
/ui/api/jobs/{id}/firmware

### Path Parameters
- **id** (string) - Required - The unique identifier of the job.

### Query Parameters
- **variant** (string) - Optional - The firmware variant to download (e.g., 'factory', 'ota'). Defaults to 'ota' if not specified.
- **gz** (integer) - Optional - Set to 1 to enable gzip compression for the download.

### Response
#### Success Response (200)
- **Binary firmware file** (Content-Type will indicate the format, e.g., `application/octet-stream` or `application/gzip`)

### Response Example
(This endpoint returns binary data, not JSON. The examples show `curl` usage for downloading.)
```bash
# Download OTA firmware binary
curl -O -J "http://homeassistant.local:8765/ui/api/jobs/550e8400-.../firmware?variant=ota" \
  -H "Authorization: Bearer <server_token>"
# Saves as: living-room-light-550e8400-ota.bin

# Download factory firmware compressed (~30-40% smaller)
curl -O -J "http://homeassistant.local:8765/ui/api/jobs/550e8400-.../firmware?variant=factory&gz=1" \
  -H "Authorization: Bearer <server_token>"
# Saves as: living-room-light-550e8400-factory.bin.gz
```
```

--------------------------------

### Automate Config-Entry Creation for HAOS Test VM

Source: https://github.com/weirded/distributed-esphome/blob/main/dev-plans/WORKITEMS-1.7.1.md

Adds a step to the HAOS add-on installation script to automate the creation of a config entry for the esphome_fleet integration. This ensures services are registered before Playwright tests run.

```bash
scripts/haos/install-addon.sh
```

--------------------------------

### GET /ui/api/targets/{filename}/rendered-config — View fully rendered YAML

Source: https://context7.com/weirded/distributed-esphome/llms.txt

Returns the YAML as ESPHome will compile it, with substitutions and package flattening applied. The result is cached in-process.

```APIDOC
## GET /ui/api/targets/{filename}/rendered-config

### Description
Retrieve the fully rendered YAML configuration for a device, including substitutions and flattened packages.

### Method
GET

### Endpoint
/ui/api/targets/{filename}/rendered-config

### Parameters
#### Path Parameters
- **filename** (string) - Required - The name of the YAML configuration file.

### Response
#### Success Response (200)
- **cached** (boolean) - Indicates if the response was served from cache.
- **content** (string) - The fully rendered YAML content.
```

--------------------------------

### Download and Print Server SBOM

Source: https://github.com/weirded/distributed-esphome/blob/main/ha-addon/DOCS.md

Download the CycloneDX SBOM for the server image as a cosign attestation and print the predicate using jq. The output is saved to `esphome-dist-server.sbom.json`.

```bash
cosign verify-attestation \
  --certificate-identity-regexp 'https://github.com/weirded/distributed-esphome/.github/workflows/publish-server\.yml@.*' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  --type cyclonedx \
  ghcr.io/weirded/esphome-dist-server:latest \
  | jq -r '.payload | @base64d | fromjson | .predicate' \
  > esphome-dist-server.sbom.json
```

--------------------------------

### Get Worker Log Snapshot

Source: https://github.com/weirded/distributed-esphome/blob/main/dev-plans/designs/2026-04-23-worker-log-visibility.md

Handles GET requests to retrieve a snapshot of the currently buffered logs for a specific worker. Used by the UI for initial log display.

```APIDOC
## GET /ui/api/workers/{client_id}/logs

### Description
Retrieves a snapshot of all log entries currently buffered for a specific worker. This is typically used by the UI to display the initial set of logs when a log view is opened.

### Method
GET

### Endpoint
/ui/api/workers/{client_id}/logs

### Parameters
#### Path Parameters
- **client_id** (string) - Required - The unique identifier of the worker.

### Response
#### Success Response (200)
- **Content-Type**: text/plain; charset=utf-8
- **Body**: Plain text containing the buffered log entries with ANSI color codes preserved.

#### Response Example
```
-- worker restarted --
[2023-04-23 10:00:00] INFO: Worker started.
[2023-04-23 10:01:00] DEBUG: Processing data...
```
```

--------------------------------

### GET /ui/api/jobs/{id}/firmware-variants

Source: https://context7.com/weirded/distributed-esphome/llms.txt

Lists the available firmware variants for a specific job ID.

```APIDOC
## GET /ui/api/jobs/{id}/firmware-variants

### Description
Lists available firmware variants for a job.

### Method
GET

### Endpoint
/ui/api/jobs/{id}/firmware-variants

### Path Parameters
- **id** (string) - Required - The unique identifier of the job.

### Response
#### Success Response (200)
- **Object containing a list of available variants**

### Response Example
```json
{
  "variants": ["factory", "ota"]
}
```
```

--------------------------------

### Build and Typecheck Frontend

Source: https://github.com/weirded/distributed-esphome/blob/main/CONTRIBUTING.md

Build the frontend application and perform type checking. This command should be run from the `ha-addon/ui` directory.

```bash
cd ha-addon/ui && npm run build
```

--------------------------------

### Worker Offline to Dashboard Warning

Source: https://github.com/weirded/distributed-esphome/blob/main/dev-plans/WORKITEMS-1.7.1.md

Example of routing a worker-offline binary-sensor transition to a dashboard warning card.

```YAML
type: custom:mushroom-template-card
icon: mdi:alert-circle
entity: binary_sensor.worker_status
primary_info: "{{ entity.name }}"
secondary_info: "{{ 'Offline' if is_state(entity.entity_id, 'off') else 'Online' }}"
layout: vertical
card_mod:
  style: | 
    ha-card {
      {% if is_state(entity.entity_id, 'off') %}
        --card-background-color: var(--warning-color);
      {% endif %}
    }
```

--------------------------------

### List ESPHome Device Configs

Source: https://context7.com/weirded/distributed-esphome/llms.txt

Fetches a list of all ESPHome device configurations from the `/config/esphome/` directory, including their live status and firmware details. Useful for displaying device inventory and health.

```bash
curl http://homeassistant.local:8765/ui/api/targets \
  -H "Authorization: Bearer <server_token>"
```

```json
[
  {
    "target": "living-room-light.yaml",
    "friendly_name": "Living Room Light",
    "online": true,
    "running_version": "2026.3.1",
    "needs_update": true,
    "ip_address": "192.168.1.42",
    "address_source": "mdns",
    "config_modified": false,
    "config_drifted_since_flash": true,
    "last_flashed_config_hash": "a1b2c3d",
    "has_uncommitted_changes": false,
    "pinned_version": null,
    "tags": ["living-room", "production"],
    "schedule": "0 3 * * 0",
    "schedule_enabled": true,
    "network_type": "wifi",
    "esp_type": "esp32",
    "board": "esp32dev",
    "bluetooth_proxy": "active",
    "ha_configured": true,
    "ha_connected": true,
    "ha_device_id": "abc123",
    "mac_address": "AA:BB:CC:DD:EE:FF",
    "last_compile": {
      "at": 1714000000,
      "state": "success",
      "ota_result": "success",
      "source": "history"
    },
    "archived": false
  }
]
```

--------------------------------

### Create a new device

Source: https://context7.com/weirded/distributed-esphome/llms.txt

Creates a new `.yaml` stub (or duplicate) staged as a dotfile invisible to the scanner until first save.

```APIDOC
## POST /ui/api/targets — Create a new device

### Description
Creates a new `.yaml` stub (or duplicate) staged as a dotfile invisible to the scanner until first save.

### Method
POST

### Endpoint
/ui/api/targets

### Parameters
#### Request Body
- **filename** (string) - Required - The desired filename for the new device configuration.
- **source** (string) - Optional - The filename of an existing device to duplicate.

### Request Example
```bash
# Create a new device from a stub
curl -X POST http://homeassistant.local:8765/ui/api/targets \
  -H "Authorization: Bearer <server_token>" \
  -H "Content-Type: application/json" \
  -d '{"filename": "office-sensor"}'

# Duplicate an existing device
curl -X POST http://homeassistant.local:8765/ui/api/targets \
  -H "Authorization: Bearer <server_token>" \
  -H "Content-Type: application/json" \
  -d '{"filename": "office-sensor-2", "source": "office-sensor.yaml"}'
```

### Response
#### Success Response (200)
- **target** (string) - The name of the staged target file (e.g., `.pending.office-sensor.yaml`).
- **ok** (boolean) - Indicates if the operation was successful.

#### Response Example
```json
{"target": ".pending.office-sensor.yaml", "ok": true}
```
```

--------------------------------

### Worker Offline Notification

Source: https://github.com/weirded/distributed-esphome/blob/main/dev-plans/WORKITEMS-1.7.1.md

Example of creating a notification when a worker's binary sensor reports an offline status.

```YAML
alias: Notify on Worker Offline

trigger:
  - platform: state
    entity_id: binary_sensor.worker_status
    to: "off"

condition:
  - condition: state
    entity_id: binary_sensor.worker_status
    for: "00:01:00"

action:
  - service: notify.persistent_notification
    data:
      title: "Worker Offline"
      message: "Worker {{ trigger.entity_id }} has gone offline."
```

--------------------------------

### GET /ui/api/workers

Source: https://context7.com/weirded/distributed-esphome/llms.txt

Retrieves a list of all connected build workers, including their status, capacity, resource usage, and current tasks.

```APIDOC
## GET /ui/api/workers

### Description
Returns all registered workers (local and remote) with online status, slot count, disk usage, tags, and current job.

### Method
GET

### Endpoint
/ui/api/workers

### Response
#### Success Response (200)
- **Array of worker objects** (Details of the worker object structure are not provided in the source.)

### Response Example
(The source does not provide a specific JSON example for the worker object structure, but implies a list of worker details.)
```json
[
  {
    "id": "worker-uuid",
    "hostname": "my-fast-pc",
    "online": true,
    "slots": 4,
    "disk_usage_gb": 50.5,
    "tags": ["esp32", "high-performance"],
    "current_job_id": "550e8400-..."
  }
]
```
```

--------------------------------

### Deploy to Local Home Assistant Test Instance

Source: https://github.com/weirded/distributed-esphome/blob/main/CONTRIBUTING.md

Optional script for external contributors; maintainers use it to deploy to a local Home Assistant test instance and run the `e2e-hass-4` Playwright smoke suite.

```bash
./push-to-hass-4.sh
```

--------------------------------

### Get File Diff

Source: https://context7.com/weirded/distributed-esphome/llms.txt

Returns a unified diff, showing changes between two git commits or between the working tree and the HEAD commit.

```APIDOC
## GET /ui/api/files/{filename}/diff — Unified diff between commits

Returns a unified diff between two commits (or the working tree vs HEAD when no hashes are given).

### Method
GET

### Endpoint
/ui/api/files/{filename}/diff

### Parameters
#### Path Parameters
- **filename** (string) - Required - The name of the file to diff.

#### Query Parameters
- **from** (string) - Optional - The starting git commit hash.
- **to** (string) - Optional - The ending git commit hash.

### Request Example
```bash
# Diff working tree vs HEAD
curl "http://homeassistant.local:8765/ui/api/files/living-room-light.yaml/diff" \
  -H "Authorization: Bearer <server_token>"

# Diff between two specific commits
curl "http://homeassistant.local:8765/ui/api/files/living-room-light.yaml/diff?from=a1b2c3d&to=f9e8d7c" \
  -H "Authorization: Bearer <server_token>"
```

### Response
#### Success Response (200)
- **diff** (string) - The unified diff output.

### Response Example
```json
{"diff": "--- a/living-room-light.yaml\n+++ b/living-room-light.yaml\n@@ -5,3 +5,3 @@\n ..."}
```
```

--------------------------------

### Run Test Matrix Script

Source: https://github.com/weirded/distributed-esphome/blob/main/AGENTS.md

Execute the main test matrix script with web UI enabled. Always pass `--web` and ensure the dashboard is accessible in the browser for live monitoring.

```bash
python scripts/test-matrix.py --web
```

--------------------------------

### Update Routing Rule

Source: https://context7.com/weirded/distributed-esphome/llms.txt

Update an existing routing rule. This example modifies the worker match to require both 'windows' and 'production' tags.

```bash
# Update an existing rule
curl -X PUT http://homeassistant.local:8765/ui/api/routing-rules/ratgdo-on-windows \
  -H "Authorization: Bearer <server_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ratgdo on Windows",
    "device_match": [{"op": "any_of", "tags": ["ratgdo"]}],
    "worker_match": [{"op": "all_of", "tags": ["windows", "production"]}]
  }'
```

--------------------------------

### Download Compiled Firmware Binary

Source: https://context7.com/weirded/distributed-esphome/llms.txt

Download the compiled firmware binary for a job. Specify the variant (`factory` or `ota`) and optionally enable gzip compression. The filename is automatically determined.

```bash
# Download OTA firmware binary
curl -O -J "http://homeassistant.local:8765/ui/api/jobs/550e8400-.../firmware?variant=ota" \
  -H "Authorization: Bearer <server_token>"
```

```bash
# Download factory firmware compressed (~30-40% smaller)
curl -O -J "http://homeassistant.local:8765/ui/api/jobs/550e8400-.../firmware?variant=factory&gz=1" \
  -H "Authorization: Bearer <server_token>"
```

```bash
# List available variants for a job
curl "http://homeassistant.local:8765/ui/api/jobs/550e8400-.../firmware-variants" \
  -H "Authorization: Bearer <server_token>"
```

--------------------------------

### Validate Device Config

Source: https://context7.com/weirded/distributed-esphome/llms.txt

Validate a device configuration by running `esphome config` on the server. This respects per-device version pins and returns immediate output.

```bash
curl -X POST http://homeassistant.local:8765/ui/api/validate \
  -H "Authorization: Bearer <server_token>" \
  -H "Content-Type: application/json" \
  -d '{"target": "living-room-light.yaml"}'
```

--------------------------------

### Deploy to hass-4

Source: https://github.com/weirded/distributed-esphome/blob/main/AGENTS.md

Fast-path script for single-target deployment to hass-4. Use `--from-ghcr` to pull pre-built images instead of rebuilding.

```bash
./push-to-hass-4.sh --from-ghcr
```

--------------------------------

### Get File History

Source: https://context7.com/weirded/distributed-esphome/llms.txt

Retrieve paginated git commit history for a configuration file. Each entry may include firmware availability information.

```bash
curl "http://homeassistant.local:8765/ui/api/files/living-room-light.yaml/history?limit=20&offset=0" \
  -H "Authorization: Bearer <server_token>"
```

--------------------------------

### GET /ui/api/history/stats

Source: https://context7.com/weirded/distributed-esphome/llms.txt

Provides aggregate statistics for compile history, including totals, success/failure counts, and average/p95 durations over a configurable rolling window.

```APIDOC
## GET /ui/api/history/stats

### Description
Returns aggregate stats (totals, success/failure counts, average and p95 duration) for a device or the whole fleet over a configurable rolling window.

### Method
GET

### Endpoint
/ui/api/history/stats

### Query Parameters
- **target** (string) - Optional - Filter stats for a specific device target.
- **window_days** (integer) - Required - The number of past days to include in the statistics calculation.

### Response
#### Success Response (200)
- **Object containing aggregate statistics**

### Response Example
```json
{
  "total": 42,
  "success": 38,
  "failed": 3,
  "cancelled": 1,
  "timed_out": 0,
  "avg_duration_seconds": 87.4,
  "p95_duration_seconds": 210.0,
  "last_success_at": "2026-04-23T10:00:00",
  "last_failure_at": "2026-04-21T08:00:00",
  "window_days": 7
}
```
```

--------------------------------

### Unpinned Dependencies in requirements.txt

Source: https://github.com/weirded/distributed-esphome/blob/main/dev-plans/SECURITY_AUDIT.md

This snippet shows minimum version constraints in requirements.txt. Using only '>=' allows the build process to pull the latest compatible versions, increasing exposure to supply-chain attacks. Pinning to exact versions with hashes is recommended.

```text
aiohttp>=3.9
aioesphomeapi>=18.0
zeroconf>=0.131
pyyaml>=6.0
esphome>=2024.1.0
requests>=2.31
```

```text
requests>=2.31
```

--------------------------------

### Get Latest ESPHome Version

Source: https://github.com/weirded/distributed-esphome/blob/main/dev-plans/RELEASE_CHECKLIST.md

Fetches the latest stable version of the ESPHome package from PyPI. Used to update pinned versions in the project.

```bash
curl -s https://pypi.org/pypi/esphome/json | jq -r '.info.version'
```

--------------------------------

### POST /ui/api/validate — Validate a device config

Source: https://context7.com/weirded/distributed-esphome/llms.txt

Runs `esphome config` directly on the server (not via a worker) and returns the output immediately. Respects per-device version pins.

```APIDOC
## POST /ui/api/validate

### Description
Validate a device configuration file on the server.

### Method
POST

### Endpoint
/ui/api/validate

### Parameters
#### Request Body
- **target** (string) - Required - The filename of the device configuration to validate.

### Request Example
```json
{
  "target": "living-room-light.yaml"
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the configuration is valid.
- **output** (string) - The output from the `esphome config` command.
```

--------------------------------

### Get File History

Source: https://context7.com/weirded/distributed-esphome/llms.txt

Retrieves paginated git commit history for a specified configuration file. Each entry may include firmware availability information.

```APIDOC
## GET /ui/api/files/{filename}/history — Per-file git history

Returns paginated git commit history for a config file, newest first. Each entry optionally includes firmware availability info when a stored binary matches that commit's config hash.

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Maximum number of commits to return.
- **offset** (integer) - Optional - Number of commits to skip.

### Request Example
```bash
curl "http://homeassistant.local:8765/ui/api/files/living-room-light.yaml/history?limit=20&offset=0" \
  -H "Authorization: Bearer <server_token>"
```

### Response
#### Success Response (200)
- **hash** (string) - The full git commit hash.
- **short_hash** (string) - The short git commit hash.
- **date** (string) - The date and time of the commit (ISO 8601 format).
- **author_name** (string) - The name of the commit author.
- **message** (string) - The commit message.
- **lines_added** (integer) - The number of lines added in this commit.
- **lines_removed** (integer) - The number of lines removed in this commit.
- **firmware_job_id** (string) - The ID of the firmware job associated with this commit, if any.
- **firmware_variants** (array of strings) - List of firmware variants available for this commit.

### Response Example
```json
[
  {
    "hash": "a1b2c3d4e5f6...",
    "short_hash": "a1b2c3d",
    "date": "2026-04-23T10:00:00+00:00",
    "author_name": "ESPHome Fleet",
    "message": "Automatically saved after editing in UI",
    "lines_added": 3,
    "lines_removed": 1,
    "firmware_job_id": "550e8400-...",
    "firmware_variants": ["factory", "ota"]
  }
]
```
```