# Aivy Developer API

> Read and control your own solar + battery system (Sungrow, Sigenergy, FoxESS, AlphaESS, SolaX, ...) through the Aivy platform by Ivy Energy. Built for a user's own AI agent as much as for scripts.

Base URL: https://bridge.ivyenergy.com.au/v1
Agent playbook (read first): https://bridge.ivyenergy.com.au/v1/agent-guide.md
Auth: `Authorization: Bearer aivy_sk_...` (personal key from the Aivy app, menu → API keys; `read` or `control` scope)
OpenAPI: https://bridge.ivyenergy.com.au/v1/openapi.json
Docs (Swagger UI): https://bridge.ivyenergy.com.au/v1/docs

## Getting a key
- In the app: https://bridge.ivyenergy.com.au/developer (sign up or sign in, create a key)
- From the API: POST /auth/register {identifier, password} → code by email → POST /auth/verify {registration_id, registration_session, code, accept_terms: true, key_name} → returns api_key
- Existing account: POST /keys with HTTP Basic (username:password); keys cannot create keys
- Every key lists demo sites (sandbox:..., read-only) so you can try before connecting hardware

## Start here
- GET /me — check the key
- GET /vendors — supported brands and what connecting one needs
- POST /sites — connect a system (serial + NMI, system id, or an authorize_url for OAuth vendors); DELETE /sites/{id} to remove
- GET /sites — your sites; ids look like `sungrow:1445844`
- GET /sites/{id} — capacity, limits, timezone, mode
- GET /sites/{id}/status — live SOC and power (W; battery_w>0 charging, grid_w>0 exporting)
- GET /sites/{id}/prices — Amber prices now + forecast (c/kWh)
- GET /sites/{id}/energy-mode, PUT — selfConsumption | amber_smart (Ai+) | forced (time-boxed, duration_minutes)
- GET /sites/{id}/ai-plus, PATCH — Ai+ engine variant and levers
- POST /sites/{id}/plans/best-price-discharge — propose a sell schedule, then PUT energy-mode to apply
- GET/POST /sites/{id}/alerts — threshold alerts (soc, prices, forecast temperature) to inbox, push and email; GET .../alerts/events for what fired

## Rules the server enforces
- A key sees only its owner's sites; writes need the control scope.
- forced mode always reverts to the previous mode after duration_minutes (default 240, max 1440).
- SOC floor and export limits cannot be overridden through this API.
- Rate limit per key (default 120/min). Readings refresh about once a minute; do not poll faster.

## Clients
- MCP server for Claude / ChatGPT / Codex / Cursor: `aivy-mcp` (Python) — https://github.com/IVYEnergy/aivy-mcp