Skip to content

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