# Aris API - Instructions for AI Agents

> Aris is an air-to-water heat pump system that heats, cools, and provides hot water for homes. The Aris Brain is the central controller. This file provides instructions for AI agents to interact with the Aris REST API.

## Quick Reference

- **Base URL**: `http://aris.local` (or use the Brain's IP address)
- **Auth**: Bearer token in `Authorization` header
- **Format**: JSON request/response
- **Units**: Metric (Celsius, kW, liters, bar)

## Authentication

Most endpoints require a Bearer token. Create one in the Aris web UI:

1. Open `http://aris.local` in a browser
2. Go to Settings → API Tokens
3. Create a token and copy it (only shown once)

Use the token in requests:

```bash
curl http://aris.local/api/zones \
  -H "Authorization: Bearer YOUR_TOKEN"
```

Health endpoints (`/health`, `/ready`) do not require authentication.

## Core Concepts

- **Zones**: Temperature-controlled areas (bedrooms, living room, etc.)
- **FCUs**: Fan Coil Units - indoor units that deliver heating/cooling to zones
- **HCU**: Hydronic Control Unit - manages water flow between equipment
- **DHW**: Domestic Hot Water tank
- **TES**: Thermal Energy Storage tank (buffer tank)
- **Heat Pumps**: Outdoor units that generate heating/cooling

## Core Operations

### Read Zone Temperatures

```bash
curl http://aris.local/api/zones \
  -H "Authorization: Bearer TOKEN"
```

Returns array of zones with `tempC`, `mode`, `tempHeatSetC`, `tempCoolSetC`.

### Set Temperature

```bash
curl -X POST http://aris.local/api/zones/ZONE_ID/command \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"tempHeatSetC": 21.0}'
```

Valid range: 10-30°C. Minimum 2.2°C gap between heat and cool setpoints enforced automatically.

### Change Zone Mode

```bash
curl -X POST http://aris.local/api/zones/ZONE_ID/command \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mode": "heat"}'
```

Modes: `heat`, `cool`, `auto`, `off`

### Change System Mode

```bash
curl -X POST http://aris.local/api/system/mode \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mode": "auto"}'
```

System mode affects all zones.

### Check System Health

```bash
curl http://aris.local/health
```

No auth required. Returns `status: ok|degraded|unhealthy`.

### Get Equipment Status

```bash
# Heat pump
curl http://aris.local/api/heatpumps -H "Authorization: Bearer TOKEN"

# Hot water tank
curl http://aris.local/api/dhw -H "Authorization: Bearer TOKEN"

# Fan coil units
curl http://aris.local/api/fcus -H "Authorization: Bearer TOKEN"
```

## Endpoint Summary

| Endpoint | Method | Auth | Purpose |
|----------|--------|------|---------|
| `/health` | GET | No | System health check |
| `/ready` | GET | No | Readiness probe |
| `/api/system` | GET | Yes | Get system state |
| `/api/system/mode` | POST | Yes | Set system mode |
| `/api/system/name` | PUT | Yes | Update system name |
| `/api/zones` | GET | Yes | List all zones |
| `/api/zones/:id` | GET | Yes | Get single zone |
| `/api/zones/:id/command` | POST | Yes | Control zone |
| `/api/zones/:id/name` | PUT | Yes | Update zone name |
| `/api/zones/:id/history` | GET | Yes | Zone temperature history |
| `/api/dhw` | GET | Yes | Hot water status |
| `/api/dhw/history` | GET | Yes | DHW temperature history |
| `/api/tes` | GET | Yes | Thermal storage status |
| `/api/hcu` | GET | Yes | Hydronic control unit |
| `/api/heatpumps` | GET | Yes | List heat pumps |
| `/api/heatpumps/:id` | GET | Yes | Single heat pump status |
| `/api/fcus` | GET | Yes | List fan coil units |
| `/api/fcus/:id` | GET | Yes | Single FCU status |
| `/api/fcus/status/all` | GET | Yes | FCU online/offline status |
| `/api/weather` | GET | Yes | Weather forecast |
| `/api/weather/current` | GET | Yes | Current weather |
| `/api/events` | GET | Yes | Query event log |
| `/api/events/:id` | GET | Yes | Get single event |
| `/api/events/stats` | GET | Yes | Event statistics |
| `/api/events/export` | GET | Yes | Export events as CSV |
| `/api/metrics/query` | GET | Yes | Instant PromQL query |
| `/api/metrics/query_range` | GET | Yes | Range PromQL query |
| `/api/tokens` | GET | Yes | List API tokens |
| `/api/tokens` | POST | Yes | Create API token |
| `/api/tokens/:id` | DELETE | Yes | Delete API token |
| `/api/config` | GET | Yes | System configuration |

## Common Patterns

### Nighttime Setback
Lower heating setpoint at night:
```bash
curl -X POST http://aris.local/api/zones/bedroom/command \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"tempHeatSetC": 18.0}'
```

### Away Mode
Turn system off when leaving:
```bash
curl -X POST http://aris.local/api/system/mode \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mode": "off"}'
```

### Check Hot Water
See if hot water is available:
```bash
curl http://aris.local/api/dhw -H "Authorization: Bearer TOKEN"
# Response includes stateOfChargePercent (0-100%)
```

### Monitor Efficiency
Check heat pump COP (Coefficient of Performance):
```bash
curl http://aris.local/api/hcu -H "Authorization: Bearer TOKEN"
# Response includes copInstant when system is running
```

## WebSocket

For real-time updates, connect to:
```
ws://aris.local?token=YOUR_TOKEN
```

Broadcasts zone changes, equipment telemetry, and fault notifications.

## Error Handling

- `401`: Invalid or missing token
- `404`: Resource not found - check zone_id or endpoint path
- `400`: Invalid parameters - check request body
- `503`: Service unavailable - equipment not configured or offline

## Sparse Telemetry

Some fields are omitted when they have no meaningful value. For example, `copInstant` only appears when the system is actively running. Handle missing fields gracefully.

## Tips for Agents

1. **Always check health first** to verify the Brain is reachable
2. **Cache zone IDs** after listing zones - they don't change
3. **Use WebSocket** for real-time updates instead of polling
4. **Temperature setpoints** are clamped to 10-30°C automatically
5. **Mode changes** propagate through the system (zone → HCU → heat pump)
6. **API tokens** never expire - create one for persistent integrations

## Full Documentation

https://docs.ariscomfort.com