API Contract
Laravel exposes these routes to the browser. The controller proxies them to Python EMS using the Docker service name ems-backend.
Route table
| Laravel route | Backend route | Method | Purpose |
|---|---|---|---|
/api/ems/health |
/api/v1/ems/health |
GET | Service health |
/api/ems/settings |
/api/v1/ems/settings |
GET | Read current EMS settings |
/api/ems/settings |
/api/v1/ems/settings |
PUT | Replace complete EMS settings |
/api/ems/settings |
/api/v1/ems/settings |
POST | Replace complete EMS settings |
/api/ems/readings |
/api/v1/ems/readings |
GET | Read all current last values |
/api/ems/readings/{device} |
/api/v1/ems/readings/{device} |
GET | Read one device snapshot |
Authentication
The browser authenticates with Laravel using the application's normal authentication. Laravel authenticates with Python using:
Authorization: Bearer ${EMS_BACKEND_TOKEN}
Never put EMS_BACKEND_TOKEN in frontend JavaScript or return it in an API response.
Settings update
The request must contain the complete JSON document, including all sections that must remain unchanged.
PUT /api/ems/settings
Content-Type: application/json
Accept: application/json
{
"ems_operation_mode": "MANUAL",
"ems_control_mode": "local_control",
"functions": {
"Manual_Operation": {
"enabled": true,
"operation_type": "CHARGE",
"power_setpoint_kw": 60
}
},
"general_settings": {
"pcs": {}
}
}
A successful response returns the complete object saved by Python EMS.
Readings response
{
"timestamp": 1769374275562,
"source": "ems-backend",
"devices": {
"pcs1_lastValue": {
"timestamp": 1769374275562,
"pcs_soc_state_of_charge_item": 55.2
},
"gridMeter_lastValue": {
"timestamp": 1769374275562,
"gridMeter_active_power_total_kw": 1.02
}
}
}
A device-specific response is:
{
"timestamp": 1769374275562,
"source": "ems-backend",
"device": "pcs1_lastValue",
"readings": {
"pcs_soc_state_of_charge_item": 55.2
}
}
Error mapping
| HTTP status | Meaning |
|---|---|
| 401 | Backend bearer token is missing or incorrect |
| 404 | Route or device snapshot does not exist |
| 422 | Laravel rejected the request or device name |
| 502 | Laravel cannot connect to ems-backend |
| 4xx/5xx | Python backend returned an error |