Ecovolt API - Consumer API Token Endpoints

MCB - Management

Get MCB by ID

GET

http://localhost:8080

/api/mcb/by-id/{deviceId}

Retrieves a single MCB by its unique ID with full details including system, tenant, room, and distribution box information.

Get MCB by ID › path Parameters

deviceId

string · required

Get MCB by ID › Responses

MCB retrieved successfully

MCB

_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

mcbType

string · enum · required

Type of MCB

Enum values:

UNREGISTERED

SWITCH

BUILT_IN

COIL

COIL3P

Example: COIL

mcbPoles

string · enum · required

Number of poles in the MCB

Enum values:

UNREGISTERED

SINGLE_POLE

DOUBLE_POLE

THREE_POLE

FOUR_POLE

Example: SINGLE_POLE

ratedCurrent

number · required

Rated current capacity in amperes

Example: 16

ratedVoltage

number · required

Rated voltage in volts

Example: 230

realTimeVoltage

number · required

Real-time voltage in volts

Example: 230

powerFactor

number · required

Power factor (0-1)

Example: 0.95

object · required

Parent distribution box containing this MCB

isReversePower

boolean · required

Whether power/current readings should be reversed (made absolute). When true, negative values are converted to positive.

Example: false

Default: false

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 name or identifier of the device

Example: TP-Link HS110

deviceBrand

string

Brand or manufacturer of the device

Example: TP-Link

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

measurementType

string · enum

Type of load/circuit being measured by this MCB

Enum values:

SSO

LIGHTS_FANS

LIGHTS

FANS

AIRCON

POWER_OUTLETS

GENERAL

COMBINED

Example: SSO

digitalTwinX

number

X coordinate for digital twin SVG positioning

Example: 150.5

rowLine

number

Row line number (1-6) the MCB is connected to

Example: 1

slotNumber

number

Slot/position number on the busbar

Example: 3

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/mcb/by-id/{deviceId}

curl http://localhost:8080/api/mcb/by-id/:deviceId

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": "TP-Link HS110",
  "deviceBrand": "TP-Link",
  "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",
  "mcbType": "COIL",
  "mcbPoles": "SINGLE_POLE",
  "measurementType": "SSO",
  "ratedCurrent": 16,
  "ratedVoltage": 230,
  "realTimeVoltage": 230,
  "powerFactor": 0.95,
  "distributionBox": {
    "_id": "64b7f1e6f9c9d4e5b8a9f7c3",
    "name": "Main DB Box - Floor 1",
    "boxNumber": 1,
    "numberOfRows": 1,
    "mcbs": [
      "64b7f1e6f9c9d4e5b8a9f7c3"
    ],
    "hasMainBreaker": true,
    "mainBreakerRating": 63,
    "location": "Ground Floor, Electrical Room",
    "remarks": "Main distribution panel installed in 2024",
    "system": "64b7f1e6f9c9d4e5b8a9f7c3",
    "tenant": "64b7f1e6f9c9d4e5b8a9f7c4",
    "zone": "64b7f1e6f9c9d4e5b8a9f7c5",
    "room": "64b7f1e6f9c9d4e5b8a9f7c6",
    "sandboxDevices": [
      {
        "id": "sandbox-device-1",
        "type": "DUMB_MCB",
        "name": "Kitchen Lights",
        "digitalTwinX": 400,
        "rowLine": 2,
        "ratedCurrent": 16,
        "ratedVoltage": 230,
        "mcbType": "BUILT_IN",
        "mcbPoles": "SINGLE_POLE",
        "leakageCurrent": 30,
        "color": "#94a3b8",
        "notes": "Connected to kitchen circuit"
      }
    ],
    "sandboxWires": [
      {
        "id": "wire-1",
        "from": {
          "deviceId": "sandbox-device-1",
          "deviceType": "DUMB_MCB",
          "side": "LEFT"
        },
        "to": {
          "deviceId": "sandbox-device-1",
          "deviceType": "DUMB_MCB",
          "side": "LEFT"
        },
        "color": "#fbbf24",
        "thickness": 3,
        "label": "Phase 1"
      }
    ],
    "digitalTwinWidth": 1200,
    "digitalTwinHeight": 800,
    "singleLineDiagramKey": "single-line-diagrams/abc123-def456.png",
    "singleLineDiagramUrl": "https://cdn.example.com/single-line-diagrams/abc123-def456.png",
    "createdAt": "2024-08-25T15:00:00Z",
    "updatedAt": "2024-08-25T15:00:00Z"
  },
  "digitalTwinX": 150.5,
  "rowLine": 1,
  "slotNumber": 3,
  "isReversePower": false,
  "voltageMax": 240,
  "currentMax": 10,
  "powerMax": 100,
  "notificationThresholdHour": 4
}

json

application/json

Get bulk MCB suggested names

GET

http://localhost:8080

/api/mcb/bulk/names

Generates suggested device names for multiple MCBs based on their Distribution Box name, Room name, and Measurement type. Format: "DistributionBoxName | RoomName | MeasurementType" (e.g. "DB-4-7U-5 | 4/7/E | Lights & Fans"). Requires SUPERADMIN or ADMIN role.

Get bulk MCB suggested names › query Parameters

mcbIds

string · required

Comma-separated list of MCB IDs to generate names for

Example: 64b7f1e6f9c9d4e5b8a9f7c3,64b7f1e6f9c9d4e5b8a9f7c4

Get bulk MCB suggested names › Responses

Suggested names generated successfully

GetBulkMCBNamesResponseDto

MCBNameSuggestionDto[] · required

Array of MCB IDs with their suggested names

MCB AirconControl

Get MCB by ID

GET

http://localhost:8080

/api/mcb/by-id/{deviceId}

Retrieves a single MCB by its unique ID with full details including system, tenant, room, and distribution box information.

Get MCB by ID › path Parameters

deviceId

string · required

Get MCB by ID › Responses

MCB retrieved successfully

MCB

_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

mcbType

string · enum · required

Type of MCB

Enum values:

UNREGISTERED

SWITCH

BUILT_IN

COIL

COIL3P

Example: COIL

mcbPoles

string · enum · required

Number of poles in the MCB

Enum values:

UNREGISTERED

SINGLE_POLE

DOUBLE_POLE

THREE_POLE

FOUR_POLE

Example: SINGLE_POLE

ratedCurrent

number · required

Rated current capacity in amperes

Example: 16

ratedVoltage

number · required

Rated voltage in volts

Example: 230

realTimeVoltage

number · required

Real-time voltage in volts

Example: 230

powerFactor

number · required

Power factor (0-1)

Example: 0.95

object · required

Parent distribution box containing this MCB

isReversePower

boolean · required

Whether power/current readings should be reversed (made absolute). When true, negative values are converted to positive.

Example: false

Default: false

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 name or identifier of the device

Example: TP-Link HS110

deviceBrand

string

Brand or manufacturer of the device

Example: TP-Link

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

measurementType

string · enum

Type of load/circuit being measured by this MCB

Enum values:

SSO

LIGHTS_FANS

LIGHTS

FANS

AIRCON

POWER_OUTLETS

GENERAL

COMBINED

Example: SSO

digitalTwinX

number

X coordinate for digital twin SVG positioning

Example: 150.5

rowLine

number

Row line number (1-6) the MCB is connected to

Example: 1

slotNumber

number

Slot/position number on the busbar

Example: 3

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 bulk MCB suggested names

GET

http://localhost:8080

/api/mcb/bulk/names

Get bulk MCB suggested names › query Parameters

mcbIds

string · required

Comma-separated list of MCB IDs to generate names for

Example: 64b7f1e6f9c9d4e5b8a9f7c3,64b7f1e6f9c9d4e5b8a9f7c4

Get bulk MCB suggested names › Responses

Suggested names generated successfully

GetBulkMCBNamesResponseDto

MCBNameSuggestionDto[] · required

Array of MCB IDs with their suggested names