EVLinkHA – Home Assistant API Reference - rogasp/evlink-backend GitHub Wiki

EVLinkHA – Home Assistant API Reference

This page documents all REST endpoints available for integrating EVLinkHA with Home Assistant.

Status Endpoint

GET /api/status/{vehicle_id}

Authentication
Must provide a valid API key in the HTTP Authorization header:

Authorization: Bearer <your-api-key>

Response Format
The response contains basic vehicle info and a detailed chargeState object.

{
  "batteryLevel": 18,
  "range": 98.28,
  "isCharging": false,
  "isPluggedIn": false,
  "chargingState": "UNPLUGGED",
  "vehicleName": "XPENG G6",
  "lastSeen": "2025-05-20T15:48:12.933Z",
  "isReachable": true,
  "chargeState": {
    "batteryLevel": 18,
    "range": 98.28,
    "isPluggedIn": false,
    "isCharging": false,
    "batteryCapacity": 91,
    "chargeLimit": null,
    "chargeRate": null,
    "chargeTimeRemaining": null,
    "isFullyCharged": false,
    "lastUpdated": "2025-05-13T14:15:29.717Z",
    "powerDeliveryState": "UNPLUGGED",
    "maxCurrent": null
  }
}

⚠️ Note: Top-level keys like batteryLevel, isCharging, and chargingState are legacy and will be removed in a future version. Use the values inside chargeState instead.

Field Reference

  • chargeState.batteryLevel: Current battery percentage.

  • chargeState.range: Estimated range in kilometers.

  • chargeState.isCharging: Whether the vehicle is actively charging.

  • chargeState.isPluggedIn: Whether the vehicle is physically connected.

  • chargeState.batteryCapacity: Total battery capacity in kWh.

  • chargeState.chargeLimit: Configured charge limit (%) if available.

  • chargeState.chargeRate: Current charging rate in kW if available.

  • chargeState.chargeTimeRemaining: Minutes remaining to full.

  • chargeState.isFullyCharged: Battery full status.

  • chargeState.maxCurrent: Max current in amps if available.

  • chargeState.lastUpdated: Timestamp when this block was updated.

  • chargeState.powerDeliveryState: Enum for detailed power state (e.g., PLUGGED_IN:CHARGING).

Control Charging Endpoint [PRO β]

Beta: On-demand charging control.

POST /api/charging/{vehicle_id}

Only users on the Pro tier can access this endpoint.

Request Body

{
  "action": "START" // or "STOP"
}

{
  "status": "success",
  "vehicle_id": "331c054f-b583-4284-b7b0-ce348c0a66fc",
  "enode_vehicle_id": "9801efc6-2d23-4fc5-bdc6-ba40b4e25e55",
  "action": "START",
  "enode_response": { /* … */ }
}

Error Handling

Status Description
401 Unauthorized: Missing or invalid API key
403 Forbidden: User not on Pro tier or not owner of vehicle
404 Not Found: Vehicle not found in EVLinkHA
400 Bad Request: Invalid vehicle state (e.g., START when unplugged, STOP when not charging)
422 Unprocessable Entity: Vehicle under scheduled or smart charging control
429 Too Many Requests: Rate limit exceeded
500 Internal Server Error: Missing Enode ID or unexpected error

Note: The backend will retry until the vehicle’s powerDeliveryState matches the desired state. It may take a few seconds for status updates.

⚠️ **GitHub.com Fallback** ⚠️