---
title: SolarWine API
emoji: 🌿
colorFrom: green
colorTo: yellow
sdk: docker
app_port: 7860
private: true
---

# SolarWine API

FastAPI backend for the SolarWine agrivoltaic vineyard control system.

## Endpoints

### Health & Monitoring
- `GET|HEAD /api/health` — system health (uptime, Redis, TB, IMS, Gemini status)
- `GET /api/health/data` — data freshness per source (age, ok/degraded)
- `GET /api/health/data-sources` — per-source green/yellow/red status with thresholds

### Weather (IMS Station 43)
- `GET /api/weather/current` — latest weather readings + data age
- `GET /api/weather/history?start_date&end_date&format` — historical weather (hourly)
- `GET /api/weather/forecast` — weather forecast

### Vine Sensors (ThingsBoard)
- `GET /api/sensors/snapshot` — latest readings (treatment vs reference)
- `GET /api/sensors/history?type&area&hours` — sensor time-series
- `GET /api/sensors/soil-moisture?hours` — soil moisture history
- `GET /api/sensors/rain?hours` — rainfall history

### Energy
- `GET /api/energy/current` — current power output (kW)
- `GET /api/energy/daily/{date}` — daily production + hourly profile
- `GET /api/energy/history` — energy generation time-series
- `GET /api/energy/predict/{date}` — predicted daily generation

### Photosynthesis
- `GET /api/photosynthesis/current?model` — current A rate (FvCB or ML)
- `GET /api/photosynthesis/forecast` — 24h predicted A profile

### Control System
- `GET /api/control/status` — last control loop tick
- `GET /api/control/plan` — current day-ahead plan
- `GET /api/control/budget` — energy budget status
- `GET /api/control/trackers` — tracker angles and modes

### Chatbot (Gemini AI)
- `POST /api/chatbot/message` — send message to vineyard advisor
- `POST /api/chatbot/feedback` — submit feedback on response
- `GET /api/chatbot/briefing` — current system status briefing

### Biology
- `GET /api/biology/phenology` — current growth stage
- `GET /api/biology/rules` — all biology rules
- `GET /api/biology/rules/{name}` — single rule detail
- `GET /api/biology/chill-units?season_start` — accumulated chill units

### Auth
- `POST /api/auth/login` — JWT token (guest mode when JWT_SECRET unset)

### Events
- `GET /api/events/stream` — SSE stream for live frontend updates

Interactive docs at `/docs`.

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `IMS_API_TOKEN` | Yes | IMS weather API token |
| `THINGSBOARD_HOST` | Yes | ThingsBoard server URL |
| `THINGSBOARD_USERNAME` | Yes | ThingsBoard login |
| `THINGSBOARD_PASSWORD` | Yes | ThingsBoard password |
| `GOOGLE_API_KEY` | No | Gemini AI for chatbot/advisor |
| `JWT_SECRET` | No | JWT signing key (guest mode if unset) |
| `ADMIN_PASSWORD` | No | Login password |
| `REDIS_URL` | No | Upstash Redis for shared cache |
| `SENTRY_DSN` | No | Sentry error tracking |
| `SMTP_HOST` | No | Email alerts (with ALERT_EMAIL_TO) |
| `ALERT_EMAIL_TO` | No | Alert recipient email(s) |