Ecovolt API - Consumer API Token Endpoints

Plug - Ecoguard

Get ecoguard-enabled plugs

GET

http://localhost:8080

/api/plug/{systemId}/ecoguard/plugs

Retrieves all plugs in a system that have ecoguard energy-saving rules enabled. Useful for monitoring which devices have automated energy management configured.

Get ecoguard-enabled plugs › path Parameters

systemId

string · required

Get ecoguard-enabled plugs › Responses

Ecoguard-enabled plugs retrieved successfully

Plug[]

Plug

_id

string · required

Primary ID of the Device

Example: 64b7f1e6f9c9d4e5b8a9f7c3

deviceType

string · enum · required

Type of device (discriminator field)

Enum values:

PLUG

MCB

ENV_SENSOR

SMART_SWITCH

AIRCON_CONTROL

WATER_METER

RIDGE

Example: PLUG

macId

string · required

MAC ID of the Device (from IoT device)

Example: 1092384701928347

deviceName

string · required

Name of the Device

Example: Living Room AC

deviceNumber

number · required

Unique device number for identification

Example: 1

onStatus

string · enum · required

Status of the Device (ON / OFF / INACTIVE / ERROR)

Enum values:

OFF

INACTIVE

ERROR

ACTIVE

Example: ON

location

string · required

Physical location or address where the device is installed

Example: Room 101, Building A

remarks

string · required

Remarks for the Device

batchNumber

number · required

Manufacturing batch number for tracking production groups

Example: 1

chipModel

string · enum · required

Hardware chip model identifier used in the device

Enum values:

ESP8266

ESP32C2

ESP32C5

ESP32

ESP32C3

Example: ESP32C2

versionNumber

string · required

Firmware version number currently running on the device

Example: 1.0.0

ssid

string · required

Network SSID (Wi-Fi name) that the device is connected to

Example: IoT-Network-5G

tenant

string · required

Tenant ID reference

object · required

Tagged Zone

room

string · required

Room ID reference

system

string · required

System ID reference

createdAt

string · date-time · required

Date Time of the Creation

Example: 2021-09-01

updatedAt

string · date-time · required

Date Time of the Update

Example: 2021-09-01

lastSeen

string · date-time · required

Last time the device was seen/reported

Example: 2021-09-01

isLocked

boolean · required

Whether the device is locked. When locked, the device on/off status cannot be toggled.

Example: false

totalEnergyUsage

number · required

Total cumulative energy usage in kWh

Example: 0

totalEnergySaved

number · required

Total energy saved through optimization in kWh

Example: 0

autoUpdateAttempts

number · required

Number of auto-update OTA attempts sent to this device

Example: 0

autoUpdateBlacklisted

boolean · required

Whether device is blacklisted from auto-updates (max retries exceeded)

Example: false

manualUpdateBlacklist

boolean · required

Whether device is manually blacklisted from auto-updates by admin

Example: false

inactivityNotificationEnabled

boolean · required

Whether inactivity notifications are enabled for this device

Default: false

plugCategory

string · required

Plug category name. See GET /plug-category for all valid values.

Example: CHARGER

Default: UNREGISTERED

plugType

string · enum · required

Type of Plug

Enum values:

SOCKET

SOAPBAR

ADAPTER

Example: ADAPTER

energyUsageRecommendationReport

string · required

Energy Usage Recommendation Report

Example: 64b7f1e6f9c9d4e5b8a9f7c3

object · required

Ecoguard of the system

Example: 30

migratedTo

string · required

Plug to which this plug has been migrated

Example: 64b7f1e6f9c9d4e5b8a9f7c3

targetState

string · enum

Pending desired on/off state commanded by backend (cloud / scheduled). Set when a toggle is issued; cleared when the device reports a matching state or a physical (MANUAL) press overrides it. Always ON or OFF when present.

Enum values:

OFF

INACTIVE

ERROR

ACTIVE

Example: ON

targetStateSetAt

string · date-time

Timestamp when targetState was last written. Used to expire stale SCHEDULED intents (24hr TTL). CLOUD intents do not expire.

Example: 2026-05-25T08:00:00.000Z

targetSource

string · enum

Origin of the pending targetState. Drives TTL behavior on reconcile. Only CLOUD / SCHEDULED are ever written here.

Enum values:

MANUAL

CLOUD

SCHEDULED

ECOGUARD

WATCHDOG

LWT

UNKNOWN

BOOTUP

Example: CLOUD

deviceModel

string

Model of the device plugged into this smart plug

Example: Dell XPS 15

deviceBrand

string

Brand of the device plugged into this smart plug

Example: Dell

isSpare

boolean

Whether the device is a spare/inventory device. Spare devices can be filtered out of user-facing dashboards.

Example: false

object

Schedule configuration for the device. Contains recurring weekly schedules and one-time scheduled tasks.

realTimePower

number

Real-time power consumption in watts

Example: 1500

realTimeCurrent

number

Real-time current in amperes

Example: 6.5

lastAutoUpdateAttempt

string · date-time

Timestamp of last auto-update OTA attempt

inactivityNotificationSentAt

string · date-time

Timestamp when the last inactivity notification was sent for this device

voltageMax

number

Max Threshold voltage reading in volts

Example: 240

currentMax

number

Max Threshold current reading in amps

Example: 10

powerMax

number

Max Threshold power reading in watts

Example: 100

notificationThresholdHour

number

Hourly notification threshold — minimum hours between repeat notifications of the same type

Example: 4

GET/api/plug/{systemId}/ecoguard/plugs

curl http://localhost:8080/api/plug/:systemId/ecoguard/plugs

Example Responses

[
  {
    "_id": "64b7f1e6f9c9d4e5b8a9f7c3",
    "deviceType": "PLUG",
    "macId": "1092384701928347",
    "deviceName": "Living Room AC",
    "deviceNumber": 1,
    "onStatus": "ON",
    "targetState": "ON",
    "targetStateSetAt": "2026-05-25T08:00:00.000Z",
    "targetSource": "CLOUD",
    "location": "Room 101, Building A",
    "remarks": "remarks",
    "deviceModel": "Dell XPS 15",
    "deviceBrand": "Dell",
    "batchNumber": 1,
    "chipModel": "ESP32C2",
    "versionNumber": "1.0.0",
    "ssid": "IoT-Network-5G",
    "tenant": "tenant",
    "zone": {
      "_id": "64b7f1e6f9c9d4e5b8a9f7c3",
      "name": "Glenn Quah Han Rong",
      "email": "glenn@gmail.com",
      "remarks": "remarks",
      "zoneType": "LABORATORY",
      "zoneEnergyReport": "64b7f1e6f9c9d4e5b8a9f7c3",
      "tenant": "tenant",
      "rooms": [
        "64b7f1e6f9c9d4e5b8a9f7c3"
      ],
      "devices": [
        "64b7f1e6f9c9d4e5b8a9f7c3"
      ],
      "distributionBoxes": [
        "64b7f1e6f9c9d4e5b8a9f7c3"
      ],
      "floorPlanKey": "floor-plans/uuid.png",
      "floorPlanUrl": "https://cdn.ecovolt.ai/floor-plans/uuid.png",
      "floorPlan": "floorPlan"
    },
    "room": "room",
    "system": "system",
    "createdAt": "2021-09-01",
    "updatedAt": "2021-09-01",
    "lastSeen": "2021-09-01",
    "isLocked": false,
    "isSpare": false,
    "deviceSchedule": {
      "oneTimeSchedules": [
        {
          "dateTime": "2023-10-31T06:00:00Z",
          "action": "OFF",
          "actionValue": 24,
          "ruleName": "ruleName"
        }
      ],
      "monday": [
        {
          "time": "06:00",
          "action": "OFF",
          "actionValue": 24,
          "ruleName": "ruleName"
        }
      ],
      "tuesday": [
        {
          "time": "06:00",
          "action": "OFF",
          "actionValue": 24,
          "ruleName": "ruleName"
        }
      ],
      "wednesday": [
        {
          "time": "06:00",
          "action": "OFF",
          "actionValue": 24,
          "ruleName": "ruleName"
        }
      ],
      "thursday": [
        {
          "time": "06:00",
          "action": "OFF",
          "actionValue": 24,
          "ruleName": "ruleName"
        }
      ],
      "friday": [
        {
          "time": "06:00",
          "action": "OFF",
          "actionValue": 24,
          "ruleName": "ruleName"
        }
      ],
      "saturday": [
        {
          "time": "06:00",
          "action": "OFF",
          "actionValue": 24,
          "ruleName": "ruleName"
        }
      ],
      "sunday": [
        {
          "time": "06:00",
          "action": "OFF",
          "actionValue": 24,
          "ruleName": "ruleName"
        }
      ],
      "confirmationState": "PENDING"
    },
    "realTimePower": 1500,
    "realTimeCurrent": 6.5,
    "totalEnergyUsage": 0,
    "totalEnergySaved": 0,
    "autoUpdateAttempts": 0,
    "autoUpdateBlacklisted": false,
    "manualUpdateBlacklist": false,
    "lastAutoUpdateAttempt": "2024-08-25T15:00:00Z",
    "inactivityNotificationEnabled": false,
    "inactivityNotificationSentAt": "2024-08-25T15:00:00Z",
    "plugCategory": "UNREGISTERED",
    "plugType": "ADAPTER",
    "energyUsageRecommendationReport": "64b7f1e6f9c9d4e5b8a9f7c3",
    "ecoguardPlug": "30",
    "migratedTo": "64b7f1e6f9c9d4e5b8a9f7c3",
    "voltageMax": 240,
    "currentMax": 10,
    "powerMax": 100,
    "notificationThresholdHour": 4
  }
]

json

application/json

Plug - Management MCB

Get ecoguard-enabled plugs

GET

http://localhost:8080

/api/plug/{systemId}/ecoguard/plugs

Retrieves all plugs in a system that have ecoguard energy-saving rules enabled. Useful for monitoring which devices have automated energy management configured.

Get ecoguard-enabled plugs › path Parameters

systemId

string · required

Get ecoguard-enabled plugs › Responses

Ecoguard-enabled plugs retrieved successfully

Plug[]

Plug

_id

string · required

Primary ID of the Device

Example: 64b7f1e6f9c9d4e5b8a9f7c3

deviceType

string · enum · required

Type of device (discriminator field)

Enum values:

PLUG

MCB

ENV_SENSOR

SMART_SWITCH

AIRCON_CONTROL

WATER_METER

RIDGE

Example: PLUG

macId

string · required

MAC ID of the Device (from IoT device)

Example: 1092384701928347

deviceName

string · required

Name of the Device

Example: Living Room AC

deviceNumber

number · required

Unique device number for identification

Example: 1

onStatus

string · enum · required

Status of the Device (ON / OFF / INACTIVE / ERROR)

Enum values:

OFF

INACTIVE

ERROR

ACTIVE

Example: ON

location

string · required

Physical location or address where the device is installed

Example: Room 101, Building A

remarks

string · required

Remarks for the Device

batchNumber

number · required

Manufacturing batch number for tracking production groups

Example: 1

chipModel

string · enum · required

Hardware chip model identifier used in the device

Enum values:

ESP8266

ESP32C2

ESP32C5

ESP32

ESP32C3

Example: ESP32C2

versionNumber

string · required

Firmware version number currently running on the device

Example: 1.0.0

ssid

string · required

Network SSID (Wi-Fi name) that the device is connected to

Example: IoT-Network-5G

tenant

string · required

Tenant ID reference

object · required

Tagged Zone

room

string · required

Room ID reference

system

string · required

System ID reference

createdAt

string · date-time · required

Date Time of the Creation

Example: 2021-09-01

updatedAt

string · date-time · required

Date Time of the Update

Example: 2021-09-01

lastSeen

string · date-time · required

Last time the device was seen/reported

Example: 2021-09-01

isLocked

boolean · required

Whether the device is locked. When locked, the device on/off status cannot be toggled.

Example: false

totalEnergyUsage

number · required

Total cumulative energy usage in kWh

Example: 0

totalEnergySaved

number · required

Total energy saved through optimization in kWh

Example: 0

autoUpdateAttempts

number · required

Number of auto-update OTA attempts sent to this device

Example: 0

autoUpdateBlacklisted

boolean · required

Whether device is blacklisted from auto-updates (max retries exceeded)

Example: false

manualUpdateBlacklist

boolean · required

Whether device is manually blacklisted from auto-updates by admin

Example: false

inactivityNotificationEnabled

boolean · required

Whether inactivity notifications are enabled for this device

Default: false

plugCategory

string · required

Plug category name. See GET /plug-category for all valid values.

Example: CHARGER

Default: UNREGISTERED

plugType

string · enum · required

Type of Plug

Enum values:

SOCKET

SOAPBAR

ADAPTER

Example: ADAPTER

energyUsageRecommendationReport

string · required

Energy Usage Recommendation Report

Example: 64b7f1e6f9c9d4e5b8a9f7c3

object · required

Ecoguard of the system

Example: 30

migratedTo

string · required

Plug to which this plug has been migrated

Example: 64b7f1e6f9c9d4e5b8a9f7c3

targetState

string · enum

Enum values:

OFF

INACTIVE

ERROR

ACTIVE

Example: ON

targetStateSetAt

string · date-time

Timestamp when targetState was last written. Used to expire stale SCHEDULED intents (24hr TTL). CLOUD intents do not expire.

Example: 2026-05-25T08:00:00.000Z

targetSource

string · enum

Origin of the pending targetState. Drives TTL behavior on reconcile. Only CLOUD / SCHEDULED are ever written here.

Enum values:

MANUAL

CLOUD

SCHEDULED

ECOGUARD

WATCHDOG

LWT

UNKNOWN

BOOTUP

Example: CLOUD

deviceModel

string

Model of the device plugged into this smart plug

Example: Dell XPS 15

deviceBrand

string

Brand of the device plugged into this smart plug

Example: Dell

isSpare

boolean

Whether the device is a spare/inventory device. Spare devices can be filtered out of user-facing dashboards.

Example: false

object

Schedule configuration for the device. Contains recurring weekly schedules and one-time scheduled tasks.

realTimePower

number

Real-time power consumption in watts

Example: 1500

realTimeCurrent

number

Real-time current in amperes

Example: 6.5

lastAutoUpdateAttempt

string · date-time

Timestamp of last auto-update OTA attempt

inactivityNotificationSentAt

string · date-time

Timestamp when the last inactivity notification was sent for this device

voltageMax

number

Max Threshold voltage reading in volts

Example: 240

currentMax

number

Max Threshold current reading in amps

Example: 10

powerMax

number

Max Threshold power reading in watts

Example: 100

notificationThresholdHour

number

Hourly notification threshold — minimum hours between repeat notifications of the same type

Example: 4