API reference
REST + SSE, fully tenant-isolated
Every PlantHub feature is also a REST endpoint. Build your own dashboard, integrate with a smart-home controller, or just write a quick script — your tenant data is always your own.
OpenAPI (Swagger)
The full machine-readable spec is served at /swagger-ui.html on any PlantHub backend deployment. The hosted instance at https://api.planthub.online/swagger-ui.html always reflects the current production version.
Authentication
PlantHub uses AWS Cognito — an OAuth2 Resource Server with RS256-signed tokens. Log in, get an access token, and pass it as Authorization: Bearer ... on subsequent requests.
Quick example
# Log in
curl -X POST https://api.planthub.online/api/v1/auth/login \
-H 'Content-Type: application/json' \
-d '{"email":"you@example.com","password":"..."}'
# List your nodes
curl https://api.planthub.online/api/v1/nodes \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
# Send a watering command
curl -X POST https://api.planthub.online/api/v1/nodes/node-abc/commands \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"actuator":"waterPump","action":"ON","durationSeconds":15}'Endpoints at a glance
| Group | Method | Path |
|---|---|---|
| Auth | POST | /api/v1/auth/signup |
| Auth | POST | /api/v1/auth/login |
| Auth | POST | /api/v1/auth/refresh |
| Auth | GET | /api/v1/auth/profile |
| Devices | POST | /api/v1/nodes |
| Devices | GET | /api/v1/nodes?page=0&size=20 |
| Devices | GET | /api/v1/nodes/{nodeId} |
| Devices | PATCH | /api/v1/nodes/{nodeId}/ai |
| Devices | DELETE | /api/v1/nodes/{nodeId} |
| Claim | POST | /api/v1/devices/claim |
| Claim | POST | /api/v1/devices/self-register |
| Sensors | GET | /api/v1/nodes/{nodeId}/latest |
| Sensors | GET | /api/v1/nodes/{nodeId}/readings?from=&to=&interval= |
| Actuators | POST | /api/v1/nodes/{nodeId}/commands |
| Rules | POST | /api/v1/rules |
| Rules | GET | /api/v1/rules?page=0&size=20 |
| AI | POST | /api/v1/nodes/{nodeId}/ai/evaluate |
| AI | POST | /api/v1/nodes/{nodeId}/ai/chat |
| AI | GET | /api/v1/nodes/{nodeId}/ai/sessions |
| Alerts | GET | /api/v1/alerts |
| Alerts | POST | /api/v1/alerts/{alertId}/acknowledge |
| Weather | GET | /api/v1/weather/{nodeId} |
| Dashboard | GET | /api/v1/dashboard/summary?groupBy=zone |
| Zones | GET | /api/v1/zones |
Tenant isolation
Every authenticated request resolves a TenantContext from the token. Every database query, every MQTT subscription, every AI tool call is scoped to that tenant — there is no way to read or actuate another user's devices.
Real-time updates
See Alerts & notifications for the SSE channels.