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

# API Overview

> Aris Brain REST API reference

The Aris Brain exposes a REST API for controlling and monitoring your HVAC system.

## Base URL

The API runs on your local network:

```
http://aris.local
```

Or use your Brain's IP address:

```
http://192.168.1.100
```

## Authentication

Most endpoints require a Bearer token in the `Authorization` header:

```bash theme={null}
curl http://aris.local/api/zones \
  -H "Authorization: Bearer YOUR_TOKEN"
```

See [Authentication](/authentication) for details on obtaining tokens.

## Response Format

All responses are JSON. Successful responses include the requested data:

```json theme={null}
{
  "zones": [...],
  "metadata": { "count": 4 }
}
```

Error responses include an error message:

```json theme={null}
{
  "error": "Zone not found",
  "zoneId": "invalid_zone"
}
```

## Units

The Aris API uses **metric (SI) units** for all measurements:

| Measurement | Unit              | Field Suffix | Example                        |
| ----------- | ----------------- | ------------ | ------------------------------ |
| Temperature | Celsius           | `_c`         | `tempC: 22.5`                  |
| Power       | Kilowatts         | `_kw`        | `thermalPowerKw: 12.5`         |
| Energy      | Kilowatt-hours    | `_kwh`       | `lifetimeElecKwh: 450.2`       |
| Flow        | Liters per minute | `_lpm`       | `flowRateLpm: 4.2`             |
| Volume      | Liters            | `_liters`    | `effectiveCapacityLiters: 242` |
| Pressure    | Bar               | `_bar`       | `systemPressureBar: 1.2`       |

<Note>
  **Why metric?** Metric units are the international standard for HVAC engineering and provide consistent precision across calculations. The Aris web UI displays temperatures in your preferred unit (°F or °C), but the API always uses Celsius for consistency.

  **Quick conversion:** °F = (°C × 9/5) + 32. So 22°C = 71.6°F.
</Note>

### Numeric Precision

Values are rounded to reflect actual sensor accuracy and avoid false precision:

* **Temperature, power, energy, flow, pressure:** 1 decimal place (e.g., `22.4`, `12.5`)
* **Percentages:** integers (e.g., `65`, not `65.4`)

### Sparse Telemetry

Some derived metrics are **omitted entirely** when they have no meaningful value, rather than being set to `0` or `null`. This prevents statistics and averages from being polluted by meaningless data.

**Example:** `copInstant` (instantaneous Coefficient of Performance) is only present when the system is actively running. When the system is idle, there's no meaningful COP to report—including a `0` would incorrectly suggest the system is running inefficiently.

<Note>
  **For API consumers:** Handle missing fields gracefully by displaying "—" or "N/A" in your UI. Do not assume a missing numeric field equals zero.
</Note>

## HTTP Status Codes

| Code | Meaning                                                  |
| ---- | -------------------------------------------------------- |
| 200  | Success                                                  |
| 201  | Created (for POST creating new resources)                |
| 400  | Bad Request (invalid parameters)                         |
| 401  | Unauthorized (missing or invalid token)                  |
| 404  | Not Found                                                |
| 500  | Internal Server Error                                    |
| 503  | Service Unavailable (service not configured or starting) |

## Endpoint Groups

<CardGroup cols={2}>
  <Card title="Health" icon="heart-pulse">
    System health and readiness checks. No auth required.
  </Card>

  <Card title="System" icon="sliders">
    System-wide state, mode control, and configuration.
  </Card>

  <Card title="Zones" icon="temperature-half">
    Zone temperatures, setpoints, and control.
  </Card>

  <Card title="Equipment" icon="fan">
    FCUs, heat pumps, HCU, DHW, and TES status.
  </Card>

  <Card title="Events" icon="list">
    Event log, audit trail, and fault history.
  </Card>

  <Card title="Metrics" icon="chart-line">
    Time-series data and Prometheus-compatible queries.
  </Card>
</CardGroup>

<Info>
  **What's not in the API?** Some system components are managed internally and don't have dedicated API endpoints:

  * **Circuits & branches** — Configured during installation, not user-adjustable
  * **Individual sensors** — Raw readings are aggregated into zone and equipment data
  * **Thermostats** — Readings flow into zone temperature and setpoint data
  * **Hydronic emitters** — Part of the physical distribution system, controlled via zones

  The API focuses on the objects you actually need to monitor and control: zones, equipment, and system state.
</Info>

## Real-Time Updates

For real-time data, connect to the WebSocket at `ws://aris.local`. Include your API token as a query parameter:

```
ws://aris.local?token=YOUR_API_TOKEN
```

The WebSocket broadcasts:

* Zone state changes
* Equipment telemetry
* System events
* Fault notifications

## Rate Limits

The local API has no rate limits. However, making too many requests may impact system performance. Recommended polling intervals:

| Data Type           | Interval      |
| ------------------- | ------------- |
| Zone state          | 5-10 seconds  |
| Equipment telemetry | 10-30 seconds |
| Health check        | 30-60 seconds |

For more frequent updates, use the WebSocket instead of polling.