Skip to main content
Zones are the primary way to control comfort in your home. Each zone represents a distinct area with its own temperature sensor and setpoints.

​
Understanding Zones

A zone can have:
  • One or more temperature sensors (thermostats, FCU sensors)
  • One or more terminal devices (FCUs, radiant emitters)
  • Independent heating and cooling setpoints
  • Its own operating mode

​
Listing Zones

Get all zones with their current state: 
curl http://aris.local/api/zones \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "zones": [
    {
      "zoneId": "primary_bedroom",
      "friendlyName": "Primary Bedroom",
      "tempC": 22.4,
      "rhPercent": 45,
      "mode": "auto",
      "tempHeatSetC": 21.0,
      "tempCoolSetC": 24.0,
      "activeCall": "none",
      "supportsHeat": true,
      "supportsCool": true
    }
  ]
}

​
Zone Properties

PropertyDescription
zoneIdUnique identifier (from system config)
friendlyNameDisplay name
tempCCurrent temperature in Celsius
rhPercentRelative humidity percentage
modeOperating mode (heat/cool/auto/off)
tempHeatSetCHeating setpoint
tempCoolSetCCooling setpoint
activeCallCurrent demand (heat/cool/none)
supportsHeatWhether zone can heat
supportsCoolWhether zone can cool

​
Setting Temperature

Adjust the heating setpoint: 
curl -X POST http://aris.local/api/zones/primary_bedroom/command \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"tempHeatSetC": 22.0}'
Adjust the cooling setpoint: 
curl -X POST http://aris.local/api/zones/primary_bedroom/command \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"tempCoolSetC": 25.0}'
Set both at once: 
curl -X POST http://aris.local/api/zones/primary_bedroom/command \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tempHeatSetC": 21.0,
    "tempCoolSetC": 24.0
  }'

​
Setpoint Constraints

Valid range: 10-30°C (50-86°F)Minimum gap: 2.2°C (4°F) between heat and cool setpointsIf you set setpoints that violate the gap, the system automatically adjusts the other setpoint to maintain the minimum gap.

​
Changing Zone Mode

Each zone can operate in one of four modes:
ModeBehavior
heatOnly heating is active
coolOnly cooling is active
autoSystem automatically switches between heating and cooling
offZone is disabled (no heating or cooling)
Set a zone’s mode: 
curl -X POST http://aris.local/api/zones/primary_bedroom/command \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mode": "heat"}'

​
Mode Propagation

Mode behavior depends on your system’s thermal energy storage (TES) topology:
ModeBehavior
offAlways zone-specific. Only disables the targeted zone.
heat, cool, autoMay propagate to other zones depending on TES configuration.
Why modes propagate: Zones sharing the same TES tank must operate in the same thermal mode because the tank can only store hot or cold water at a time, not both.
  • Single-TES systems: The heat, cool, and auto modes are effectively system-wide since all zones share one thermal source. Setting any zone to heat means the entire system operates in heating mode.
  • Multi-TES systems: Zones served by different TES tanks may operate independently. For example, upstairs zones on TES-1 could be in cooling mode while basement zones on TES-2 heat.
The API accepts mode changes on any zone. If the mode would affect other zones due to TES topology, the system applies it consistently across all affected zones.

​
Combined Commands

Set mode and temperature in one request: 
curl -X POST http://aris.local/api/zones/primary_bedroom/command \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "heat",
    "tempHeatSetC": 22.0
  }'

​
Renaming Zones

Update a zone’s friendly name: 
curl -X PATCH http://aris.local/api/zones/primary_bedroom/name \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Master Suite"}'
Names must be 1-50 characters.

​
Viewing History

Get historical temperature data for a zone: 
# Last 24 hours (default)
curl "http://aris.local/api/zones/primary_bedroom/history" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Last 7 days
curl "http://aris.local/api/zones/primary_bedroom/history?hours=168" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Specific time range
curl "http://aris.local/api/zones/primary_bedroom/history?start=2024-01-01T00:00:00Z&end=2024-01-02T00:00:00Z" \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "zoneId": "primary_bedroom",
  "start": "2024-01-14T10:30:00Z",
  "end": "2024-01-15T10:30:00Z",
  "points": [
    {
      "timestamp": "2024-01-14T10:30:00Z",
      "tempC": 21.5,
      "tempHeatSetC": 21.0,
      "tempCoolSetC": 24.0
    }
  ],
  "count": 288
}

​
Python Example

A complete example for monitoring and controlling zones: 
import requests
import time

BRAIN_URL = "http://aris.local"
TOKEN = "your-api-token"

def get_headers():
    return {"Authorization": f"Bearer {TOKEN}"}

def get_zones():
    """Get all zone states"""
    response = requests.get(f"{BRAIN_URL}/api/zones", headers=get_headers())
    return response.json()["zones"]

def set_temperature(zone_id: str, heat: float = None, cool: float = None):
    """Set zone temperature setpoints"""
    payload = {}
    if heat is not None:
        payload["tempHeatSetC"] = heat
    if cool is not None:
        payload["tempCoolSetC"] = cool

    response = requests.post(
        f"{BRAIN_URL}/api/zones/{zone_id}/command",
        headers=get_headers(),
        json=payload
    )
    return response.json()

def set_mode(zone_id: str, mode: str):
    """Set zone mode (heat/cool/auto/off)"""
    response = requests.post(
        f"{BRAIN_URL}/api/zones/{zone_id}/command",
        headers=get_headers(),
        json={"mode": mode}
    )
    return response.json()

# Example: Turn off bedroom at night, warm up in morning
if __name__ == "__main__":
    zones = get_zones()
    for zone in zones:
        print(f"{zone['friendlyName']}: {zone['tempC']}°C (target: {zone['tempHeatSetC']}°C)")

    # Nighttime setback
    set_temperature("primary_bedroom", heat=18.0)
    print("Bedroom set to 18°C for night")

    # Morning warmup (run this at 6am via cron)
    # set_temperature("primary_bedroom", heat=21.0)

​
Common Patterns

Lower heating setpoints at night to save energy:
for zone in get_zones():
    set_temperature(zone["zoneId"], heat=18.0)
When leaving home, set a wider deadband:
for zone in get_zones():
    set_temperature(zone["zoneId"], heat=16.0, cool=28.0)
Warm up guest rooms before arrival:
set_temperature("guest_room", heat=22.0)
set_mode("guest_room", "heat")