Skip to main content
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: 
curl http://aris.local/api/zones \
  -H "Authorization: Bearer YOUR_TOKEN"
See Authentication for details on obtaining tokens.

​
Response Format

All responses are JSON. Successful responses include the requested data: 
{
  "zones": [...],
  "metadata": { "count": 4 }
}
Error responses include an error message: 
{
  "error": "Zone not found",
  "zoneId": "invalid_zone"
}

​
Units

The Aris API uses metric (SI) units for all measurements:
MeasurementUnitField SuffixExample
TemperatureCelsius_ctempC: 22.5
PowerKilowatts_kwthermalPowerKw: 12.5
EnergyKilowatt-hours_kwhlifetimeElecKwh: 450.2
FlowLiters per minute_lpmflowRateLpm: 4.2
VolumeLiters_literseffectiveCapacityLiters: 242
PressureBar_barsystemPressureBar: 1.2
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.

​
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.
For API consumers: Handle missing fields gracefully by displaying ”—” or “N/A” in your UI. Do not assume a missing numeric field equals zero.

​
HTTP Status Codes

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

​
Endpoint Groups

Health

System health and readiness checks. No auth required.

System

System-wide state, mode control, and configuration.

Zones

Zone temperatures, setpoints, and control.

Equipment

FCUs, heat pumps, HCU, DHW, and TES status.

Events

Event log, audit trail, and fault history.

Metrics

Time-series data and Prometheus-compatible queries.
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.

​
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 TypeInterval
Zone state5-10 seconds
Equipment telemetry10-30 seconds
Health check30-60 seconds
For more frequent updates, use the WebSocket instead of polling.