Schemas

AssetType

string · enum

Enum values:

image

video

Type of media asset (image or video)

ReleaseResponseBodyDto

releaseDescription

string · required

Release Description for current release page

Example: We are excited to announce the release of version 1.2.0...

assetKey

string · required

S3 object key for the release media asset

Example: releases/123e4567-e89b-12d3-a456-426614174000.mp4

assetType

string · enum · required

Type of media asset (image or video)

Enum values:

image

video

Example: video

assetUrl

string · required

Url to access the media asset

Example: https://cdn.example.com/releases/123e4567-e89b-12d3-a456-426614174000.mp4

ctaLabel

string

Optional call-to-action button label

Example: Open Notification Settings

ctaUrl

string

Optional call-to-action URL. Use {systemId} as a placeholder for the active system.

Example: /system/{systemId}/system-settings/notification-settings

ctaIsExternal

boolean

Whether the CTA link should open in a new tab (external) or navigate within the app.

Example: false

ReleaseResponseDto

_id

string · required

Unique identifier for the release

Example: 507f1f77bcf86cd799439011

releaseTitle

string · required

Release Title for current global operation

Example: New Release v1.2.0

ReleaseResponseBodyDto[] · required

Array of objects containing respective descriptions and media for the release.

ReleaseBodyDto

releaseDescription

string · required

Release description for current release page

Example: We are excited to announce the release of version 1.2.0...

file

string

Media file (image or video) for the current release page

existingAssetKey

string

Existing S3 object key for the release media asset

ctaLabel

string

Optional call-to-action button label

Example: Open Notification Settings

ctaUrl

string

Optional call-to-action URL. Use {systemId} as a placeholder for the active system.

Example: /system/{systemId}/system-settings/notification-settings

ctaIsExternal

boolean

Whether the CTA link should open in a new tab (external) or navigate within the app.

Example: false

ReleaseDto

releaseTitle

string · required

Release Title for current global operation

Example: New Release v1.0.0

ReleaseBodyDto[] · required

Array of objects containing respective descriptions and media for the release.

CreateManufacturerApiKeyDto

label

string · required

Human-readable label for this key

Example: Factory Line A

ManufacturerApiKeyCreatedResponseDto

_id

string · required

label

string · required

keyPrefix

string · required

First 8 chars of the key (for identification only)

Example: mfr_a1b2

enabled

boolean · required

createdAt

string · date-time · required

updatedAt

string · date-time · required

key

string · required

Full API key — shown once only, store it securely

Example: mfr_a1b2c3d4-e5f6-7890-abcd-ef1234567890

ManufacturerApiKeyResponseDto

_id

string · required

label

string · required

keyPrefix

string · required

First 8 chars of the key (for identification only)

Example: mfr_a1b2

enabled

boolean · required

createdAt

string · date-time · required

updatedAt

string · date-time · required

DeviceType

string · enum

Enum values:

PLUG

MCB

ENV_SENSOR

SMART_SWITCH

AIRCON_CONTROL

WATER_METER

RIDGE

Type of device (PLUG, MCB, etc.)

UsageHistoryHour

_id

string · required

Primary ID of the UsageHistoryHour

Example: 64b7f1e6f9c9d4e5b8a9f7c3

hour

number · required

No. What Hour (E.g. 7 means 0700 - 0800)

Example: 7

onStatus

string · enum · required

Status of the Plug (ON / OFF)

Enum values:

OFF

INACTIVE

ERROR

ACTIVE

Example: ON

deviceType

string · enum · required

Type of device (PLUG, MCB, etc.)

Enum values:

PLUG

MCB

ENV_SENSOR

SMART_SWITCH

AIRCON_CONTROL

WATER_METER

RIDGE

Example: PLUG

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

actualDate

string · date-time · required

Date Time of the Update

Example: 2021-09-01

macId

string · required

MAC ID of the device

Example: 1092384701928347

device

string · required

Reference to the device

Example: 64b7f1e6f9c9d4e5b8a9f7c3

wifiStrength

number

WiFi signal strength at the time of the hourly record

Example: -65

UsageHistoryDay

_id

string · required

Primary ID of the UsageHistoryDay

Example: 64b7f1e6f9c9d4e5b8a9f7c3

UsageHistoryHour[] · required

Usage History of the device (Hourly)

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

deviceType

string · enum · required

Type of device (PLUG, MCB, etc.)

Enum values:

PLUG

MCB

ENV_SENSOR

SMART_SWITCH

AIRCON_CONTROL

WATER_METER

RIDGE

Example: PLUG

macId

string · required

MAC ID of the device

Example: 1092384701928347

device

string · required

Reference to the device

Example: 64b7f1e6f9c9d4e5b8a9f7c3

UsageHistoryDayWithCostBreakdownDto

date

string · required

No. Hour of the Usage History

Example: 2023-03-15

totalEnergyUsage

number · required

Total Energy Usage in a Day (kWh)

Example: 12.48

cost

number · required

Energy cost for this day in dollars. Zero (0) if no tariff rate is configured for this day.

Example: 23.1

tariffRate

number | null

Tariff rate applied for this day in cents per kWh/L. Null if no tariff rate is configured.

Example: 10

UsageHistoryDayBreakdownDto

date

string · required

No. Hour of the Usage History

Example: 2023-03-15

totalEnergyUsage

number · required

Total Energy Usage in a Day (kWh)

Example: 12.48

UsageHistoryHourBreakdownDto

hour

number · required

No. Hour of the Usage History

Example: 7

totalEnergyUsage

number · required

Total Energy Usage in a Hour (kWh)

Example: 231

UsageHistoryHourWithTariffResponseDto

UsageHistoryHourBreakdownDto[] · required

Array of hourly usage data

Example: [{"hour":0,"totalEnergyUsage":1.2},{"hour":1,"totalEnergyUsage":1.5}]

currentTariffRate

number | null

Current tariff rate in cost per kWh. Null if no tariff rate is configured. Useful for frontend calculations.

Example: 0.25

DeviceStatus

string · enum

Enum values:

OFF

INACTIVE

ERROR

ACTIVE

Status of the device (ON / OFF)

UsageHistoryEnergyRealtimeDto

onStatus

string · enum · required

Status of the device (ON / OFF)

Enum values:

OFF

INACTIVE

ERROR

ACTIVE

Example: ON

createdAt

string · date-time · required

Date Time of the Creation

Example: 2021-09-01T00:00:00.000Z

current

number · required

Current in Amperes (A)

Example: 2.5

voltage

number · required

Voltage in Volts (V)

Example: 230

powerFactor

number · required

Power factor (0-1)

Example: 0.9

power

number · required

Power in Watts (W)

Example: 517.5

voltageA

number

Phase A voltage (V)

voltageB

number

Phase B voltage (V)

voltageC

number

Phase C voltage (V)

currentA

number

Phase A current (A)

currentB

number

Phase B current (A)

currentC

number

Phase C current (A)

activePowerA

number

Phase A active power (W)

activePowerB

number

Phase B active power (W)

activePowerC

number

Phase C active power (W)

reactivePowerA

number

Phase A reactive power (VAR)

reactivePowerB

number

Phase B reactive power (VAR)

reactivePowerC

number

Phase C reactive power (VAR)

apparentPowerA

number

Phase A apparent power (VA)

apparentPowerB

number

Phase B apparent power (VA)

apparentPowerC

number

Phase C apparent power (VA)

powerFactorA

number

Phase A power factor (0-1)

powerFactorB

number

Phase B power factor (0-1)

powerFactorC

number

Phase C power factor (0-1)

frequency

number

Line frequency (Hz)

McbRealtimeDataPointDto

createdAt

string · date-time · required

power

number · required

Summed power at this timestamp in Watts (W)

Example: 200

McbRealtimeSeriesDto

measurementType

string · required

MCB measurement type for this series, or "COMBINED" for the total across all types

Example: SSO

McbRealtimeDataPointDto[] · required

max

number

Maximum power value across all data points in this series (W). Only present for the COMBINED series.

Example: 500

average

number

Average power value across all data points in this series (W). Only present for the COMBINED series.

Example: 250

McbRoomRealtimeResponseDto

McbRealtimeSeriesDto[] · required

One time-series per MCB measurement type found in the room, plus a COMBINED series that sums all types

RoomMcbAiInsightPossibleDeviceDto

device

string · required

reason

string · required

RoomMcbAiInsightResponseDto

summary

string · required

One-liner summary of room energy behaviour

Example: This room shows signs of an overnight portable AC and a mini fridge drawing constant baseline power.

RoomMcbAiInsightPossibleDeviceDto[] · required

List of predicted devices and why

DeviceEnergyDto

energy

number · required

Total energy consumed by the device in watt-hours.

Example: 231

UsageWithCostResponseDto

totalEnergyUsage

number · required

Total energy usage in kWh

Example: 125.5

totalCost

number | null

Total cost based on current tariff rate. Null if no tariff rate is configured.

Example: 31.375

tariffRate

number | null

Current tariff rate in cost per kWh. Null if no tariff rate is configured.

Example: 0.25

TelemetryHourSmartSwitchResponseDto

hour

number · required

Hour of the day (0–23)

Example: 7

onStatus

string · enum · required

Device on/off status for this hour

Enum values:

OFF

INACTIVE

ERROR

ACTIVE

Example: ON

createdAt

string · date-time · required

Record creation timestamp

Example: 2024-01-15T07:10:00.000Z

downTime

number

Total downtime in milliseconds for this hour (3600000 = full hour down)

Example: 1800000

gangSwitchStatus

number[]

Gang switch states reported by the device (array index = gang index, 1 = ON, 0 = OFF)

Example: [1,0,1]

actualDate

string · date-time

Actual date this hourly record is for

Example: 2024-01-15T07:00:00.000Z

TelemetryAirconControlRealtimeResponseDto

onStatus

string · enum · required

Device on/off status

Enum values:

OFF

INACTIVE

ERROR

ACTIVE

createdAt

string · date-time · required

Record creation timestamp

ambientTemperature

number

Ambient temperature in Celsius

Example: 24.5

ambientHumidity

number

Ambient humidity percentage

Example: 65

TelemetryHourAirconControlResponseDto

hour

number · required

Hour of the day (0–23)

Example: 7

onStatus

string · enum · required

Device on/off status for this hour

Enum values:

OFF

INACTIVE

ERROR

ACTIVE

Example: ON

createdAt

string · date-time · required

Record creation timestamp

Example: 2024-01-15T07:10:00.000Z

downTime

number

Total downtime in milliseconds for this hour (3600000 = full hour down)

Example: 1800000

ambientTemperature

number

Ambient temperature in Celsius

Example: 24.5

ambientHumidity

number

Ambient humidity percentage

Example: 65

actualDate

string · date-time

Actual date this hourly record is for

Example: 2024-01-15T07:00:00.000Z

BoxplotDeviceType

string · enum

Enum values:

PLUG

MCB

DISTRIBUTION_BOX

ENV_SENSOR

DeviceBoxplotEntryDto

min

number · required

q1

number · required

median

number · required

q3

number · required

max

number · required

hour

number · required

Hour of the day (0–23)

Example: 14

deviceCount

number · required

Number of distinct entities with data in this hour

Example: 5

DeviceBoxplotResponseDto

DeviceBoxplotEntryDto[] · required

Hourly box plot entries (only hours with data)

DeviceBoxStatsDto

min

number · required

q1

number · required

median

number · required

q3

number · required

max

number · required

DeviceBreakdownEntryDto

deviceId

string · required

deviceName

string · required

value

number · required

Aggregated value for this entity in the hour

Example: 0.42

DeviceDrilldownResponseDto

object · required

Overall box plot statistics across all entities in the hour

DeviceBreakdownEntryDto[] · required

Per-entity breakdown

totalDevices

number · required

TelemetryHourEnvironmentSensor

_id

string · required

Primary ID of the UsageHistoryHour

Example: 64b7f1e6f9c9d4e5b8a9f7c3

hour

number · required

No. What Hour (E.g. 7 means 0700 - 0800)

Example: 7

onStatus

string · enum · required

Status of the Plug (ON / OFF)

Enum values:

OFF

INACTIVE

ERROR

ACTIVE

Example: ON

deviceType

string · enum · required

Type of device (PLUG, MCB, etc.)

Enum values:

PLUG

MCB

ENV_SENSOR

SMART_SWITCH

AIRCON_CONTROL

WATER_METER

RIDGE

Example: PLUG

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

actualDate

string · date-time · required

Date Time of the Update

Example: 2021-09-01

macId

string · required

MAC ID of the device

Example: 1092384701928347

device

string · required

Reference to the device

Example: 64b7f1e6f9c9d4e5b8a9f7c3

carbonDioxide

number · required

Current CO2 reading in ppm

Example: 400

lux

number · required

Current light level in lux (lx)

Example: 500

formaldehyde

number · required

Current formaldehyde (HCHO) reading in ppm

Example: 0.03

temperature

number · required

Current temperature reading in degrees Celsius

Example: 24

humidity

number · required

Current humidity percentage

Example: 24

fineParticulateMatter

number · required

Current Fine Particulate Matter in µg/m3

Example: 1

coarseParticulateMatter

number · required

Current Coarse Particulate Matter in µg/m3

Example: 1

totalVolatileOrganicCompounds

number · required

Total Volatile Organic Compounds in ppm

Example: 1

soundLevel

number · required

Current Sound Level in dB

Example: 1

motionDetected

boolean · required

Motion detection status

Example: true

wifiStrength

number

WiFi signal strength at the time of the hourly record

Example: -65

TelemetryEnvironmentSensor

_id

string · required

Primary ID of the Usage History Real Time

Example: 64b7f1e6f9c9d4e5b8a9f7c3

onStatus

string · enum · required

Status of the device (ON / OFF)

Enum values:

OFF

INACTIVE

ERROR

ACTIVE

Example: ON

deviceType

string · enum · required

Type of device (PLUG, MCB, etc.)

Enum values:

PLUG

MCB

ENV_SENSOR

SMART_SWITCH

AIRCON_CONTROL

WATER_METER

RIDGE

Example: PLUG

macId

string · required

MAC ID of the device

Example: 1092384701928347

device

string · required

Reference to the device

Example: 64b7f1e6f9c9d4e5b8a9f7c3

createdAt

string · date-time · required

Date Time of the Creation

Example: 2021-09-01

temperature

number · required

Current temperature reading in degrees Celsius

Example: 24

carbonDioxide

number · required

Current CO2 reading in ppm

Example: 400

lux

number · required

Current light level in lux (lx)

Example: 500

formaldehyde

number · required

Current formaldehyde (HCHO) reading in ppm

Example: 0.03

humidity

number · required

Current humidity percentage

Example: 24

fineParticulateMatter

number · required

Current Fine Particulate Matter in µg/m3

Example: 1

coarseParticulateMatter

number · required

Current Coarse Particulate Matter in µg/m3

Example: 1

totalVolatileOrganicCompounds

number · required

Total Volatile Organic Compounds in ppm

Example: 1

soundLevel

number · required

Current Sound Level in dB

Example: 1

motionDetected

boolean · required

Motion detection status

Example: true

TelemetryHourWaterMeter

_id

string · required

Primary ID of the UsageHistoryHour

Example: 64b7f1e6f9c9d4e5b8a9f7c3

hour

number · required

No. What Hour (E.g. 7 means 0700 - 0800)

Example: 7

onStatus

string · enum · required

Device status during this hour

Enum values:

OFF

INACTIVE

ERROR

ACTIVE

Example: ON

deviceType

string · enum · required

Type of device (PLUG, MCB, etc.)

Enum values:

PLUG

MCB

ENV_SENSOR

SMART_SWITCH

AIRCON_CONTROL

WATER_METER

RIDGE

Example: PLUG

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

actualDate

string · date-time · required

Date Time of the Update

Example: 2021-09-01

macId

string · required

MAC ID of the device

Example: 1092384701928347

device

string · required

Reference to the device

Example: 64b7f1e6f9c9d4e5b8a9f7c3

waterConsumption

number · required

Total water consumption for this hour (liters)

realTimeFlowRate

number · required

Average flow rate for this hour (L/min)

realTimePressure

number · required

Average pressure for this hour (bar)

wifiStrength

number

WiFi signal strength at the time of the hourly record

Example: -65

realTimeTemperature

number

Average temperature for this hour (Celsius)

TelemetryWaterMeter

_id

string · required

Primary ID of the Usage History Real Time

Example: 64b7f1e6f9c9d4e5b8a9f7c3

onStatus

string · enum · required

Device status

Enum values:

OFF

INACTIVE

ERROR

ACTIVE

Example: ON

deviceType

string · enum · required

Type of device (PLUG, MCB, etc.)

Enum values:

PLUG

MCB

ENV_SENSOR

SMART_SWITCH

AIRCON_CONTROL

WATER_METER

RIDGE

Example: PLUG

macId

string · required

MAC ID of the device

Example: 1092384701928347

device

string · required

Reference to the device

Example: 64b7f1e6f9c9d4e5b8a9f7c3

createdAt

string · date-time · required

Date Time of the Creation

Example: 2021-09-01

realTimeFlowRate

number · required

Current flow rate in liters per minute (L/min)

realTimePressure

number · required

Water pressure in bar

waterConsumption

number · required

Cumulative water consumption in liters

realTimeTemperature

number

Water temperature in Celsius

TelemetryDayWaterMeter

_id

string · required

Primary ID of the UsageHistoryDay

Example: 64b7f1e6f9c9d4e5b8a9f7c3

UsageHistoryHour[] · required

Usage History of the device (Hourly)

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

deviceType

string · enum · required

Type of device (PLUG, MCB, etc.)

Enum values:

PLUG

MCB

ENV_SENSOR

SMART_SWITCH

AIRCON_CONTROL

WATER_METER

RIDGE

Example: PLUG

macId

string · required

MAC ID of the device

Example: 1092384701928347

device

string · required

Reference to the device

Example: 64b7f1e6f9c9d4e5b8a9f7c3

waterConsumption

number · required

Total daily water consumption (liters)

realTimeFlowRate

number · required

Average daily flow rate (L/min)

realTimePressure

number · required

Average daily pressure (bar)

realTimeTemperature

number

Average daily temperature (Celsius)

Role

string · enum

Enum values:

SUPERADMIN

ADMIN

USER

TENANT

ROOM

Administrator role defining access permissions (SUPERADMIN or ADMIN)

FrontendApp

string · enum

Enum values:

everest

base

docs

trek

Frontend app context for app-specific signup flows

SignUpDto

name

string · required

Full name of the administrator

Example: John Smith

email

string · required

Email address for the administrator account (must be unique)

Example: john.smith@ecovolt.com

password

string

Account password (minimum 6 characters, optional for invited admins)

Example: SecurePass123

role

string · enum

Administrator role defining access permissions (SUPERADMIN or ADMIN)

Enum values:

SUPERADMIN

ADMIN

USER

TENANT

ROOM

Example: ADMIN

app

string · enum

Frontend app context for app-specific signup flows

Enum values:

everest

base

docs

trek

Example: base

unitName

string

Unit name for B2C signup — used as the zone name for the user's space

Example: Block 123 #04-12

approved

boolean

Whether the admin account is approved and can access the system

Example: true

associatedZone

string

Optional zone ID to associate this admin with a specific zone account

Example: 64b7f1e6f9c9d4e5b8a9f7c4

associatedTenant

string

Optional tenant ID to associate this admin with a specific tenant

Example: 64b7f1e6f9c9d4e5b8a9f7c3

associatedRoom

string

Optional room ID to associate this admin with a specific room

Example: 64b7f1e6f9c9d4e5b8a9f7c2

LoginResponseDto

isSuccessful

boolean · required

Indicates if the login was successful

Example: true

id

string · required

User ID of the authenticated user

Example: 60f2e1f3f7f7f0002f00c7e9

token

string · required

JWT authentication token

Example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

mainSystemId

string · required

Main system ID associated with the user

Example: 60f2e1f3f7f7f0002f00c7e9

requires2FA

boolean · required

Indicates if the user has 2FA enabled and needs to complete 2FA verification

Example: false

role

string · enum

Role of the authenticated user

Enum values:

SUPERADMIN

ADMIN

USER

TENANT

ROOM

Example: ADMIN

associatedTenantId

string

Associated tenant ID if user has TENANT role

Example: 60f2e1f3f7f7f0002f00c7e9

associatedUserId

string

Associated user ID if user has USER role

Example: 60f2e1f3f7f7f0002f00c7e9

associatedRoomId

string

Associated room ID if user has ROOM_ADMIN role

Example: 60f2e1f3f7f7f0002f00c7e9

refreshToken

string

Refresh token for obtaining new access tokens. Not provided when 2FA verification is pending.

Example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

LoginDto

email

string · required

Administrator email address used for authentication

Example: admin@ecovolt.com

password

string · required

Administrator password (minimum 6 characters)

Example: SecurePass123

app

string · enum

Frontend app identifier for role-based access control

Enum values:

everest

base

docs

trek

Example: everest

InviteDto

inviterId

string · required

ID of the administrator sending the invitation

Example: 64b7f1e6f9c9d4e5b8a9f7c1

systemId

string · required

System ID where the new admin will have access

Example: 64b7f1e6f9c9d4e5b8a9f7c2

name

string · required

Full name of the person being invited

Example: Jane Doe

email

string · required

Email address where the invitation will be sent

Example: jane.doe@ecovolt.com

role

string · enum · required

Role to be assigned to the new administrator (SUPERADMIN or ADMIN)

Enum values:

SUPERADMIN

ADMIN

USER

TENANT

ROOM

Example: ADMIN

associatedZone

string

Optional zone ID to link this admin account to an existing zone

Example: 64b7f1e6f9c9d4e5b8a9f7c4

associatedTenant

string

Optional tenant ID to associate this admin with a specific tenant for billing

Example: 64b7f1e6f9c9d4e5b8a9f7c3

associatedRoom

string

Optional room ID to associate this admin with a specific room

Example: 64b7f1e6f9c9d4e5b8a9f7c2

ReInviteDto

inviterId

string · required

ID of the Admin that is inviting

Example: 1234567890abcdef12345678

systemId

string · required

ID of the System

Example: 1234567890abcdef12345678

email

string · required

Email of the Admin

Example: glenn@gmail.com

SignUpViaInviteDto

token

string · required

Reset password token for the Admin

Example: reset-token-123

password

string

Password of the Admin

Example: password

RequestResetPasswordDto

email

string · required

Email of the Admin

Example: glenn@gmail.com

ResetPasswordDto

token

string · required

Reset password token for the Admin

Example: reset-token-123

newPassword

string · required

New password for the Admin

Example: NewPassword123!

ValidateTokenResponseDto

message

string · required

adminId

string · required

GoogleTokenDto

credential

string · required

Google Identity Services ID token (JWT credential) obtained client-side via the GIS button. Verified server-side against the configured Google client ID.

Example: eyJhbGciOiJSUzI1NiIsImtpZCI6...

app

string · enum

Frontend app identifier for role-based access control

Enum values:

everest

base

docs

trek

Example: base

Auth2FAResponseDto

issuer

string · required

Issuer for the 2FA secret

Example: Ecovolt

label

string · required

Label for the 2FA secret

Example: Ecovolt

secret

string · required

2FA secret

Example: ABC123

Disable2FAResponseDto

message

string · required

Success message

Example: 2FA disabled for 5 users in the system

ValidateTokenDto

token

string · required

Disable2FASystemResponseDto

message

string · required

Success message

Example: 2FA disabled for 5 users in the system

affectedUsers

number · required

Number of users whose 2FA was disabled

Example: 5

AuditAction

string · enum

Enum values:

DEVICE_TOGGLE

SCHEDULE_SET

SCHEDULE_EDIT

SCHEDULE_DELETE

LOGOUT

LOGIN_2FA

AuditOutcome

string · enum

Enum values:

SUCCESS

FAILURE

AuditTargetType

string · enum

Enum values:

DEVICE

SCHEDULE

ACCOUNT

StatusTriggerSource

string · enum

Enum values:

MANUAL

CLOUD

SCHEDULED

ECOGUARD

WATCHDOG

LWT

UNKNOWN

BOOTUP

Trigger source for device actions

GetAuditLogDto

_id

string · required

Primary ID of the audit log entry

Example: 64b7f1e6f9c9d4e5b8a9f7c3

action

string · enum · required

The action that was performed

Enum values:

DEVICE_TOGGLE

SCHEDULE_SET

SCHEDULE_EDIT

SCHEDULE_DELETE

LOGOUT

LOGIN_2FA

outcome

string · enum · required

Whether the action succeeded or failed

Enum values:

SUCCESS

FAILURE

createdAt

string · date-time · required

When the action occurred

Example: 2026-06-07T12:00:00Z

actorId

string

Account that performed the action

Example: 64b7f1e6f9c9d4e5b8a9f7c3

actorName

string

Display name of the acting account (resolved from actorId)

Example: Glenn Quah

actorRole

string · enum

Role of the actor at the time of the action

Enum values:

SUPERADMIN

ADMIN

USER

TENANT

ROOM

systemId

string

System the action was scoped to

Example: 64b7f1e6f9c9d4e5b8a9f7c3

systemName

string

Name of the system the action was scoped to

Example: TEST SYSTEM

targetType

string · enum

Type of resource the action targeted

Enum values:

DEVICE

SCHEDULE

ACCOUNT

targetId

string

ID of the targeted resource

Example: 64b7f1e6f9c9d4e5b8a9f7c3

triggerSource

string · enum

Trigger source for device actions

Enum values:

MANUAL

CLOUD

SCHEDULED

ECOGUARD

WATCHDOG

LWT

UNKNOWN

BOOTUP

metadata

object

Free-form contextual data; shape varies by action

Example: {"statusBefore":"OFF","statusAfter":"ON"}

GetAuditLogsResponseDto

total

number · required

Total count of items matching filters

Example: 150

page

number · min: 1 · required

Current page number

Example: 1

size

number · min: 1 · required

Items per page

Example: 50

totalPages

number · min: 0 · required

Total number of pages

Example: 3

GetAuditLogDto[] · required

Array of audit log entries matching the query parameters

ChatRole

string · enum

Enum values:

system

user

assistant

Role of the message sender

ChatMessageDto

role

string · enum · required

Role of the message sender

Enum values:

system

user

assistant

Example: user

content

string · required

Content of the message

Example: What is Ecovolt?

ChatRequestDto

message

string · required

The user's current message

Example: How do I authenticate with the API?

ChatMessageDto[] · required

Array of previous messages in the conversation (max 30 messages)

Example: [{"role":"user","content":"What is Ecovolt?"},{"role":"assistant","content":"Ecovolt is an energy monitoring platform..."}]

PlugCategoryResponseDto

_id

string · required

Category ID

name

string · required

Unique category key

Example: CHARGER

displayName

string · required

Human-readable display name

Example: Charger

isBuiltIn

boolean · required

Whether this is a built-in category

createdAt

string · date-time · required

Creation timestamp

createdBy

string

Admin who created this category

PlugCategoriesListResponseDto

PlugCategoryResponseDto[] · required

total

number · required

CreatePlugCategoryDto

name

string · required

Unique category key — must be UPPER_SNAKE_CASE

Example: STANDING_DESK

displayName

string · required

Human-readable display name

Example: Standing Desk

UpdatePlugCategoryDto

displayName

string

Human-readable display name

Example: Standing Desk

SurgeConfig

calculatedThresholdKwh

number · required

Auto-calculated threshold (median) in kWh

Example: 15.5

defaultViolationCount

number · required

Default number of violations to trigger flagging

Example: 3

defaultViolationWindow

number · required

Default rolling window in days for violation counting

Example: 7

manualThresholdKwh

number

Manual threshold override in kWh (if provided)

Example: 18

sentinelPowerRangeRules

array[]

Sentinel power range rules for suspected device classification

LocationObject

locationInput

string · required

Location of the Tenant

Example: Punggol East Flyover, Punggol, Singapore 828649

type

string · required

Type of the Tenant

Example: Point

coordinates

number[] · required

Geolocation of the Tenant

Example: [103.7759,1.2966]

Price

monthly

number · required

Price for monthly subscription in cents

Example: 999

quarterly

number · required

Price for quarterly subscription in cents

Example: 2799

yearly

number · required

Price for yearly subscription in cents

Example: 9999

FeatureType

string · enum

Enum values:

ZONE_MANAGEMENT

ROOMS_MANAGEMENT

RELATIONSHIP_MAP

ADMIN_PANEL

TENANT_MANAGEMENT

SMART_PLUGS

AI_FEATURE

HEATMAP

Type of the feature

Feature

_id

string · required

Primary ID of the feature

Example: 64b7f1e6f9c9d4e5b8a9f7c3

name

string · required

Name of the feature

featureType

string · enum · required

Type of the feature

Enum values:

ZONE_MANAGEMENT

ROOMS_MANAGEMENT

RELATIONSHIP_MAP

ADMIN_PANEL

TENANT_MANAGEMENT

SMART_PLUGS

AI_FEATURE

HEATMAP

description

string · required

Description of the feature

Example: Tenant Management of the system

createdAt

string · date-time · required

Indicates the creation time of the feature

Example: 2026-06-17T06:17:45.237Z

updatedAt

string · date-time · required

Indicates the last update time of the feature

Example: 2026-06-17T06:17:45.237Z

SubscriptionTier

_id

string · required

The unique identifier of the subscription tier

Example: 64b7f1e6f9c9d4e5b8a9f7c3

name

string · required

The name of the subscription tier

Example: Premium

description

string · required

The description of the subscription tier

Example: Access to all premium features

object · required

The price of the subscription tier

Example: {"monthly":9.99,"quarterly":24.99,"yearly":99.99}

Feature[] · required

The features included in the subscription tier

createdAt

string · date-time · required

The date when the subscription tier was created

Example: 2023-08-01T12:00:00Z

updatedAt

string · date-time · required

The date when the subscription tier was last updated

Example: 2023-08-01T12:00:00Z

isDeleted

boolean · required

Indicates whether the subscription tier is deleted

Example: false

Default: false

SystemPermission

Feature[] · required

Array of features that are currently enabled for this system

Example: ["64b7f1e6f9c9d4e5b8a9f7c1","64b7f1e6f9c9d4e5b8a9f7c2"]

object

Subscription tier that defines available features for the system

Example: 64b7f1e6f9c9d4e5b8a9f7c3

updatedAt

string · date-time

Timestamp when the permission settings were last updated

Example: 2026-06-17T06:17:45.239Z

expiryDate

string · date-time

Optional expiry date for the current permission settings

Example: 2027-06-17T06:17:45.239Z

ScheduleExclusionType

string · enum

Enum values:

HOLIDAY

CUSTOM

Type of exclusion

CountryCode

string · enum

Enum values:

ISO country code (for holidays from API)

ExclusionMode

string · enum

Enum values:

FULL

TIMED

FULL: skip all schedules for the day. TIMED: skip recurring schedules but run devices within timeStart–timeEnd.

ScheduleExclusion

date

string · required

ISO date format (YYYY-MM-DD)

Example: 2025-01-01

name

string · required

Name of the exclusion day

Example: New Year's Day

type

string · enum · required

Type of exclusion

Enum values:

HOLIDAY

CUSTOM

Example: HOLIDAY

mode

string · enum · required

FULL: skip all schedules for the day. TIMED: skip recurring schedules but run devices within timeStart–timeEnd.

Enum values:

FULL

TIMED

Example: FULL

countryCode

string · enum

ISO country code (for holidays from API)

Enum values:

Example: SG

timeStart

string

Time (HH:mm) when devices turn ON. Only set when mode is TIMED.

Example: 13:00

timeEnd

string

Time (HH:mm) when devices turn OFF. Only set when mode is TIMED.

Example: 18:00

SystemTimezone

string · enum

Enum values:

Asia/Singapore

Asia/Manila

Asia/Kuala_Lumpur

Asia/Jakarta

IANA timezone identifier for the system location. Used for scheduling and public holiday calculations.

EntityLabelPairDto

singular

string · required

Singular form of the label

Example: Floor

plural

string · required

Plural form of the label

Example: Floors

SystemEntityLabelsDto

object

Custom label for the zone entity

object

Custom label for the tenant entity

object

Custom label for the room entity

System

_id

string · required

Primary ID of the system

Example: 64b7f1e6f9c9d4e5b8a9f7c3

systemName

string · required

Name of the system

Example: National University of Singapore

maxMissedHeartbeats

number · required

Maximum number of missed heartbeats before the plug is considered offline (1 heart beat = 1 minute)

Example: 3

watchDogTimerRuleName

string · required

Name of the Watch Dog Timer Rule for the system

Example: watchDogTimerRuleName

inActiveDevicesCronJobRuleName

string · required

Name of the Inactive Devices Cron Job Rule for the system

Example: inActiveDevicesCronJobRuleName

remarks

string · required

Remarks for the system

Example: Pilot program for energy monitoring

startPilotDate

string · date-time · required

Start date of the pilot program

Example: 2024-01-01T00:00:00.000Z

endPilotDate

string · date-time · required

End date of the pilot program

Example: 2024-12-31T23:59:59.999Z

realTimeToggleOn

boolean · required

Real Time Toggle Status for the system

heartBeatInterval

number · required

Heart Beat Interval for the system

object · required

Locations of the Tenant

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

createdAdmin

string · required

Admin which created the system (ObjectId reference)

Example: 64b7f1e6f9c9d4e5b8a9f7c3

systemEnergyReport

string · required

System Report

Example: 64b7f1e6f9c9d4e5b8a9f7c3

admins

string[] · required

System Admins of the system (ObjectId references)

Example: ["64b7f1e6f9c9d4e5b8a9f7c3"]

tenants

string[] · required

Tenants of the system (ObjectId references)

Example: ["64b7f1e6f9c9d4e5b8a9f7c3"]

devices

string[] · required

All IoT devices in the System (ObjectId references — Plugs, MCBs, Environment sensors, etc.)

Example: ["64b7f1e6f9c9d4e5b8a9f7c3"]

distributionBoxes

string[] · required

All distribution boxes in the System (ObjectId references)

Example: ["64b7f1e6f9c9d4e5b8a9f7c3"]

object · required

System permission settings including subscription tier, enabled features, and metadata

countryCode

string · enum · required

ISO 3166-1 alpha-2 country code for the system. Determines which public holidays are available for scheduling.

Enum values:

Example: SG

timezone

string · enum · required

IANA timezone identifier for the system location. Used for scheduling and public holiday calculations.

Enum values:

Asia/Singapore

Asia/Manila

Asia/Kuala_Lumpur

Asia/Jakarta

Example: Asia/Singapore

inactiveDevicesSnapshotEnabled

boolean · required

Whether notifications are sent for the daily inactive devices snapshot for this system. When disabled, snapshots are still saved to the database for historical tracking, but no in-app notifications, emails, or Telegram messages are sent.

Example: true

Default: true

locked

boolean · required

Whether the system is locked. A locked system is flagged by a SUPERADMIN (e.g. for non-payment or suspension). Toggle via PATCH /system/:systemId/lock.

Example: false

Default: false

ScheduleExclusion[]

Dates when recurring schedules will NOT execute

surgeMonitoringScheduleName

string

Name of the surge monitoring daily check scheduled task rule for this system. If present, surge monitoring is enabled. If absent/undefined, monitoring is disabled.

Example: surge_monitoring_64b7f1e6f9c9d4e5b8a9f7c3_prod

surgeMonitoringDigestScheduleName

string

Name of the surge monitoring digest scheduled task rule for this system

Example: surge_digest_64b7f1e6f9c9d4e5b8a9f7c3_prod

object

Surge monitoring configuration by entity type (ROOM, TENANT, USER). Map keys are MonitoringEntityType enum values.

Example: {"ROOM":{"calculatedThresholdKwh":15.5,"manualThresholdKwh":18,"defaultViolationCount":3,"defaultViolationWindow":7}}

notificationChannelConfig

object

Per-notification-group channel configuration. Keys are NotificationGroup values. Controls which delivery channels (email, sms, push) are enabled for each notification group.

Example: {"PLUG_MCB_SURGE":{"email":true},"WATER_METER":{"email":true,"sms":false}}

notificationEmailSubscribers

string[]

List of admin ObjectIds subscribed to receive email/channel notifications for this system.

Example: ["64b7f1e6f9c9d4e5b8a9f7c3"]

telegramGroupChatId

string

Telegram group chat ID for this system. When set, notifications are sent to this Telegram group.

Example: -1001234567890

scheduleAdjustmentConfig

object

Schedule adjustment configuration for this system. Controls automatic schedule adjustments based on user manual override patterns.

Example: {"enabled":true,"autoApplyEnabled":false,"occurrenceThreshold":5,"timeWindowMinutes":30}

object

Custom display labels for entity types (zone, tenant, room). Each entry has a singular and plural form. When absent, the frontend uses default names.

Tenant

_id

string · required

Primary ID of the Tenant

Example: 64b7f1e6f9c9d4e5b8a9f7c3

tenantName

string · required

Name of the Tenant

Example: Faculty of Engineering

remarks

string · required

Remarks for the Plug

object · required

Locations of the Tenant

level

number · required

Level of the Tenant

Example: 7

energyUsage

number · required

Energy Usage of the Tenant (Separated from the Tenants)

Example: 1000

system

string · required

System ID reference

tenantEnergyReport

string · required

Tenant Report

Example: 64b7f1e6f9c9d4e5b8a9f7c3

devices

string[] · required

All IoT devices under the Tenant (ObjectId references — Plugs, MCBs, Environment sensors, etc.)

Example: ["64b7f1e6f9c9d4e5b8a9f7c3"]

distributionBoxes

string[] · required

All distribution boxes under the Tenant (ObjectId references)

Example: ["64b7f1e6f9c9d4e5b8a9f7c3"]

zones

string[] · required

Zones under the Tenant (ObjectId references)

Example: ["64b7f1e6f9c9d4e5b8a9f7c3"]

rooms

string[] · required

List of Rooms assigned to the Tenant (ObjectId references)

Example: ["64b7f1e6f9c9d4e5b8a9f7c3"]

tenantEmail

string

Email of the Admin

Example: glenn@gmail.com

tenantType

string

Tenant type key — must match a valid tenant type for this system

Example: RETAIL

Zone

_id

string · required

Primary ID of the Zone

Example: 64b7f1e6f9c9d4e5b8a9f7c3

name

string · required

Name of the Zone

Example: Glenn Quah Han Rong

email

string · required

Email of the Zone

Example: glenn@gmail.com

remarks

string · required

Remarks for the Zone

zoneEnergyReport

string · required

Zone Energy Report

Example: 64b7f1e6f9c9d4e5b8a9f7c3

tenant

string · required

Tenant ID reference

rooms

string[] · required

List of Rooms assigned to the zone (ObjectId references)

Example: ["64b7f1e6f9c9d4e5b8a9f7c3"]

devices

string[] · required

All IoT devices under the Zone (ObjectId references — Plugs, MCBs, Environment sensors, etc.)

Example: ["64b7f1e6f9c9d4e5b8a9f7c3"]

distributionBoxes

string[] · required

All distribution boxes under the Zone (ObjectId references)

Example: ["64b7f1e6f9c9d4e5b8a9f7c3"]

zoneType

string

Zone type key — must match a valid zone type for this system

Example: LABORATORY

floorPlanKey

string

S3 key for the 2D floor plan image

Example: floor-plans/uuid.png

floorPlanUrl

string

CDN URL for the 2D floor plan image

Example: https://cdn.ecovolt.ai/floor-plans/uuid.png

floorPlan

string

3D floor plan design linked to this zone

Room

_id

string · required

Primary ID of the Room

Example: 64b7f1e6f9c9d4e5b8a9f7c3

name

string · required

Name of the Room

Example: Living Room

remarks

string · required

Remarks for the Room

roomEnergyReport

string · required

Room Energy Report

Example: 64b7f1e6f9c9d4e5b8a9f7c3

devices

string[] · required

All IoT devices in the Room (ObjectId references — Plugs, MCBs, Environment sensors, etc.)

Example: ["64b7f1e6f9c9d4e5b8a9f7c3"]

distributionBoxes

string[] · required

All distribution boxes in the Room (ObjectId references)

Example: ["64b7f1e6f9c9d4e5b8a9f7c3"]

system

string

System ID reference

object

Zone tagged to room

tenant

string

Tenant ID reference

roomType

string

Room type key — must match a valid room type for this system

Example: MEETING_ROOM

squareMeter

number

Floor area of the room in square meters

Example: 25.5

floorPlanKey

string

S3 key for the floor plan image

Example: floor-plans/abc123-def456.png

floorPlanUrl

string

CDN URL for the floor plan image

Example: https://cdn.example.com/floor-plans/abc123-def456.png

Admin

_id

string · required

Primary ID of the Admin

Example: 64b7f1e6f9c9d4e5b8a9f7c3

name

string · required

Name of the Admin

Example: Glenn Quah Han Rong

email

string · required

Email of the Admin

Example: glenn@gmail.com

role

string · required

Role of the Admin (ENUM)

Example: SUPERADMIN

object[] · required

Profile Image of the Admin

systems

string[] · required

Systems available to use for the Admin (ObjectId references)

Example: ["64b7f1e6f9c9d4e5b8a9f7c3"]

approved

boolean · required

Whether the Admin is approved

Example: true

notifications

string[] · required

Notifications associated with the Admin (ObjectId references)

Example: ["64b7f1e6f9c9d4e5b8a9f7c3"]

twoFASecret

string · required

The secret for 2FA setup

Example: secret

enable2FA

boolean · required

Indicates whether 2FA is enabled for the Admin

Example: true

createdAt

string · date-time · required

Date when the Admin was created

Example: 2023-10-01T12:00:00Z

updatedAt

string · date-time · required

Date when the Admin was last updated

Example: 2023-10-01T12:00:00Z

password

string

Password of the Admin

Example: password

pending

boolean

Indicates whether the Admin's invitation is pending

Example: true

associatedRoom

string

Room ID reference

object

Reference to the associated Zone

associatedTenant

string

Tenant ID reference

CreateSystemDto

systemName

string · required

Name of the system. Typically represents an organization, building, or facility using the Ecovolt platform.

Example: National University of Singapore

maxMissedHeartbeats

number · required

Maximum number of consecutive missed heartbeats before a plug is marked as offline. Used for monitoring plug connectivity.

Example: 3

realTimeToggleOn

boolean · required

Controls whether plugs in this system should send real-time energy data. When enabled, increases data transmission frequency.

Example: true

heartBeatInterval

number · required

Interval in minutes between heartbeat signals from plugs. Determines how frequently plugs report their online status.

Example: 3

object · required

Geographic location details of the system. Includes address, city, country, and coordinates for mapping purposes.

costPerKWh

number · required

Initial cost per kilowatt-hour (kWh) in cents for this system. This will be used to create the first tariff rate period. Example: 30.65 cents = $0.3065 per kWh.

Example: 30.65

countryCode

string · enum · required

ISO 3166-1 alpha-2 country code for the system. Determines which public holidays are available for scheduling.

Enum values:

Example: SG

timezone

string · enum · required

System timezone used for scheduling and public holiday calculations. Should match the country code.

Enum values:

Asia/Singapore

Asia/Manila

Asia/Kuala_Lumpur

Asia/Jakarta

Example: Asia/Singapore

admin

string

Admin ID reference

subscriptionTier

string

Unique identifier of the subscription tier to assign to this system. Determines available features and usage limits.

Example: 64b7f1e6f9c9d4e5b8a9f7c1

remarks

string

Additional notes or comments about the system. Useful for documenting special configurations or pilot program details.

Example: Pilot program for energy monitoring in campus buildings

startPilotDate

string · date-time

Start date of the pilot program for this system. Used for tracking trial periods and generating time-based reports.

Example: 2024-01-01T00:00:00.000Z

endPilotDate

string · date-time

End date of the pilot program for this system. After this date, the system may transition to a permanent subscription.

Example: 2025-12-31T23:59:59.999Z

GetSystemDto

_id

string · required

Unique identifier of the system

Example: 64b7f1e6f9c9d4e5b8a9f7c3

systemName

string · required

Name of the system

Example: National University of Singapore

maxMissedHeartbeats

number · required

Maximum number of missed heartbeats before a plug is considered offline

Example: 3

realTimeToggleOn

boolean · required

Real-time data toggle status for the system

Example: true

heartBeatInterval

number · required

Heartbeat interval in minutes

Example: 5

numberOfAdmins

number · required

Number of admins linked to the system

Example: 3

numberOfDevices

number · required

Number of devices in the system

Example: 150

deviceOnCount

number · required

Number of devices currently in ON status for this system.

Example: 80

deviceOffCount

number · required

Number of devices currently in OFF status for this system.

Example: 50

deviceInactiveCount

number · required

Number of devices currently in INACTIVE status for this system.

Example: 20

object · required

Location details of the system

createdAt

string · date-time · required

When the system was created

updatedAt

string · date-time · required

When the system was last updated

createdAdmin

string

Admin ID reference

GetSystemsDto

systems

string[] · required

Array of GetSystemDto IDs

total

number · required

Total number of systems

page

number · required

Current page number

Example: 1

size

number · required

Number of items per page

Example: 50

totalPages

number · required

Total number of pages

Example: 5

TenantEnergyUsageDto

tenantId

string · required

Unique identifier of the tenant

Example: 64b7f1e6f9c9d4e5b8a9f7c1

tenantName

string · required

Name of the tenant

Example: Faculty of Engineering

energyUsage

number · required

Total energy usage in kilowatt-hours (kWh) for the specified period

Example: 125.45

GetTenantEnergyUsageResponseDto

systemId

string · required

System ID for which tenant energy usage was calculated

Example: 64b7f1e6f9c9d4e5b8a9f7c1

days

number · required

Number of days the energy usage was calculated over

Example: 7

startDate

string · required

Start date of the energy usage period (ISO 8601 format)

Example: 2024-01-15T00:00:00.000Z

endDate

string · required

End date of the energy usage period (ISO 8601 format)

Example: 2024-01-22T00:00:00.000Z

TenantEnergyUsageDto[] · required

List of tenants with their energy usage data

totalTenants

number · required

Total number of tenants found in this system

Example: 5

totalEnergyUsage

number · required

Total energy usage across all tenants in kWh

Example: 547.32

CreateTariffRateDto

costPerKWh

number · min: 0 · required

Cost in cents per kWh

Example: 30.65

effectiveFrom

string · required

Date when this tariff rate becomes effective (ISO 8601 format)

Example: 2024-01-01T00:00:00.000Z

notes

string

Notes or reason for this tariff rate change

Example: Annual rate adjustment for 2024

GetTariffRatePeriodDto

_id

string · required

Tariff rate period ID

Example: 507f1f77bcf86cd799439011

system

string · required

System ID that this tariff rate applies to

Example: 507f1f77bcf86cd799439012

costPerKWh

number · required

Cost in cents per kWh

Example: 30.65

effectiveFrom

string · date-time · required

Date when this tariff rate becomes effective

Example: 2024-01-01T00:00:00.000Z

createdAt

string · date-time · required

Timestamp when this record was created

updatedAt

string · date-time · required

Timestamp when this record was last updated

effectiveTo

string · date-time

Date when this tariff rate expires (null means currently active)

Example: 2024-12-31T23:59:59.999Z

notes

string

Notes or reason for this tariff rate change

Example: Annual rate adjustment for 2024

createdBy

string

Admin who created this tariff rate

Example: 507f1f77bcf86cd799439013

GetTariffRateHistoryDto

GetTariffRatePeriodDto[] · required

Array of tariff rate periods

total

number · required

Total number of tariff rate periods for this system

Example: 10

page

number · required

Current page number (1-indexed)

Example: 1

size

number · required

Number of items per page

Example: 10

UpdateTariffRateDto

costPerKWh

number

Updated tariff rate in cents per kWh

Example: 32.5

effectiveFrom

string

Updated start date for this tariff rate period

Example: 2024-01-01T00:00:00.000Z

effectiveTo

string | null

Updated end date for this tariff rate period (null means currently active)

Example: 2024-12-31T23:59:59.999Z

notes

string

Notes or reason for this tariff rate

Example: Updated: Annual rate adjustment for 2024 (revised)

PublicHolidayResponseDto

date

string · required

name

string · required

countryCode

string · enum · required

ISO country code (for holidays from API)

Enum values:

Example: SG

CustomExclusionEntryDto

name

string · required

Human-readable name for this exclusion

Example: Christmas Day

mode

string · enum · required

FULL: skip all schedules for the day. TIMED: skip recurring schedules but run devices within timeStart–timeEnd.

Enum values:

FULL

TIMED

Example: FULL

date

string

Single date in YYYY-MM-DD format. Cannot be used with startDate/endDate.

Example: 2026-12-25

startDate

string

Range start in YYYY-MM-DD format. Must be used with endDate.

Example: 2026-12-27

endDate

string

Range end in YYYY-MM-DD format. Must be used with startDate.

Example: 2026-12-31

type

string · enum

Exclusion type. Defaults to CUSTOM if omitted.

Enum values:

HOLIDAY

CUSTOM

Example: CUSTOM

countryCode

string

Country code for HOLIDAY entries (e.g. "SG"). Optional.

Example: SG

timeStart

string

Required when mode is TIMED. Time (HH:mm, system timezone) when devices turn ON.

Example: 13:00

timeEnd

string

Required when mode is TIMED. Time (HH:mm, system timezone) when devices turn OFF.

Example: 18:00

BulkAddCustomExclusionsDto

CustomExclusionEntryDto[] · required

List of exclusion entries. Each can be a full-day exclusion or a timed override.

replaceExistingOfType

string · enum

If set, all existing exclusions of this type are removed before the new entries are inserted. Use HOLIDAY to sync public holidays without accumulating stale entries.

Enum values:

HOLIDAY

CUSTOM

Example: HOLIDAY

BulkAddCustomExclusionsResponseDto

exclusionsReplaced

number · required

Number of existing exclusions removed (when replaceExistingOfType is set)

Example: 15

exclusionsAdded

number · required

Number of new exclusion dates added

Example: 7

duplicatesSkipped

number · required

Number of dates skipped because an exclusion already existed

Example: 1

timedOverridesApplied

number · required

Number of TIMED entries processed

Example: 2

oneTimeTasksCreated

number · required

Total one-time ON+OFF tasks created across all TIMED entries and devices

Example: 48

devicesProcessed

number · required

Number of devices that received one-time tasks (relevant for TIMED entries)

Example: 12

RemoveExclusionResponseDto

message

string · required

removedDate

string · required

UpdateSystemDto

systemName

string · required

Name of the system. Typically represents an organization, building, or facility using the Ecovolt platform.

Example: National University of Singapore

object · required

Geographic location details of the system. Includes address, city, country, and coordinates for mapping purposes.

subscriptionTier

string

Unique identifier of the subscription tier to assign to this system. Determines available features and usage limits.

Example: 64b7f1e6f9c9d4e5b8a9f7c1

remarks

string

Additional notes or comments about the system. Useful for documenting special configurations or pilot program details.

Example: Pilot program for energy monitoring in campus buildings

startPilotDate

string

Start date of the pilot program for this system. Used for tracking trial periods and generating time-based reports.

Example: 2024-01-01T00:00:00.000Z

endPilotDate

string

End date of the pilot program for this system. After this date, the system may transition to a permanent subscription.

Example: 2025-12-31T23:59:59.999Z

countryCode

string · enum

ISO 3166-1 alpha-2 country code for the system. Determines which public holidays are available for scheduling.

Enum values:

Example: SG

timezone

string · enum

System timezone used for scheduling and public holiday calculations. Should match the country code if both are provided.

Enum values:

Asia/Singapore

Asia/Manila

Asia/Kuala_Lumpur

Asia/Jakarta

Example: Asia/Singapore

object

Custom display labels for entity types (zone, tenant, room). Each entry has a singular and plural form. When absent, the frontend falls back to default names.

HeartBeatConfigurationDto

toggleOn

boolean · required

Controls whether plugs in this system should send real-time energy data. When enabled, increases data transmission frequency for live monitoring.

Example: true

heartBeatInterval

number · required

Interval in minutes between heartbeat signals from plugs. Determines how frequently plugs report their online status to the system.

Example: 5

maxMissedHeartbeats

number · required

Maximum number of consecutive missed heartbeats before a plug is marked as offline. The timeout duration equals maxMissedHeartbeats × heartBeatInterval minutes.

Example: 3

LinkAdminToSystemDto

adminId

string · required

Unique identifier of the admin account to be linked to the system. This establishes a management relationship between the admin and the system.

Example: 64b7f1e6f9c9d4e5b8a9f7c1

LinkAdminResponseDto

system

string · required

System ID reference

admin

string · required

Admin ID reference

UnlinkAdminResponseDto

system

string · required

System ID reference

admin

string · required

Admin ID reference

UpdateSystemPermissionDto

subscriptionTier

string

Unique identifier of the subscription tier to assign to this system. Changes the base feature set and limitations.

Example: 64b7f1e6f9c9d4e5b8a9f7c1

featuresEnabled

string[]

Array of feature identifiers to enable for this system. Overrides or extends the default features from the subscription tier.

Example: ["64b7f1e6f9c9d4e5b8a9f7c2","64b7f1e6f9c9d4e5b8a9f7c3"]

expiryDate

string

Expiration date for the system permission. After this date, the system may lose access to certain features or services.

Example: 2025-12-31T23:59:59.999Z

ScheduleAdjustmentConfigDto

enabled

boolean · required

Whether schedule adjustment suggestions are enabled. If false, no suggestions will be generated.

Example: true

autoApplyEnabled

boolean · required

Whether auto-apply is enabled after reaching threshold. If false, always require manual approval. When enabled, patterns are applied on the NEXT manual toggle after threshold.

Example: false

occurrenceThreshold

number · min: 1 · max: 20 · required

Number of occurrences required before auto-apply. Examples: 3 = quick response, 5 = balanced, 10 = conservative

Example: 5

timeWindowMinutes

number · min: 5 · max: 60 · required

Time window in minutes for grouping similar override times. Overrides within this window are considered the same pattern. Examples: 15 = strict, 30 = moderate, 45 = lenient

Example: 30

UpdateScheduleAdjustmentConfigDto

enabled

boolean

Whether schedule adjustment suggestions are enabled

Example: true

autoApplyEnabled

boolean

Whether auto-apply is enabled (applies on next manual toggle after threshold)

Example: false

occurrenceThreshold

number · min: 1 · max: 20

Number of occurrences required before auto-apply (1-20)

Example: 5

timeWindowMinutes

number · min: 5 · max: 60

Time window in minutes for grouping similar override times (5-60)

Example: 30

NotificationChannelSettingsDto

email

boolean

Enable or disable email notifications for this group

sms

boolean

Enable or disable SMS notifications for this group

push

boolean

Enable or disable push notifications for this group

telegram

boolean

Enable or disable Telegram notifications for this group

NotificationChannelConfigResponseDto

NotificationChannelSettingsDto

NotificationGroup

string · enum

Enum values:

PLUG_MCB_SURGE

ENVIRONMENT_SENSOR

WATER_METER

INACTIVE_DEVICES_SNAPSHOT

INACTIVE_DEVICES

SENTINEL_REPORT

DEVICE_HEALTH

AIRCON_CONTROL

The notification group to configure

NotificationGroupChannelEntryDto

group

string · enum · required

The notification group to configure

Enum values:

PLUG_MCB_SURGE

ENVIRONMENT_SENSOR

WATER_METER

INACTIVE_DEVICES_SNAPSHOT

INACTIVE_DEVICES

SENTINEL_REPORT

DEVICE_HEALTH

AIRCON_CONTROL

object · required

Channel settings for this notification group

UpdateNotificationChannelConfigDto

NotificationGroupChannelEntryDto[] · required

Array of notification group + channel settings pairs to update. Existing groups not listed are preserved.

ToggleInactiveSnapshotDto

enabled

boolean · required

Set to true to enable notifications for the daily inactive devices snapshot, false to disable them. Snapshots are always saved to the database regardless of this setting. When disabled, no in-app notifications, emails, or Telegram messages are sent.

Example: true

ToggleInactiveSnapshotResponseDto

systemId

string · required

System ID

Example: 64b7f1e6f9c9d4e5b8a9f7c3

inactiveDevicesSnapshotEnabled

boolean · required

Whether notifications for the daily inactive devices snapshot are now enabled. Snapshots are always saved to the database regardless of this setting.

Example: true

message

string · required

Confirmation message

Example: Inactive devices snapshot enabled for system Acme HQ.

ToggleSystemLockDto

locked

boolean · required

Set to true to lock the system, false to unlock it. Only accessible to SUPERADMIN users.

Example: true

ToggleSystemLockResponseDto

systemId

string · required

System ID

Example: 64b7f1e6f9c9d4e5b8a9f7c3

locked

boolean · required

Whether the system is now locked.

Example: true

message

string · required

Confirmation message

Example: System Acme HQ locked.

NotificationSubscriberDto

_id

string · required

name

string · required

email

string · required

role

string · required

NotificationSubscribersResponseDto

NotificationSubscriberDto[] · required

total

number · required

AddNotificationSubscriberDto

adminId

string · required

Admin ID to add as a notification email subscriber

Example: 64b7f1e6f9c9d4e5b8a9f7c3

UpdateTelegramGroupDto

chatId

string · required

Telegram group chat ID to link to this system. Obtain this by adding the bot to your group and calling getUpdates.

Example: -1001234567890

CronJobType

string · enum

Enum values:

inactive-devices-snapshot

invoice-generation

hourly-update-watchdog

calendar-ics-sync

calendar-webhook-renewal

forecast-retrain

forecast-precompute

Type of cron job to schedule

ScheduleCronJobRequestDto

jobType

string · enum · required

Type of cron job to schedule

Enum values:

inactive-devices-snapshot

invoice-generation

hourly-update-watchdog

calendar-ics-sync

calendar-webhook-renewal

forecast-retrain

forecast-precompute

Example: inactive-devices-snapshot

ScheduleCronJobResponseDto

jobType

string · enum · required

Type of cron job

Enum values:

inactive-devices-snapshot

invoice-generation

hourly-update-watchdog

calendar-ics-sync

calendar-webhook-renewal

forecast-retrain

forecast-precompute

Example: inactive-devices-snapshot

scheduleName

string · required

AWS EventBridge schedule name

Example: inactive_devices_snapshot_daily_production

message

string · required

Success message

Example: Cron job scheduled successfully

DeleteCronJobRequestDto

jobType

string · enum · required

Type of cron job to delete

Enum values:

inactive-devices-snapshot

invoice-generation

hourly-update-watchdog

calendar-ics-sync

calendar-webhook-renewal

forecast-retrain

forecast-precompute

Example: inactive-devices-snapshot

CronJobState

string · enum

Enum values:

ENABLED

DISABLED

Current state of the schedule (if exists)

CronJobStatusResponseDto

jobType

string · enum · required

Type of cron job

Enum values:

inactive-devices-snapshot

invoice-generation

hourly-update-watchdog

calendar-ics-sync

calendar-webhook-renewal

forecast-retrain

forecast-precompute

Example: inactive-devices-snapshot

isEnabled

boolean · required

Whether the cron job is currently scheduled and enabled

Example: true

message

string · required

Status message

Example: Cron job is enabled

scheduleName

string

AWS EventBridge schedule name (if exists)

Example: inactive_devices_snapshot_daily_production

scheduleExpression

string

Schedule expression (if exists)

Example: cron(0 16 * * ? *)

state

string · enum

Current state of the schedule (if exists)

Enum values:

ENABLED

DISABLED

Example: ENABLED

PopulatedTenantDto

_id

string · required

tenantName

string · required

PopulatedUserDto

_id

string · required

name

string · required

email

string · required

PopulatedRoomDto

_id

string · required

name

string · required

PopulatedZoneDto

_id

string · required

name

string · required

DeviceChipModel

string · enum

Enum values:

ESP8266

ESP32C2

ESP32C5

ESP32

ESP32C3

Hardware chip model identifier used in the device

PlugType

string · enum

Enum values:

SOCKET

SOAPBAR

ADAPTER

Hardware type classification of the plug device (PLUG only)

MCBType

string · enum

Enum values:

UNREGISTERED

SWITCH

BUILT_IN

COIL

COIL3P

MCB type (MCB only)

AirconControlMode

string · enum

Enum values:

COOL

HEAT

DRY

FAN

AUTO

Operating mode (AIRCON_CONTROL only)

AirconControlFan

string · enum

Enum values:

LOW

MEDIUM

HIGH

AUTO

Fan speed setting (AIRCON_CONTROL only)

AirconControlSwing

string · enum

Enum values:

OFF

AUTO

Swing setting (AIRCON_CONTROL only)

AirconControlBrand

string · enum

Enum values:

DAIKIN

MITSUBISHI

PANASONIC

SAMSUNG

FUJITSU

TOSHIBA

SHARP

Air conditioner brand (AIRCON_CONTROL only)

GangSwitchState

gangNumber

number · required

Gang number (1-4)

Example: 1

onStatus

string · enum · required

ON/OFF status of this gang switch

Enum values:

OFF

INACTIVE

ERROR

ACTIVE

Example: OFF

label

string

Optional label/name for this gang switch

Example: Living Room Main Light

SwitchType

string · enum

Enum values:

UNREGISTERED

LIGHT

FAN

AIRCON

Type of appliance the switch controls (SMART_SWITCH only)

ScheduledActionType

string · enum

Enum values:

OFF

SET_TEMPERATURE

SET_BRIGHTNESS

SET_MODE

TOGGLE_SMART_SWITCH

Action type to execute at scheduled time

OneTimeScheduleEntry

dateTime

string · date-time · required

Scheduled date and time (ISO 8601 format)

Example: 2023-10-31T06:00:00Z

action

string · enum · required

Action type to execute at scheduled time

Enum values:

OFF

SET_TEMPERATURE

SET_BRIGHTNESS

SET_MODE

TOGGLE_SMART_SWITCH

Example: OFF

actionValue

number

Optional value for actions that require it (e.g., temperature for SET_TEMPERATURE, brightness for SET_BRIGHTNESS)

Example: 24

ruleName

string

EventBridge rule name for tracking and management

DailyScheduleEntry

time

string

Scheduled time in HH:mm format

Example: 06:00

action

string · enum

Action type to execute at scheduled time

Enum values:

OFF

SET_TEMPERATURE

SET_BRIGHTNESS

SET_MODE

TOGGLE_SMART_SWITCH

Example: OFF

actionValue

number

Optional value for actions that require it (e.g., temperature for SET_TEMPERATURE, brightness for SET_BRIGHTNESS)

Example: 24

ruleName

string

EventBridge rule name for tracking and management

ScheduleConfirmationState

string · enum

Enum values:

PENDING

CONFIRMED

Confirmation state of the offline device schedule. PENDING until device confirms receipt via MQTT.

DeviceSchedule

OneTimeScheduleEntry[]

One-time scheduled tasks that execute once and auto-delete after execution

DailyScheduleEntry[]

Recurring schedule entries for Monday

DailyScheduleEntry[]

Recurring schedule entries for Tuesday

DailyScheduleEntry[]

Recurring schedule entries for Wednesday

DailyScheduleEntry[]

Recurring schedule entries for Thursday

DailyScheduleEntry[]

Recurring schedule entries for Friday

DailyScheduleEntry[]

Recurring schedule entries for Saturday

DailyScheduleEntry[]

Recurring schedule entries for Sunday

confirmationState

string · enum

Confirmation state of the offline device schedule. PENDING until device confirms receipt via MQTT.

Enum values:

PENDING

CONFIRMED

DeviceDetailsDto

_id

string · required

Unique device identifier

Example: 64b7f1e6f9c9d4e5b8a9f7c3

deviceName

string · required

Device name

Example: Office Plug 1

macId

string · required

Device MAC address

Example: 1C:69:20:18:0A:BC

deviceType

string · enum · required

Device type

Enum values:

PLUG

MCB

ENV_SENSOR

SMART_SWITCH

AIRCON_CONTROL

WATER_METER

RIDGE

Example: PLUG

onStatus

string · enum · required

Current ON/OFF status

Enum values:

OFF

INACTIVE

ERROR

ACTIVE

Example: ON

system

string · required

System ID

Example: 64b7f1e6f9c9d4e5b8a9f7c1

createdAt

string · date-time · required

Device creation timestamp

Example: 2024-01-15T10:30:00.000Z

updatedAt

string · date-time · required

Last update timestamp

Example: 2024-01-15T14:30:00.000Z

lastSeen

string · date-time · required

Last time the device was seen/reported

Example: 2024-01-15T14:30:00.000Z

deviceStatus

string

Device status

Example: ACTIVE

systemName

string

System name (only populated in SUPERADMIN /devices endpoint)

Example: National University of Singapore

object

Tenant details (populated)

object

User details (populated)

object

Room details (populated)

object

Zone details (populated)

deviceNumber

number

Unique device number for identification

Example: 1

batchNumber

number

Manufacturing batch number for tracking production groups

Example: 1

remarks

string

Additional remarks or notes about the device

Example: Located near the window

location

string

Physical location or address where the device is installed

Example: Room 101, Building A

chipModel

string · enum

Hardware chip model identifier used in the device

Enum values:

ESP8266

ESP32C2

ESP32C5

ESP32

ESP32C3

Example: ESP32C2

versionNumber

string

Firmware version number currently running on the device

Example: 1.0.0

ssid

string

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

Example: IoT-Network-5G

isLocked

boolean

Locked status of the device

Example: false

inactivityNotificationEnabled

boolean

Whether inactivity notifications are enabled for this device

Example: false

deviceModel

string

Model name or identifier of the device connected to this plug (PLUG only)

Example: Dell XPS 15

deviceBrand

string

Brand or manufacturer of the device connected to this plug (PLUG only)

Example: Dell

plugCategory

string

Category classification for the connected device type (PLUG only). See GET /plug-category for valid values.

Example: CHARGER

plugType

string · enum

Hardware type classification of the plug device (PLUG only)

Enum values:

SOCKET

SOAPBAR

ADAPTER

Example: ADAPTER

ecoguardPlug

string

Ecoguard power-saving configuration settings reference ID (PLUG only)

Example: 64b7f1e6f9c9d4e5b8a9f7c6

realTimePower

number

Real-time power consumption in watts (PLUG only)

Example: 500

realTimeCurrent

number

Real-time current in amperes (PLUG only)

Example: 2.5

realTimeVoltage

number

Real-time voltage (PLUG only)

Example: 230

powerFactor

number

Power factor (PLUG only)

Example: 0.95

totalEnergyUsage

number

Total energy usage in watt-hours (PLUG only)

Example: 125000

ecoguardWatts

number

Ecoguard power threshold in watts (PLUG only)

Example: 100

ecoguardMinutes

number

Ecoguard time threshold in minutes (PLUG only)

Example: 30

ratedCurrent

number

Rated current in amperes (MCB only)

Example: 32

mcbType

string · enum

MCB type (MCB only)

Enum values:

UNREGISTERED

SWITCH

BUILT_IN

COIL

COIL3P

Example: BUILT_IN

tripStatus

boolean

Trip status - whether the MCB has tripped (MCB only)

Example: false

distributionBox

string

Distribution box ID (MCB only)

Example: 64b7f1e6f9c9d4e5b8a9f7d2

position

number

Position in distribution box (MCB only)

Example: 1

temperature

number

Set temperature in Celsius (AIRCON_CONTROL only)

Example: 24

mode

string · enum

Operating mode (AIRCON_CONTROL only)

Enum values:

COOL

HEAT

DRY

FAN

AUTO

Example: COOL

fan

string · enum

Fan speed setting (AIRCON_CONTROL only)

Enum values:

LOW

MEDIUM

HIGH

AUTO

Example: AUTO

swing

string · enum

Swing setting (AIRCON_CONTROL only)

Enum values:

OFF

AUTO

Example: OFF

brand

string · enum

Air conditioner brand (AIRCON_CONTROL only)

Enum values:

DAIKIN

MITSUBISHI

PANASONIC

SAMSUNG

FUJITSU

TOSHIBA

SHARP

Example: DAIKIN

isIRRemote

boolean

Whether this device uses IR remote control (AIRCON_CONTROL only)

Example: true

numberOfGangs

number · min: 1 · max: 4

Number of gangs/buttons on the switch (SMART_SWITCH only)

Example: 2

GangSwitchState[]

Individual gang switch states with ON/OFF status (SMART_SWITCH only)

switchType

string · enum

Type of appliance the switch controls (SMART_SWITCH only)

Enum values:

UNREGISTERED

LIGHT

FAN

AIRCON

Example: LIGHT

object

Weekly and one-time schedule configuration for this device

sensorData

object

Environmental sensor data (ENV_SENSOR only)

GetDevicesResponseDto

total

number · required

Total count of items matching filters

Example: 150

page

number · min: 1 · required

Current page number

Example: 1

size

number · min: 1 · required

Items per page

Example: 50

totalPages

number · min: 0 · required

Total number of pages

Example: 3

DeviceDetailsDto[] · required

Array of devices with their full details. Each device includes base fields plus type-specific fields based on deviceType.

DeviceHistoryItem

_id

string · required

Unique identifier for the history entry

Example: 507f1f77bcf86cd799439011

onStatus

string · enum · required

Status of the device (ON/OFF)

Enum values:

OFF

INACTIVE

ERROR

ACTIVE

Example: ON

triggerSource

string · enum · required

Source that triggered the status change

Enum values:

MANUAL

CLOUD

SCHEDULED

ECOGUARD

WATCHDOG

LWT

UNKNOWN

BOOTUP

Example: MANUAL

createdAt

string · date-time · required

Timestamp when the status change occurred

Example: 2024-01-15T10:30:00.000Z

temperature

number

Temperature setting (Aircon Control only) - present when device is an aircon control

Example: 24

mode

string · enum

Operation mode (Aircon Control only) - present when device is an aircon control

Enum values:

COOL

HEAT

DRY

FAN

AUTO

Example: COOL

fan

string · enum

Fan speed (Aircon Control only) - present when device is an aircon control

Enum values:

LOW

MEDIUM

HIGH

AUTO

Example: AUTO

swing

string · enum

Swing setting (Aircon Control only) - present when device is an aircon control

Enum values:

OFF

AUTO

Example: OFF

brand

string · enum

Brand of AC (Aircon Control only) - present when device is an aircon control

Enum values:

DAIKIN

MITSUBISHI

PANASONIC

SAMSUNG

FUJITSU

TOSHIBA

SHARP

Example: DAIKIN

GangSwitchState[]

Gang switch states (Smart Switch only) - present when device is a smart switch, shows the state of each gang at the time of this history entry

Example: [{"gangNumber":1,"onStatus":"ON","label":"Main Light"},{"gangNumber":2,"onStatus":"OFF","label":"Accent Light"}]

GetDeviceHistoryDto

DeviceHistoryItem[] · required

Array of device history entries

total

number · required

Total number of history entries

Example: 100

MultipleDevicesConfigurationDto

deviceType

string · enum · required

Type of devices to configure

Enum values:

PLUG

MCB

ENV_SENSOR

SMART_SWITCH

AIRCON_CONTROL

WATER_METER

RIDGE

Example: PLUG

deviceIds

string[] · required

Array of unique device identifiers from IoT devices to configure in batch

Example: ["1092384701928347","1092384701928348"]

ssid

string

Network SSID (Wi-Fi name) to configure for all selected devices

Example: EcovoltHotspot

password

string

Wi-Fi network password to configure for all selected devices

Example: 123abc456

systemName

string

System name to assign to all selected devices for organizational grouping

Example: NUS

DeviceConfigurationDto

deviceType

string · enum · required

Type of device to configure (PLUG, MCB, ENV_SENSOR). Determines which device will receive the configuration.

Enum values:

PLUG

MCB

ENV_SENSOR

SMART_SWITCH

AIRCON_CONTROL

WATER_METER

RIDGE

Example: PLUG

ssid

string

Network SSID (Wi-Fi name) that the device should connect to for internet access

Example: EcovoltHotspot

password

string

Wi-Fi network password required for the device to authenticate and connect

Example: 123abc456

systemName

string

Name of the system that the device belongs to for organizational grouping

Example: NUS

DeviceErrorType

string · enum

Enum values:

Info

Warning

Error

ErrorLog

_id

string · required

Error log document ID

errorType

string · enum · required

Type or code of the error

Enum values:

Info

Warning

Error

Example: Error

errorTitle

string · required

Type or code of the error

errorMessage

string · required

Detailed error message

createdAt

string · date-time · required

Date Time of the Creation

Example: 2021-09-01

macId

string · required

Device MAC Address

Example: AA:BB:CC:DD:EE:FF

deviceType

string · enum · required

Type of device

Enum values:

PLUG

MCB

ENV_SENSOR

SMART_SWITCH

AIRCON_CONTROL

WATER_METER

RIDGE

Example: PLUG

deviceId

string · required

Device ID

Example: 60f7c0b5b4d1c826d8f0e6b7

systemId

string · required

Tagged System

GetErrorHistoryDto

ErrorLog[] · required

Array of error log records for devices matching the query

total

number · required

Total count of error logs available for pagination purposes

Example: 25

CreateWhiteListedDevicesDto

macIds

string[] · required

Array of unique MAC address identifiers from IoT devices to add to the whitelist

Example: ["AA:BB:CC:DD:EE:FF","AA:BB:CC:DD:EE:FE"]

deviceType

string · enum · required

Type of device

Enum values:

PLUG

MCB

ENV_SENSOR

SMART_SWITCH

AIRCON_CONTROL

WATER_METER

RIDGE

Example: PLUG

batchNumber

number · required

Manufacturing batch number for tracking device production groups and quality control

Example: 1

chipModel

string · enum · required

Hardware chip model identifier used in the devices (e.g., ESP32C2, ESP8266)

Enum values:

ESP8266

ESP32C2

ESP32C5

ESP32

ESP32C3

Example: ESP32C2

versionNumber

string · required

Firmware version number installed on the devices in semantic versioning format

Example: 1.0.0

WhiteList

_id

string · required

Primary ID of the MacId

Example: 64b7f1e6f9c9d4e5b8a9f7c3

macId

string · required

Mac ID of the device (from IoT device)

Example: AA:BB:CC:DD:EE:FF

deviceType

string · enum · required

Type of device

Enum values:

PLUG

MCB

ENV_SENSOR

SMART_SWITCH

AIRCON_CONTROL

WATER_METER

RIDGE

Example: PLUG

batchNumber

number · required

Batch Number of the device

Example: 2

chipModel

string · enum · required

Chip Model of the device

Enum values:

ESP8266

ESP32C2

ESP32C5

ESP32

ESP32C3

Example: ESP32C2

versionNumber

string · required

Version number of the device

Example: 1.0.0

deviceNumber

number · required

Auto-incremented Device Number for whitelisted devices

Example: 1

adminCreated

string · required

Name of the admin who created the whitelist entry

Example: Glenn

createdAt

string · date-time · required

Date Time of the Creation

Example: 2021-09-01

GetWhitelistedDevicesDto

WhiteList[] · required

Array of devices that are approved and registered in the whitelist

total

number · required

Total count of whitelisted devices for pagination and tracking

Example: 200

GetIsDeviceWhiteListedDto

isWhiteListed

boolean · required

Boolean flag indicating whether the device is approved and present in the whitelist

Example: true

BulkRemoveWhitelistDto

ids

string[] · required

Array of whitelist entry IDs to remove

Example: ["507f1f77bcf86cd799439011","507f1f77bcf86cd799439012"]

ManufacturerRegisterDeviceDto

macId

string · required

MAC address of the device

Example: AA:BB:CC:DD:EE:FF

deviceType

string · enum · required

Type of device being registered

Enum values:

PLUG

MCB

ENV_SENSOR

SMART_SWITCH

AIRCON_CONTROL

WATER_METER

RIDGE

Example: PLUG

batchNumber

number · required

Manufacturing batch number

Example: 1

chipModel

string · enum · required

Hardware chip model of the device

Enum values:

ESP8266

ESP32C2

ESP32C5

ESP32

ESP32C3

Example: ESP32C2

versionNumber

string · required

Firmware version number installed on the device

Example: 1.0.0

adminCreated

string

Name of the manufacturer or person registering the device. Defaults to "Manufacturer" if not provided.

Example: Ah Kow Manufacturing

ManufacturerDeviceResponseDto

macId

string · required

MAC address of the device

Example: AA:BB:CC:DD:EE:FF

deviceNumber

number · required

Auto-assigned device number for this device

Example: 42

alreadyExisted

boolean · required

True if the MAC was already registered and this was a lookup, false if newly registered

Example: false

ManufacturerPlugStatusDto

_id

string · required

Device ID

Example: 64b7f1e6f9c9d4e5b8a9f7c3

macId

string · required

MAC address of the device

Example: AA:BB:CC:DD:EE:FF

deviceNumber

number · required

Unique device number for identification

Example: 42

onStatus

string · enum · required

Current on/off status of the device

Enum values:

OFF

INACTIVE

ERROR

ACTIVE

Example: ON

ManufacturerSystemPlugsResponseDto

ManufacturerPlugStatusDto[] · required

List of plug devices in the system

total

number · required

Total number of plug devices

Example: 10

MultipleDevicesChangeSystemDto

deviceIds

string[] · required

Array of unique device identifiers (plugs or MCBs) to reassign to a different system

Example: ["1092384701928347","1092384701928348"]

newSystemId

string · required

Unique identifier of the target system to reassign all selected devices to

Example: 64b7f1e6f9c9d4e5b8a9f7c3

UpdateMultipleDevicesRelationshipsDto

deviceIds

string[] · required

Array of unique device identifiers to update relationships for

Example: ["64b7f1e6f9c9d4e5b8a9f7c1","64b7f1e6f9c9d4e5b8a9f7c2"]

tenantId

string | null

Unique identifier of the tenant to assign the devices to. Pass null to remove the tenant relationship.

Example: 64b7f1e6f9c9d4e5b8a9f7c5

zoneId

string | null

Unique identifier of the zone to assign ownership of the devices to. Pass null to remove the zone relationship.

Example: 64b7f1e6f9c9d4e5b8a9f7c3

roomId

string | null

Unique identifier of the room to assign the devices to. Pass null to remove the room relationship.

Example: 64b7f1e6f9c9d4e5b8a9f7c4

UpdateDeviceBaseDto

deviceName

string

Name of the device

Example: Living Room Light

location

string

Physical location of the device

Example: Block 123, Unit 01-23

remarks

string

Additional remarks or notes about the device

Example: Handle with care - critical equipment

tenantId

string

Tenant ID to associate the device with

Example: 64b7f1e6f9c9d4e5b8a9f7c3

zoneId

string

Zone ID to associate the device with

Example: 64b7f1e6f9c9d4e5b8a9f7c4

roomId

string

Room ID to associate the device with

Example: 64b7f1e6f9c9d4e5b8a9f7c5

isLocked

boolean

Whether the device is locked. When locked, the device cannot be toggled ON/OFF.

Example: false

isSpare

boolean

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

Example: false

DeviceUpdateItem

deviceId

string · required

MongoDB ID of the device to update

Example: 64b7f1e6f9c9d4e5b8a9f7c3

object · required

Fields to update on the device

BulkUpdateDevicesDto

DeviceUpdateItem[] · required

Array of device update operations to perform in a single batch request

Example: [{"deviceId":"64b7f1e6f9c9d4e5b8a9f7c3","data":{"deviceName":"Main Switch","location":"Lobby","remarks":"Critical"}}]

UpdateDevicesLockStatusDto

deviceIds

string[] · required

Array of device IDs to lock or unlock

Example: ["64b7f1e6f9c9d4e5b8a9f7c3","64b7f1e6f9c9d4e5b8a9f7c4"]

isLocked

boolean · required

Lock status to set. True to lock devices, false to unlock.

Example: true

FailedDeviceLockUpdateDto

deviceId

string · required

Device ID that failed to update

Example: 64b7f1e6f9c9d4e5b8a9f7c3

reason

string · required

Reason for failure

Example: Device not found

UpdateDevicesLockStatusResponseDto

successCount

number · required

Number of devices successfully updated

Example: 5

failedCount

number · required

Number of devices that failed to update

Example: 1

successfulDeviceIds

string[] · required

List of device IDs that were successfully updated

Example: ["64b7f1e6f9c9d4e5b8a9f7c3","64b7f1e6f9c9d4e5b8a9f7c4"]

FailedDeviceLockUpdateDto[] · required

List of devices that failed to update with reasons

UpdateDevicesSpareStatusDto

deviceIds

string[] · required

Array of device IDs to mark as spare or non-spare

Example: ["64b7f1e6f9c9d4e5b8a9f7c3","64b7f1e6f9c9d4e5b8a9f7c4"]

isSpare

boolean · required

Spare status to set. True to mark as spare, false to unmark.

Example: true

UpdateDevicesRelationshipTenantDto

deviceIds

string[] · required

Array of unique device identifiers to update relationships for

Example: ["64b7f1e6f9c9d4e5b8a9f7c1","64b7f1e6f9c9d4e5b8a9f7c2"]

zoneId

string

Unique identifier of the zone to assign ownership of the devices to within the tenant

Example: 64b7f1e6f9c9d4e5b8a9f7c3

roomId

string

Unique identifier of the room to assign the devices to for location tracking

Example: 64b7f1e6f9c9d4e5b8a9f7c4

UpdateDevicesRelationshipZoneDto

deviceIds

string[] · required

Array of unique device identifiers to update room assignment for

Example: ["64b7f1e6f9c9d4e5b8a9f7c2","64b7f1e6f9c9d4e5b8a9f7c2"]

roomId

string

Unique identifier of the room to assign the devices to for location tracking

Example: 64b7f1e6f9c9d4e5b8a9f7c4

MultipleDevicesResetSystemVariablesDto

systemName

string · required

Name of the system containing the devices whose variables should be reset

Example: NUS

deviceType

string · enum · required

Type of device to reset (PLUG, MCB, ENV_SENSOR). Determines which devices will receive the reset command.

Enum values:

PLUG

MCB

ENV_SENSOR

SMART_SWITCH

AIRCON_CONTROL

WATER_METER

RIDGE

Example: PLUG

deviceIds

string[]

Array of unique device identifiers (MAC IDs) to reset, or empty to reset all devices in the system

Example: ["1092384701928347","1092384701928348"]

MultipleDevicesCalibrationDto

systemName

string · required

Name of the system containing the devices to calibrate for batch processing

Example: NUS

deviceType

string · enum · required

Type of device to calibrate (PLUG, MCB, ENV_SENSOR). Determines which devices will receive calibration data.

Enum values:

PLUG

MCB

ENV_SENSOR

SMART_SWITCH

AIRCON_CONTROL

WATER_METER

RIDGE

Example: PLUG

voltageMultiplier

number · required

Calibration multiplier to adjust voltage sensor readings for accuracy correction

Example: 1.5

voltageOffset

number · required

Calibration offset value in volts to adjust voltage sensor baseline readings

Example: 0.5

currentMultiplier

number · required

Calibration multiplier to adjust current sensor readings for accuracy correction

Example: 1.2

currentOffset

number · required

Calibration offset value in amperes to adjust current sensor baseline readings

Example: 0.2

powerMultiplier

number · required

Calibration multiplier to adjust power measurement calculations for accuracy

Example: 1.1

powerOffset

number · required

Calibration offset value in watts to adjust power measurement baseline

Example: 0.1

deviceIds

string[]

Array of unique device identifiers to apply calibration settings to, or empty to calibrate all devices in the system

Example: ["64b7f1e6f9c9d4e5b8a9f7c1","64b7f1e6f9c9d4e5b8a9f7c2"]

InactiveDeviceDto

_id

string · required

Device document ID

Example: 507f1f77bcf86cd799439011

macId

string · required

Device MAC ID (unique identifier)

Example: 28:56:2F:0E:58:C8

deviceNumber

number · required

Device number identifier

Example: 1

deviceName

string · required

Device display name

Example: Conference Room AC

deviceType

string · enum · required

Type of device

Enum values:

PLUG

MCB

ENV_SENSOR

SMART_SWITCH

AIRCON_CONTROL

WATER_METER

RIDGE

Example: PLUG

lastSeen

string · date-time · required

Last time the device sent a heartbeat (last seen timestamp)

Example: 2024-10-15T08:30:00.000Z

inactiveDuration

number · required

Duration the device has been inactive in milliseconds

Example: 172800000

inactiveDurationFormatted

string · required

Duration the device has been inactive in human-readable format

Example: 2 days, 3 hours

tenantId

string

Tenant ID that owns this device

Example: 507f1f77bcf86cd799439011

tenantName

string

Tenant name that owns this device

Example: Building A - Floor 3

GetInactiveDevicesDto

InactiveDeviceDto[] · required

Array of inactive devices with their details

total

number · required

Total count of inactive devices found

Example: 15

retrievedAt

string · date-time · required

Timestamp when this data was retrieved

Example: 2024-10-17T14:45:00.000Z

SaveInactiveSnapshotResponseDto

snapshotId

string · required

Snapshot document ID

Example: 507f1f77bcf86cd799439011

systemId

string · required

System ID this snapshot belongs to

Example: 507f1f77bcf86cd799439011

totalInactiveDevices

number · required

Number of inactive devices captured in this snapshot

Example: 5

snapshotDate

string · date-time · required

Timestamp when the snapshot was taken

Example: 2024-10-22T00:00:00.000Z

message

string · required

Message confirming the snapshot was saved

Example: Inactive device snapshot saved successfully

InactiveDeviceSnapshot

_id

string · required

Snapshot document ID

system

string · required

System ID reference

InactiveDeviceDto[] · required

Array of inactive devices with their details

total

number · required

Total count of inactive devices

retrievedAt

string · date-time · required

Timestamp when this data was retrieved

createdAt

string · date-time · required

Timestamp when this snapshot was created

updatedAt

string · date-time · required

Timestamp when this snapshot was last updated

referenceDate

string · date-time

Optional reference date used for duration calculation

GetInactiveSnapshotsDto

InactiveDeviceSnapshot[] · required

Array of inactive device snapshots

total

number · required

Total count of snapshots found

Example: 10

HierarchyType

string · enum

Enum values:

SYSTEM

TENANT

USER

ROOM

DeviceCountDto

deviceCount

number · required

Total number of devices registered in the system across all statuses

Example: 4

deviceOnCount

number · required

Number of devices currently in ON status and actively consuming power

Example: 2

deviceOffCount

number · required

Number of devices currently in OFF status and not consuming power

Example: 1

deviceInactiveCount

number · required

Number of devices marked as inactive or not communicating with the system

Example: 1

deviceSpareCount

number · required

Number of spare devices (excluded from total, on, off, and inactive counts)

Example: 1

DeviceTypeBreakdownDto

PLUG

number · required

Number of PLUG devices in the system

Example: 15

MCB

number · required

Number of MCB (Miniature Circuit Breaker) devices in the system

Example: 8

ENV_SENSOR

number · required

Number of ENV_SENSOR (Environmental Sensor) devices in the system

Example: 3

SMART_SWITCH

number · required

Number of SMART_SWITCH devices in the system

Example: 5

AIRCON_CONTROL

number · required

Number of AIRCON_CONTROL (Air Conditioning Controller) devices in the system

Example: 4

WATER_METER

number · required

Number of WATER_METER devices in the system

Example: 2

total

number · required

Total number of devices in the system

Example: 37

ChangeDeviceSystemDto

newSystemId

string · required

Unique identifier of the system to reassign the device to for organizational management

Example: 64b7f1e6f9c9d4e5b8a9f7c3

ToggleDeviceStatusDto

deviceId

string · required

Unique identifier of the device to be toggled

Example: 64b7f1e6f9c9d4e5b8a9f7c3

onStatus

string · enum

Desired power state. Use ON to turn the device on (all gangs for SmartSwitch), or OFF to turn it off (all gangs for SmartSwitch).

Enum values:

OFF

INACTIVE

ERROR

ACTIVE

Example: ON

Device

_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

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

BulkToggleDeviceDto

deviceIds

string[] · required

Array of device IDs to toggle

Example: ["64b7f1e6f9c9d4e5b8a9f7c3","64b7f1e6f9c9d4e5b8a9f7c4"]

onStatus

string · enum

Desired power state for all devices. Use ON to turn all devices on (all gangs for SmartSwitch), or OFF to turn all devices off (all gangs for SmartSwitch).

Enum values:

OFF

INACTIVE

ERROR

ACTIVE

Example: ON

BulkDeleteDeviceDto

deviceIds

string[] · required

Array of device IDs to delete

Example: ["507f1f77bcf86cd799439011","507f1f77bcf86cd799439012"]

ManualBlacklistDto

blacklist

boolean · required

Whether to blacklist (true) or remove blacklist (false)

Example: true

BulkManualBlacklistDto

deviceIds

string[] · required

Array of device IDs to blacklist/unblacklist

Example: ["507f1f77bcf86cd799439011","507f1f77bcf86cd799439012"]

blacklist

boolean · required

Whether to blacklist (true) or remove blacklist (false)

Example: true

EnvironmentType

string · enum

Enum values:

STAGING

PRODUCTION

Environment type to set for the devices. STAGING for staging environment, PRODUCTION for production environment.

ChangeEnvironmentDto

deviceIds

string[] · required

Array of device IDs to change environment for

Example: ["64b7f1e6f9c9d4e5b8a9f7c3","64b7f1e6f9c9d4e5b8a9f7c4"]

setEnvironment

string · enum · required

Environment type to set for the devices. STAGING for staging environment, PRODUCTION for production environment.

Enum values:

STAGING

PRODUCTION

Example: STAGING

BulkUpdateEnergyThresholdsDto

deviceIds

string[] · required

IDs of energy devices (Plugs or MCBs) to update

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

UpdateEnergyDeviceThresholdDto

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

EnergyThresholdBaselineDto

voltageMin

number · required

Minimum voltage reading (V)

voltageMax

number · required

Maximum voltage reading (V)

currentMin

number · required

Minimum current reading (A)

currentMax

number · required

Maximum current reading (A)

powerMin

number · required

Minimum power reading (W)

powerMax

number · required

Maximum power reading (W)

EnvironmentSensorThresholdBaselineDto

temperatureMin

number

Minimum temperature reading (°C)

temperatureMax

number

Maximum temperature reading (°C)

carbonDioxideMin

number

Minimum CO2 reading (ppm)

carbonDioxideMax

number

Maximum CO2 reading (ppm)

luxMin

number

Minimum light level reading (lx)

luxMax

number

Maximum light level reading (lx)

formaldehydeMin

number

Minimum formaldehyde reading (ppm)

formaldehydeMax

number

Maximum formaldehyde reading (ppm)

humidityMin

number

Minimum humidity (%)

humidityMax

number

Maximum humidity (%)

fineParticulateMatterMin

number

Minimum PM2.5 reading (µg/m³)

fineParticulateMatterMax

number

Maximum PM2.5 reading (µg/m³)

coarseParticulateMatterMin

number

Minimum PM10 reading (µg/m³)

coarseParticulateMatterMax

number

Maximum PM10 reading (µg/m³)

totalVolatileOrganicCompoundsMin

number

Minimum TVOC reading (ppm)

totalVolatileOrganicCompoundsMax

number

Maximum TVOC reading (ppm)

soundLevelMin

number

Minimum sound level (dB)

soundLevelMax

number

Maximum sound level (dB)

WaterMeterThresholdBaselineDto

flowRateMin

number

Minimum flow rate (L/min)

flowRateMax

number

Maximum flow rate (L/min)

pressureMin

number

Minimum pressure (bar)

pressureMax

number

Maximum pressure (bar)

temperatureMin

number

Minimum temperature (°C)

temperatureMax

number

Maximum temperature (°C)

ThresholdBaselineResponseDto

deviceId

string · required

Device ID

deviceType

string · required

Device type

periodStart

string · date-time · required

Start date of the baseline period

periodEnd

string · date-time · required

End date of the baseline period

dataPointCount

number · required

Number of data points used to calculate the baseline

message

string

Warning message when insufficient data (< 14 days) was available for the baseline calculation

Example: Only 3 days of data available. Baseline calculated from limited data.

object

Energy device baseline (Plug/MCB)

object

Environment sensor baseline

object

Water meter baseline

BulkThresholdBaselineRequestDto

deviceIds

string[] · required

IDs of devices to calculate threshold baselines for

Example: ["64b7f1e6f9c9d4e5b8a9f7c3","64b7f1e6f9c9d4e5b8a9f7c4"]

FailedThresholdBaselineDto

deviceId

string · required

Device ID that failed to generate a baseline

Example: 64b7f1e6f9c9d4e5b8a9f7c3

reason

string · required

Reason for failure

Example: Device not found in system

BulkThresholdBaselineResponseDto

successCount

number · required

Number of devices for which baselines were successfully generated

Example: 5

failedCount

number · required

Number of devices for which baseline generation failed

Example: 1

ThresholdBaselineResponseDto[] · required

Successfully generated baselines

FailedThresholdBaselineDto[] · required

Devices that failed baseline generation with reasons

UpdateInactivityNotificationDto

enabled

boolean · required

Enable or disable inactivity notifications for this device

Example: true

ClaimTokenResponseDto

claimToken

string · required

Encrypted claim token for device

Example: a1b2c3d4e5f6...

claimUrl

string · required

Full URL for claiming the device

Example: https://base.ecovolt.ai/claim/a1b2c3d4e5f6...

PrintQrResponseDto

deviceNumber

number · required

Auto-assigned device number for this device

Example: 42

claimUrl

string · required

Full URL for claiming the device — encode this as QR

Example: https://base.ecovolt.ai/claim/a1b2c3d4e5f6...

ClaimDeviceResponseDto

message

string · required

Success message

Example: Device claimed successfully

deviceId

string · required

Device ID

Example: 64b7f1e6f9c9d4e5b8a9f7c3

deviceName

string · required

Device name

Example: Smart Plug 1

deviceNumber

number · required

Device number

Example: 42

deviceType

string · enum · required

Device type

Enum values:

PLUG

MCB

ENV_SENSOR

SMART_SWITCH

AIRCON_CONTROL

WATER_METER

RIDGE

Example: PLUG

systemId

string · required

System ID the device belongs to

Example: 64b7f1e6f9c9d4e5b8a9f7c1

zoneId

string · required

Zone ID the device was assigned to

Example: 64b7f1e6f9c9d4e5b8a9f7c4

zoneName

string · required

Zone name the device was assigned to

Example: Unit 01-01

tenantId

string

Tenant ID the device was assigned to (if any)

Example: 64b7f1e6f9c9d4e5b8a9f7c2

tenantName

string

Tenant name the device was assigned to (if any)

Example: Acme Corp

CreateNotificationDto

title

string · required

Title of the notification

Example: New Notification

message

string · required

Message of the notification

Example: Power outage in your area

system

string · required

Notification for a specific System

type

string · enum · required

Type of the notification

Enum values:

DEVICE_INACTIVITY_ALERT

POWER_SURGE

TEMP_SURGE

TEMP_DROP

INACTIVE_DEVICES_SNAPSHOT

LEAK_DETECTION

USAGE_SURGE

DEVICE_HEALTH_ANOMALY

Example: DEVICE_INACTIVITY_ALERT

recieveType

string · enum · required

Receive type of the notification

Enum values:

SYSTEM

SMS

PUSH

Example: EMAIL

device

string

Notification for a specific Device (optional - if not provided, finds system-level admin)

isSystemLevel

boolean

Whether this is a system-level notification (visible to all admins in the system)

Example: false

Notification

_id

string · required

Primary ID of the Notification

Example: 64b7f1e6f9c9d4e5b8a9f7c3

title

string · required

Title of the Notification

Example: System Maintenance

message

string · required

Message of the Notification

Example: The system will be down for maintenance from 2 AM to 3 AM.

system

string · required

System ID reference

device

string · required

Notification for a specific Device

type

string · enum · required

Type of the Notification (ENUM)

Enum values:

DEVICE_INACTIVITY_ALERT

POWER_SURGE

TEMP_SURGE

TEMP_DROP

INACTIVE_DEVICES_SNAPSHOT

LEAK_DETECTION

USAGE_SURGE

DEVICE_HEALTH_ANOMALY

Example: DEVICE_INACTIVITY_ALERT

recieveType

string · enum · required

Type of the Notification (ENUM)

Enum values:

SYSTEM

SMS

PUSH

Example: EMAIL

isResolved

boolean · required

Status of the Notification

Example: true

isSystemLevel

boolean · required

Whether this is a system-level notification (visible to all admins in the system)

Example: false

createdAt

string · date-time · required

Creation date of the Notification

Example: 2023-08-01T12:00:00Z

updatedAt

string · date-time · required

Last update date of the Notification

Example: 2023-08-01T12:00:00Z

admin

string

Admin ID reference

SearchQueryResultDto

results

array[] · required

Search results

total

number · required

Total number of results

Example: 100

ResolveAllNotificationsResponseDto

resolvedCount

number · required

Number of notifications marked as resolved

Example: 12

BasicEmailNotificationDto

receiverEmail

string · required

Email address of the receiver

Example: user@example.com

subject

string · required

Subject of the email notification

Example: Password Reset Request

content

string · required

Content of the email notification

Example: Please click the link to reset your password.

BusinessOrderDevice

string · enum

Enum values:

office-printer

office-meeting-pod

office-water-dispenser

office-coffee

office-air-purifier

office-desk

office-tv

office-av

Device type identifier

BusinessSelectedDeviceDto

deviceType

string · enum · required

Device type identifier

Enum values:

office-printer

office-meeting-pod

office-water-dispenser

office-coffee

office-air-purifier

office-desk

office-tv

office-av

Example: office-printer

qty

number · min: 1 · required

Number of units of this device

Example: 2

PublicWebEmailNotificationDto

firstName

string · required

first name of the sender

Example: John

lastName

string · required

last name of the sender

Example: Doe

phoneNumber

string · required

phone number of the sender

Example: +1234567890

company

string · required

company name of the sender

Example: Acme Corp

email

string · required

Email address of the sender

Example: user@example.com

message

string · required

Content of the email notification

Example: We are interested in energy solutions for our office.

BusinessSelectedDeviceDto[]

Business devices selected with quantities

NewsletterSubscriberSource

string · enum

Enum values:

landing-page

other

Subscriber source

NewsletterSubscriberDto

email

string · required

Subscriber email address

Example: user@example.com

name

string

Subscriber name

Example: John Doe

subscribedFromSource

string · enum

Subscriber source

Enum values:

landing-page

other

Example: landing-page

NewsletterSubscriberStatus

string · enum

Enum values:

SUBSCRIBED

UNSUBSCRIBED

Status of the newsletter subscriber

NewsletterSubscriberResponseDto

_id

string · required

Unique identifier of the newsletter subscriber

Example: 64a7b2f5c9e77b6f4d8e4a2b

email

string · required

Email of the newsletter subscriber

Example: ecovolt@example.com

status

string · enum · required

Status of the newsletter subscriber

Enum values:

SUBSCRIBED

UNSUBSCRIBED

Example: SUBSCRIBED

name

string

Name of the newsletter subscriber

Example: John Doe

subscribedFromIp

string

IP address from which the user subscribed

Example: 192.168.1.1

subscribedFromSource

string · enum

Source from which the user subscribed

Enum values:

landing-page

other

Example: landing-page

createdAt

string · date-time

Timestamp when the subscriber was created

Example: 2024-07-01T10:00:00Z

updatedAt

string · date-time

Timestamp when the subscriber was last updated

Example: 2024-07-01T10:00:00Z

EmailRecipientsType

string · enum

Enum values:

ALL_SUBSCRIBERS

ADMINS

MANUAL_SELECTION

Type of recipient list for the email campaign

ManualSelectionRecipientType

string · enum

Enum values:

Admin

NewsletterSubscriber

Type of recipient

ManualSelectionRecipientDto

recipientType

string · enum · required

Type of recipient

Enum values:

Admin

NewsletterSubscriber

Example: NewsletterSubscriber

recipientId

string · required

ID of the recipient

Example: 64b8c3d2e1f4a2b3c4d5e6f7

CreateEmailCampaignDto

name

string · required

Name of the email campaign

Example: July 2024 Newsletter Campaign

templateId

string · required

ID of the newsletter template to use for the email campaign

Example: 64a7b2f5c9e77b6f4d8e4a2b

recipientType

string · enum · required

Type of recipient list for the email campaign

Enum values:

ALL_SUBSCRIBERS

ADMINS

MANUAL_SELECTION

Example: ALL_SUBSCRIBERS

subject

string

Subject of the campaign email

Example: Exciting Updates in Our July Newsletter!

ManualSelectionRecipientDto[]

List of manually selected recipients with their types (required if recipientType is MANUAL_SELECTION)

scheduledAt

string

Scheduled send time for the email campaign in ISO 8601 format

Example: 2024-07-01T10:00:00Z

EmailCampaignStatus

string · enum

Enum values:

DRAFT

SCHEDULED

SENDING

SENT

FAILED

CANCELLED

Current status of the email campaign

EmailCampaign

_id

string · required

Unique identifier of the email campaign

Example: 64a7b2f5c9e77b6f4d8e4a2b

name

string · required

Name of the email campaign

Example: July Newsletter Campaign

sourceTemplate

string · required

Reference to the original template used for this email campaign

Example: 64a7b2f5c9e77b6f4d8e4a2b

subject

string · required

Subject of the campaign email

Example: Exciting Updates in Our July Newsletter!

designJson

object · required

Copied JSON from template for campaign-specific email customization

Example: {"body":{"rows":[],"values":{"backgroundColor":"#ffffff","contentWidth":"600px"}}}

renderedHtml

string · required

Rendered HTML content for this email campaign

Example: <html><body><h1>Welcome to our Newsletter</h1></body></html>

plainText

string · required

Plain text version of the email campaign

Example: Welcome to our Newsletter

previewText

string · required

Short text that appears in email preview before opening

Example: This is the preview text for the newsletter email.

recipientType

string · enum · required

Type of recipients for the email campaign

Enum values:

ALL_SUBSCRIBERS

ADMINS

MANUAL_SELECTION

Example: ALL_SUBSCRIBERS

ManualSelectionRecipientDto[] · required

List of manually selected recipients with their types (if recipientType is MANUAL_SELECTION)

status

string · enum · required

Current status of the email campaign

Enum values:

DRAFT

SCHEDULED

SENDING

SENT

FAILED

CANCELLED

Example: DRAFT

scheduledAt

string · date-time · required

Scheduled send time for the email campaign

Example: 2024-08-01T10:00:00Z

scheduleName

string · required

AWS EventBridge Scheduler name for the scheduled campaign send

Example: oneoff_SEND_EMAIL_CAMP_64a7b2f5c9e77b6f4d8e4a2b_1234567890_deve

sentAt

string · date-time · required

Time when the email campaign was sent

Example: 2024-08-01T10:00:00Z

totalRecipients

number · required

Total number of recipients for the email campaign

Example: 1500

errorMessage

string · required

Error message if campaign sending failed

Example: Campaign failed due to SMTP server error.

createdBy

string · required

Admin who created the campaign

Example: 64a7b2f5c9e77b6f4d8e4a2b

updatedBy

string · required

Admin who last updated the campaign

Example: 64a7b2f5c9e77b6f4d8e4a2b

SendEmailCampaignDto

campaignId

string · required

ID of the email campaign to be sent

Example: 60f7c0b5b4d1c826d8f0e6b7

status

string · enum · required

Current status of the email campaign

Enum values:

DRAFT

SCHEDULED

SENDING

SENT

FAILED

CANCELLED

Example: SCHEDULED

message

string · required

Result message after attempting to send the email campaign

Example: Campaign scheduled successfully

totalRecipients

number · required

Total number of recipients for the email campaign

Example: 1500

SendTestEmailRequestDto

testEmail

string · required

Email address to send the test email to

Example: test@example.com

testName

string

Name of the test recipient for personalization

Example: John Doe

GetEmailCampaignsDto

EmailCampaign[] · required

List of email campaigns

total

number · required

Total number of email campaigns

Example: 10

UpdateEmailCampaignDto

name

string

Name of the email campaign

Example: July 2024 Newsletter Campaign - Updated

subject

string

Subject of the campaign email

Example: Exciting Updates in Our July Newsletter!

recipientType

string · enum

Type of recipient list for the email campaign

Enum values:

ALL_SUBSCRIBERS

ADMINS

MANUAL_SELECTION

Example: ALL_SUBSCRIBERS

ManualSelectionRecipientDto[]

List of manually selected recipients with their types (used when recipientType is MANUAL_SELECTION)

designJson

object

Unlayer design JSON for campaign-specific email customization

Example: {"body":{"rows":[],"values":{"backgroundColor":"#ffffff","contentWidth":"600px"}}}

renderedHtml

string

Rendered HTML content of the email campaign

Example: <html><body><h1>Welcome</h1></body></html>

plainText

string

Plain text version of the email campaign

Example: Welcome to our newsletter

previewText

string

Short text that appears in email preview before opening

Example: Check out the latest news and updates!

scheduledAt

string | null

Scheduled send time for the email campaign in ISO 8601 format. Set to null to convert SCHEDULED to DRAFT.

Example: 2024-07-01T10:00:00Z

EmailTemplateDto

name

string · required

Name of the email template

Example: Monthly Newsletter Template

subject

string · required

Subject of the email template

Example: Your Ecovolt Monthly Update!

designJson

object · required

JSON structure of the email template

Example: {"body":{"rows":[],"values":{"backgroundColor":"#ffffff","contentWidth":"600px"}}}

description

string

Description of the email template

Example: A template for our monthly newsletters

previewText

string

Preview text for the email template

Example: Check out the latest news and updates!

renderedHtml

string

Rendered HTML content of the email template

Example: <html><body><h1>Welcome</h1></body></html>

plainText

string

Plain text version of the email template

Example: Welcome to our newsletter

EmailTemplateStatus

string · enum

Enum values:

DRAFT

PUBLISHED

ARCHIVED

Indicates status of the email template

EmailTemplate

_id

string · required

Unique identifier of the email template

Example: 64a7b2f5c9e77b6f4d8e4a2b

name

string · required

Name of the email template

Example: Weekly Update

description

string · required

Description of the email template

Example: Template for the weekly Email updates

subject

string · required

Subject of the email template

Example: Your Weekly News is Here!

designJson

object · required

JSON from Unlayer editor

Example: {"body":{"rows":[],"values":{"backgroundColor":"#ffffff","contentWidth":"600px"}}}

renderedHtml

string · required

Compiled HTML content of the email template

Example: <html><body><h1>Welcome to our Email</h1></body></html>

plainText

string · required

Plain text version of the email template

Example: Welcome to our Email

previewText

string · required

Short text that appears in email preview before opening

Example: This is the preview text for the Email email.

status

string · enum · required

Indicates status of the email template

Enum values:

DRAFT

PUBLISHED

ARCHIVED

Example: DRAFT

thumbnailUrl

string · required

Thumbnail image of the template for superadmin dashboard

Example: https://example.com/thumbnail-image.png

createdBy

string · required

Admin who created the template

Example: 64a7b2f5c9e77b6f4d8e4a2b

updatedBy

string · required

Admin who last updated the template

Example: 64a7b2f5c9e77b6f4d8e4a2b

GetEmailTemplatesDto

EmailTemplate[] · required

List of email templates

total

number · required

Total number of email templates

Example: 25

PreviewEmailTemplateDto

renderedHtml

string · required

Rendered HTML preview of the email template

Example: <html><body><h1>Welcome to our Newsletter</h1></body></html>

plainText

string

Plain text version of the email template preview

Example: Welcome to our Newsletter

UpdateEmailTemplateDto

name

string

Name of the email template

Example: Monthly Newsletter Template

description

string

Description of the email template

Example: A template for our monthly newsletters

subject

string

Subject of the email template

Example: Your Ecovolt Monthly Update!

designJson

object

JSON structure of the email template

Example: {"body":{"rows":[],"values":{"backgroundColor":"#ffffff","contentWidth":"600px"}}}

previewText

string

Preview text for the email template

Example: Check out the latest news and updates!

renderedHtml

string

Rendered HTML content of the email template

Example: <html><body><h1>Welcome</h1></body></html>

plainText

string

Plain text version of the email template

Example: Welcome to our newsletter

status

string · enum

Status of the email template

Enum values:

DRAFT

PUBLISHED

ARCHIVED

Example: DRAFT

CreateFirmwareDto

versionNumber

string · required

Semantic version number for the firmware release. Must follow the format major.minor.patch (e.g., 1.0.0).

Example: 2.1.5

chipModel

string · enum · required

Target chip model for this firmware build. Determines which plug devices can receive this firmware.

Enum values:

ESP8266

ESP32C2

ESP32C5

ESP32

ESP32C3

Example: ESP32C2

deviceType

string · enum · required

Type of device this firmware is intended for (e.g., PLUG, MCB, ENV_SENSOR).

Enum values:

PLUG

MCB

ENV_SENSOR

SMART_SWITCH

AIRCON_CONTROL

WATER_METER

RIDGE

Example: PLUG

remarks

string · required

Optional release notes or comments about this firmware version. Used to document changes and fixes.

Example: Bug fixes for power monitoring accuracy and stability improvements

file

string · required

Firmware binary file to upload. Must be a valid firmware binary for the specified chip model. Maximum file size: 10MB.

mcbType

string · enum

MCB subtype the firmware targets. Required when deviceType === MCB; ignored otherwise.

Enum values:

UNREGISTERED

SWITCH

BUILT_IN

COIL

COIL3P

Example: COIL

ReuploadFirmwareDto

file

string · required

Updated firmware binary file to upload. Must be a valid firmware binary for the existing chip model. Maximum file size: 10MB.

remarks

string

Optional updated release notes or comments about this firmware version. Used to document changes and fixes.

Example: Re-uploaded with critical security patch for authentication vulnerability

GetFirmwareResponseDto

_id

string · required

Primary ID of the Firmware

Example: 64b7f1e6f9c9d4e5b8a9f7c3

adminCreated

string · required

Name of the admin who created the firmware entry

Example: Glenn

versionNumber

string · required

Firmware version number

Example: 1.0.0

chipModel

string · enum · required

Chip Model of the Device

Enum values:

ESP8266

ESP32C2

ESP32C5

ESP32

ESP32C3

Example: ESP32C2

deviceType

string · enum · required

Type of device this firmware is intended for

Enum values:

PLUG

MCB

ENV_SENSOR

SMART_SWITCH

AIRCON_CONTROL

WATER_METER

RIDGE

Example: PLUG

createdAt

string · date-time · required

Timestamp when the firmware was created

Example: 2024-01-15T10:30:00Z

updatedAt

string · date-time · required

Timestamp when the firmware was last updated

Example: 2024-01-15T10:30:00Z

adminLastModified

string

Name of the admin who last modified/re-uploaded the firmware

Example: Glenn

mcbType

string · enum

MCB subtype this firmware targets. Set only when deviceType === MCB.

Enum values:

UNREGISTERED

SWITCH

BUILT_IN

COIL

COIL3P

Example: COIL

remarks

string

Remarks or notes about the firmware

Example: Initial release with basic features

MassSendOtaDto

versionNumber

string · required

Firmware version number to push to all matching plugs. Must exist in the firmware repository.

Example: 2.1.5

chipModel

string · enum · required

Target chip model to filter which plugs receive the OTA update. Only plugs with matching chip model will be updated.

Enum values:

ESP8266

ESP32C2

ESP32C5

ESP32

ESP32C3

Example: ESP32C2

deviceType

string · enum · required

Type of device this firmware is intended for (e.g., PLUG, MCB, ENV_SENSOR).

Enum values:

PLUG

MCB

ENV_SENSOR

SMART_SWITCH

AIRCON_CONTROL

WATER_METER

RIDGE

Example: PLUG

targetVersion

string · required

Optional filter to target only plugs currently running this specific firmware version. Used for targeted upgrades.

Example: 2.0.8

mcbType

string · enum

MCB subtype to match against the firmware record. Required when deviceType === MCB.

Enum values:

UNREGISTERED

SWITCH

BUILT_IN

COIL

COIL3P

Example: COIL

SendOtaDto

deviceIds

string[] · required

Array of unique plug identifiers to receive the OTA firmware update. Each plug will be notified via MQTT.

Example: ["64b7f1e6f9c9d4e5b8a9f7c1","64b7f1e6f9c9d4e5b8a9f7c2"]

versionNumber

string · required

Firmware version number to push to the specified devices. Must exist in the firmware repository.

Example: 2.1.5

chipModel

string · enum · required

Target chip model for firmware compatibility validation. Ensures plugs receive compatible firmware.

Enum values:

ESP8266

ESP32C2

ESP32C5

ESP32

ESP32C3

Example: ESP32C2

deviceType

string · enum · required

Type of device this firmware is intended for (e.g., PLUG, MCB, ENV_SENSOR).

Enum values:

PLUG

MCB

ENV_SENSOR

SMART_SWITCH

AIRCON_CONTROL

WATER_METER

RIDGE

Example: PLUG

targetVersion

string · required

Optional filter to verify plugs are running this specific firmware version before updating. Used for validation.

Example: 2.0.8

mcbType

string · enum

MCB subtype to match against the firmware record. Required when deviceType === MCB.

Enum values:

UNREGISTERED

SWITCH

BUILT_IN

COIL

COIL3P

Example: COIL

MassSendOtaRollbackDto

chipModel

string · enum · required

Chip Model of the Plug

Enum values:

ESP8266

ESP32C2

ESP32C5

ESP32

ESP32C3

Example: ESP32C2

deviceType

string · enum · required

Type of device this firmware is intended for (e.g., PLUG, MCB, ENV_SENSOR).

Enum values:

PLUG

MCB

ENV_SENSOR

SMART_SWITCH

AIRCON_CONTROL

WATER_METER

RIDGE

Example: PLUG

SendOtaRollbackDto

deviceIds

string[] · required

List of unique Plug IDs

Example: 1092384701928347

chipModel

string · enum · required

Chip Model of the Plug

Enum values:

ESP8266

ESP32C2

ESP32C5

ESP32

ESP32C3

Example: ESP32C2

deviceType

string · enum · required

Type of device this firmware is intended for (e.g., PLUG, MCB, ENV_SENSOR).

Enum values:

PLUG

MCB

ENV_SENSOR

SMART_SWITCH

AIRCON_CONTROL

WATER_METER

RIDGE

Example: PLUG

GetFirmwareListDto

total

number · required

Total count of items matching filters

Example: 150

page

number · min: 1 · required

Current page number

Example: 1

size

number · min: 1 · required

Items per page

Example: 50

totalPages

number · min: 0 · required

Total number of pages

Example: 3

GetFirmwareResponseDto[] · required

Array of firmware objects containing version details, chip models, and metadata. Sorted by creation date. File information is excluded for security.

GenerateDownloadUrlResponseDto

url

string · required

Clean OTA download URL without embedded token

Example: https://api.ecovolt.ai/firmware/download-ota-update?versionNumber=1.0.4&chipModel=ESP32C2&deviceType=PLUG

jwtToken

string · required

JWT token for Authorization header (devices should send as Bearer token)

Example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

VersionDistributionDto

versionNumber

string · required

Firmware version number

Example: 1.0.0

deviceCount

number · required

Number of devices with this firmware version

Example: 25

ChipModelDistributionDto

chipModel

string · enum · required

Chip model

Enum values:

ESP8266

ESP32C2

ESP32C5

ESP32

ESP32C3

Example: ESP32

totalDevices

number · required

Total number of devices for this chip model

Example: 50

VersionDistributionDto[] · required

Distribution of firmware versions for this chip model

DeviceTypeFirmwareDistributionDto

deviceType

string · enum · required

Device type

Enum values:

PLUG

MCB

ENV_SENSOR

SMART_SWITCH

AIRCON_CONTROL

WATER_METER

RIDGE

Example: PLUG

totalDevices

number · required

Total number of devices for this device type

Example: 100

ChipModelDistributionDto[] · required

Distribution of firmware versions grouped by chip model

GetFirmwareVersionDistributionDto

DeviceTypeFirmwareDistributionDto[] · required

Firmware version distribution grouped by device type

total

number · required

Total number of device types

Example: 6

DeviceFirmwareInfoDto

_id

string · required

Device ID

Example: 64b7f1e6f9c9d4e5b8a9f7c3

macId

string · required

Device MAC ID

Example: 1092384701928347

deviceType

string · enum · required

Device type

Enum values:

PLUG

MCB

ENV_SENSOR

SMART_SWITCH

AIRCON_CONTROL

WATER_METER

RIDGE

Example: PLUG

onStatus

string · enum · required

Device status

Enum values:

OFF

INACTIVE

ERROR

ACTIVE

Example: ON

systemName

string · required

System name

Example: Main Building System

systemId

string · required

System ID

Example: 64b7f1e6f9c9d4e5b8a9f7c4

deviceName

string

Device name

Example: Living Room AC

deviceNumber

number

Device number

Example: 1

chipModel

string · enum

Chip model

Enum values:

ESP8266

ESP32C2

ESP32C5

ESP32

ESP32C3

Example: ESP32

versionNumber

string

Firmware version number

Example: 1.0.0

lastSeen

string · date-time

Last time the device was seen/reported

Example: 2024-01-15T10:30:00.000Z

autoUpdateAttempts

number

Number of auto-update attempts for this device

Example: 2

Default: 0

autoUpdateBlacklisted

boolean

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

Example: false

Default: false

manualUpdateBlacklist

boolean

Whether the device is manually blacklisted from auto-updates by admin

Example: false

Default: false

GetDeviceFirmwareListDto

total

number · required

Total count of items matching filters

Example: 150

page

number · min: 1 · required

Current page number

Example: 1

size

number · min: 1 · required

Items per page

Example: 50

totalPages

number · min: 0 · required

Total number of pages

Example: 3

DeviceFirmwareInfoDto[] · required

List of devices with firmware information

CreateAutoUpdatePolicyDto

enabled

boolean · required

Enable or disable the auto-update policy

Example: false

Default: false

deviceType

string · enum · required

Target device type for auto-updates

Enum values:

PLUG

MCB

ENV_SENSOR

SMART_SWITCH

AIRCON_CONTROL

WATER_METER

RIDGE

Example: PLUG

chipModel

string · enum · required

Target chip model for auto-updates

Enum values:

ESP8266

ESP32C2

ESP32C5

ESP32

ESP32C3

Example: ESP32

targetVersion

string · required

Target firmware version to auto-update devices to

Example: 2.0.0

mcbType

string · enum

MCB subtype the policy targets. Required when deviceType === MCB; ignored otherwise.

Enum values:

UNREGISTERED

SWITCH

BUILT_IN

COIL

COIL3P

Example: COIL

sourceVersions

string[]

List of source firmware versions to update FROM. If empty or not provided, updates all versions. If specified, only devices on these versions will be auto-updated.

Example: ["1.1.0","1.2.0"]

Default: []

maxRetries

number

Maximum number of OTA attempts per device before blacklisting

Example: 5

Default: 5

AutoUpdatePolicyResponseDto

_id

string · required

Primary ID of the policy

Example: 64b7f1e6f9c9d4e5b8a9f7c3

enabled

boolean · required

Enable or disable the auto-update policy

Example: true

deviceType

string · enum · required

Target device type for auto-updates

Enum values:

PLUG

MCB

ENV_SENSOR

SMART_SWITCH

AIRCON_CONTROL

WATER_METER

RIDGE

Example: PLUG

chipModel

string · enum · required

Target chip model for auto-updates

Enum values:

ESP8266

ESP32C2

ESP32C5

ESP32

ESP32C3

Example: ESP32

targetVersion

string · required

Target firmware version to auto-update devices to

Example: 2.0.0

maxRetries

number · required

Maximum number of OTA attempts per device before blacklisting

Example: 5

createdBy

string · required

Admin email/ID who created this policy

Example: admin@example.com

lastModifiedBy

string · required

Admin email/ID who last modified this policy

Example: admin@example.com

createdAt

string · date-time · required

Timestamp when the policy was created

Example: 2024-01-15T10:30:00Z

updatedAt

string · date-time · required

Timestamp when the policy was last updated

Example: 2024-01-15T10:30:00Z

sourceVersions

string[]

List of source firmware versions to update FROM. If empty, updates all versions.

Example: ["1.1.0","1.2.0"]

AutoUpdateAffectedDeviceDto

_id

string · required

Primary ID of the device

Example: 64b7f1e6f9c9d4e5b8a9f7c3

deviceName

string · required

Device name

Example: Living Room Plug

macId

string · required

Device MAC address

Example: AA:BB:CC:DD:EE:01

deviceType

string · required

Device type

Example: PLUG

chipModel

string · required

Chip model

Example: ESP32

versionNumber

string · required

Current firmware version

Example: 1.9.2

autoUpdateAttempts

number · required

Number of auto-update OTA attempts sent to this device

Example: 2

autoUpdateBlacklisted

boolean · required

Whether device is blacklisted from further auto-update attempts

Example: false

object · required

System information

lastAutoUpdateAttempt

string · date-time

Timestamp of last auto-update OTA attempt

Example: 2024-01-15T08:45:00Z

AutoUpdateAffectedDevicesListDto

AutoUpdateAffectedDeviceDto[] · required

List of devices affected by the auto-update policy

total

number · required

Total number of devices matching the policy criteria

Example: 25

policyTargetVersion

string · required

Target firmware version from the policy

Example: 2.0.0

needsUpdateCount

number · required

Number of devices that need updates (version mismatch, not blacklisted)

Example: 18

CreateTenantDto

tenantName

string · required

Name of the tenant. Represents a department, unit, or organization within the system.

Example: Faculty of Engineering

adminCreation

boolean · required

Flag indicating whether an tenant admin should be created, if so send invite.

tenantEmail

string

Primary email address for tenant contact. Used for notifications and billing communications.

Example: engineering@university.edu

remarks

string

Additional notes or comments about the tenant. Useful for documenting special arrangements or contact details.

Example: Main office located on 7th floor, contact person: John Doe

level

number

Floor number where the tenant is primarily located. Used for organizing tenants within a building.

Example: 7

energyUsage

number

Initial energy usage budget allocated to the tenant in kilowatt-hours. Used for tracking consumption against quotas.

Example: 1000

object

Geographic location details of the tenant. Includes address, city, country, and coordinates for mapping purposes.

tenantType

string

Tenant type key. Must be a valid type defined for this system via /entity-type/TENANT.

Example: RETAIL

GetTenantDto

_id

string · required

Unique identifier of the tenant in the database.

Example: 64b7f1e6f9c9d4e5b8a9f7c1

tenantName

string · required

Name of the tenant. Represents a department, unit, or organization within the system.

Example: Faculty of Engineering

tenantEmail

string · required

Primary email address for tenant contact. Used for notifications and billing communications.

Example: engineering@university.edu

deviceCount

number · required

Total count of devices assigned to this tenant. Used for resource allocation tracking.

Example: 15

deviceOnCount

number · required

Number of devices currently in ON status for this tenant.

Example: 8

deviceOffCount

number · required

Number of devices currently in OFF status for this tenant.

Example: 5

deviceInactiveCount

number · required

Number of devices currently in INACTIVE status for this tenant.

Example: 2

totalEnergyUsage

number · required

Energy usage budget allocated to the tenant in kilowatt-hours. Tracks consumption against quotas.

Example: 1000

object

Geographic location details of the tenant. Includes address, city, country, and coordinates.

level

number

Floor number where the tenant is primarily located. Used for organizing tenants within a building.

Example: 7

totalFlaggedCount

number

Total number of rolling windows this tenant has been flagged. Represents how many different time periods the tenant exceeded thresholds.

Example: 3

totalViolationCount

number

Total number of individual violations across all time. Sum of all daily violations ever recorded for this tenant.

Example: 15

isMonitoringDisabled

boolean

Whether surge monitoring is disabled for this tenant. If true, the tenant will not be checked for energy threshold violations.

Example: false

suspectedDeviceTypes

string[]

Device types suspected of causing surge violations for this tenant.

Example: ["PLUG","MCB"]

tenantType

string

Tenant type key

Example: RETAIL

GetTenantsResponseDto

total

number · required

Total count of items matching filters

Example: 150

page

number · min: 1 · required

Current page number

Example: 1

size

number · min: 1 · required

Items per page

Example: 50

totalPages

number · min: 0 · required

Total number of pages

Example: 3

data

string[] · required

Array of GetTenantDto IDs

GetRoomDto

_id

string · required

Unique identifier of the room in MongoDB ObjectId format.

Example: 64b7f1e6f9c9d4e5b8a9f7c1

name

string · required

Display name of the room as registered in the system.

Example: Living Room

deviceCount

number · required

Total count of devices currently assigned to this room.

Example: 8

deviceOnCount

number · required

Number of devices currently in ON status for this room.

Example: 4

deviceOffCount

number · required

Number of devices currently in OFF status for this room.

Example: 3

deviceInactiveCount

number · required

Number of devices currently in INACTIVE status for this room.

Example: 1

totalEnergyUsage

number · required

Cumulative energy consumption from all devices in this room, measured in kilowatt-hours (kWh).

Example: 124.67

tenantId

string

Unique identifier of the tenant organization that owns this room.

Example: 64b7f1e6f9c9d4e5b8a9f7c4

tenantName

string

Name of the tenant organization that owns this room. Included when tenant data is populated.

Example: Faculty of Engineering

zoneId

string

Unique identifier of the zone that has access to this room.

Example: 64b7f1e6f9c9d4e5b8a9f7c5

zoneName

string

Name of the zone that has access to this room. Included when zone data is populated.

Example: Zone A

remarks

string

Optional administrative notes or comments about the room. Used for describing room purpose or equipment.

Example: Conference room with presentation equipment

totalFlaggedCount

number

Total number of rolling windows this room has been flagged. Represents how many different time periods the room exceeded thresholds.

Example: 5

totalViolationCount

number

Total number of individual violations across all time. Sum of all daily violations ever recorded for this room.

Example: 22

isMonitoringDisabled

boolean

Whether surge monitoring is disabled for this room. If true, the room will not be checked for energy threshold violations.

Example: false

squareMeter

number

Floor area of the room in square meters.

Example: 25.5

energyIntensity

number

Energy intensity over the past 30 days in kWh/m²/month. Null if the room has no squareMeter set.

Example: 10.8

suspectedDeviceTypes

string[]

Device types suspected of causing surge violations for this room.

Example: ["PLUG","MCB"]

roomType

string

Room type key

Example: MEETING_ROOM

GetZoneDto

_id

string · required

Unique identifier of the zone in MongoDB ObjectId format.

Example: 64b7f1e6f9c9d4e5b8a9f7c1

name

string · required

Full name of the zone as registered in the system.

Example: Zone A - Engineering Wing

email

string · required

Email address of the zone used for authentication and notifications.

Example: zone-a@ecovolt.com

deviceCount

number · required

Total count of devices currently assigned to this zone across all their rooms.

Example: 12

deviceOnCount

number · required

Number of devices currently in ON status for this zone.

Example: 6

deviceOffCount

number · required

Number of devices currently in OFF status for this zone.

Example: 4

deviceInactiveCount

number · required

Number of devices currently in INACTIVE status for this zone.

Example: 2

totalEnergyUsage

number · required

Cumulative energy consumption from all devices assigned to the zone, measured in kilowatt-hours (kWh).

Example: 124.67

remarks

string

Optional administrative notes or comments about the zone. Used for internal tracking and context.

Example: Department head - Engineering

tenantName

string

Name of the tenant organization that the zone belongs to. Included when tenant data is populated.

Example: Faculty of Engineering

tenantId

string

Unique identifier of the tenant organization that the zone is associated with.

Example: 64b7f1e6f9c9d4e5b8a9f7c1

rooms

string[]

Array of GetRoomDto IDs

totalFlaggedCount

number

Total number of rolling windows this zone has been flagged. Represents how many different time periods the zone exceeded thresholds.

Example: 2

totalViolationCount

number

Total number of individual violations across all time. Sum of all daily violations ever recorded for this zone.

Example: 8

isMonitoringDisabled

boolean

Whether surge monitoring is disabled for this zone. If true, the zone will not be checked for energy threshold violations.

Example: false

suspectedDeviceTypes

string[]

Device types suspected of causing surge violations for this zone.

Example: ["PLUG","MCB"]

zoneType

string

Zone type key

Example: LABORATORY

TenantRelationshipDto

_id

string · required

Unique identifier of the tenant in the database.

Example: 64b7f1e6f9c9d4e5b8a9f7c1

tenantName

string · required

Name of the tenant. Represents a department, unit, or organization within the system.

Example: Faculty of Engineering

energyUsage

number · required

Energy usage budget allocated to the tenant in kilowatt-hours. Tracks consumption against quotas.

Example: 1000

DeviceDetailsDto[] · required

Array of IoT devices assigned to this tenant. Includes all device types: smart plugs, MCBs, distribution boxes, etc.

rooms

string[] · required

Array of GetRoomDto IDs

GetZoneDto[] · required

Array of zones assigned to this tenant. Includes zone accounts with access to tenant resources.

numberOfZones

number · required

Total count of zones assigned to this tenant. Used for resource planning and statistics.

Example: 24

numberOfRooms

number · required

Total count of rooms belonging to this tenant. Used for resource planning and statistics.

Example: 18

numberOfDevices

number · required

Total count of IoT devices assigned to this tenant. Used for resource planning and statistics. Includes all device types: smart plugs, MCBs, distribution boxes, etc.

Example: 65

GetTenantsRelationshipDto

TenantRelationshipDto[] · required

Array of tenants with their complete relationship hierarchy including zones, rooms, and devices.

numberOfTenants

number · required

Total count of tenants in the system. Useful for pagination and statistics.

Example: 12

numberOfZones

number · required

Total count of zones across all tenants in the system. Useful for system-wide statistics.

Example: 145

numberOfRooms

number · required

Total count of rooms across all tenants in the system. Useful for system-wide statistics.

Example: 87

numberOfDevices

number · required

Total count of IoT devices across all tenants in the system. Useful for system-wide statistics. Includes all device types: smart plugs, MCBs, distribution boxes, etc.

Example: 342

RoomEnergyUsageDto

roomId

string · required

Unique identifier of the room

Example: 64b7f1e6f9c9d4e5b8a9f7c1

roomName

string · required

Name of the room

Example: Conference Room A

energyUsage

number · required

Total energy usage in kilowatt-hours (kWh) for the specified period

Example: 125.45

GetRoomEnergyUsageResponseDto

tenantId

string · required

Tenant ID for which energy usage was calculated

Example: 64b7f1e6f9c9d4e5b8a9f7c1

days

number · required

Number of days the energy usage was calculated over

Example: 7

startDate

string · required

Start date of the energy usage period (ISO 8601 format)

Example: 2024-01-15T00:00:00.000Z

endDate

string · required

End date of the energy usage period (ISO 8601 format)

Example: 2024-01-22T00:00:00.000Z

RoomEnergyUsageDto[] · required

List of rooms with their energy usage data

totalRooms

number · required

Total number of rooms found for this tenant

Example: 5

totalEnergyUsage

number · required

Total energy usage across all rooms in kWh

Example: 547.32

UpdateTenantDto

tenantName

string · required

Name of the tenant. Represents a department, unit, or organization within the system.

Example: Faculty of Engineering

tenantEmail

string · required

Primary email address for tenant contact. Used for notifications and billing communications.

Example: engineering@university.edu

object · required

Geographic location details of the tenant. Includes address, city, country, and coordinates for mapping purposes.

remarks

string

Additional notes or comments about the tenant. Useful for documenting special arrangements or contact details.

Example: Main office located on 7th floor, contact person: John Doe

level

number

Floor number where the tenant is primarily located. Used for organizing tenants within a building.

Example: 7

tenantType

string

Tenant type key. Must be a valid type defined for this system via /entity-type/TENANT.

Example: RETAIL

MonitoringEntityType

string · enum

Enum values:

ROOM

TENANT

ZONE

Type of entity to start usage surge analysis for

StartAnalysisDto

entityType

string · enum · required

Type of entity to start usage surge analysis for

Enum values:

ROOM

TENANT

ZONE

Example: ROOM

startDate

string · required

Start date for historical analysis (YYYY-MM-DD format). Must be at least 7 days before end date.

Example: 2026-01-01

endDate

string · required

End date for historical analysis (YYYY-MM-DD format). Must be at least 7 days after start date.

Example: 2026-01-14

initialFlagThreshold

number · required

Minimum number of violations required to flag an entity as initially problematic during analysis

Example: 10

McbMeasurementType

string · enum

Enum values:

SSO

LIGHTS_FANS

LIGHTS

FANS

AIRCON

POWER_OUTLETS

GENERAL

COMBINED

MCB measurement type classification

McbMeasurementTypeBreakdown

measurementType

string · enum · required

MCB measurement type classification

Enum values:

SSO

LIGHTS_FANS

LIGHTS

FANS

AIRCON

POWER_OUTLETS

GENERAL

COMBINED

Example: AIRCON

energyKwh

number · required

Total energy consumption in kWh for this measurement type

Example: 123.45

costAmount

number · required

Total cost amount for this measurement type

Example: 35.18

EntityEnergyBreakdown

McbMeasurementTypeBreakdown[] · required

Energy breakdown by MCB measurement type

totalEnergyKwh

number · required

Total energy consumption across all measurement types (kWh)

Example: 456.78

totalCost

number · required

Total cost across all measurement types ($)

Example: 130.18

periodDays

number · required

Number of days in the analysis period

Example: 7

dailyAverageKwh

number · required

Daily average energy consumption (kWh)

Example: 65.25

predictedMonthlyKwh

number · required

Predicted monthly energy consumption (kWh)

Example: 1957.5

predictedMonthlyCost

number · required

Predicted monthly cost ($)

Example: 558.39

EntityAnalysisDetailDto

entityId

string · required

Entity ID

Example: 65a1b2c3d4e5f6a7b8c9d0e1

entityName

string · required

Entity name

Example: Conference Room A

averageDailyUsageKwh

number · required

Average daily usage during analysis period (kWh)

Example: 12.5

totalUsageKwh

number · required

Total usage during analysis period (kWh)

Example: 175

validDaysCount

number · required

Number of days with valid data in analysis period

Example: 14

exceededThreshold

boolean · required

Whether this entity exceeded the threshold during analysis

Example: false

exceedanceCount

number · required

Number of times threshold was exceeded during analysis period

Example: 0

predictedMonthlyKwh

number · required

Predicted monthly usage (kWh) based on average daily usage

Example: 375

predictedYearlyKwh

number · required

Predicted yearly usage (kWh) based on average daily usage

Example: 4562.5

predictedMonthlyCost

number · required

Predicted monthly cost based on tariff

Example: 75

predictedYearlyCost

number · required

Predicted yearly cost based on tariff

Example: 912.5

object · required

Energy breakdown by MCB measurement type

AnalysisStartResponseDto

success

boolean · required

Operation success status

message

string · required

Confirmation message

Example: Analysis completed using historical data from 2026-01-01 to 2026-01-14

calculatedThresholdKwh

number · required

Calculated threshold in kWh

Example: 15.5

entitiesAnalyzed

number · required

Number of entities analyzed

Example: 42

initialFlaggedCount

number · required

Number of initially flagged entities

Example: 3

EntityAnalysisDetailDto[] · required

Detailed analysis for each entity

object

System-wide energy breakdown by MCB measurement type

SentinelPowerRangeRuleDto

id

string · required

Unique rule identifier (UUID)

Example: a1b2c3d4-...

label

string · required

Human-readable label for the suspected device type

Example: Suspected Fridge

minWatts

number · required

Minimum power threshold in Watts (inclusive)

Example: 50

maxWatts

number · required

Maximum power threshold in Watts (inclusive)

Example: 125

minDurationMinutes

number · required

Minimum cumulative minutes device must sustain power in range on a violation day to be classified

Example: 120

CreateSurgeConfigDto

calculatedThresholdKwh

number · required

Calculated threshold (median) in kWh

Example: 15.5

manualThresholdKwh

number

Manual threshold override (kWh) - takes precedence over calculated threshold

Example: 18

defaultViolationCount

number

Default violation count to trigger flag

Example: 3

defaultViolationWindow

number

Default rolling window in days

Example: 7

SentinelPowerRangeRuleDto[]

Sentinel power range rules for suspected device classification

SurgeConfigResponseDto

success

boolean · required

Operation success status

entityType

string · enum · required

Entity type

Enum values:

ROOM

TENANT

ZONE

message

string · required

Success or informational message

object · required

Updated configuration

UpdateSystemSurgeConfigDto

calculatedThresholdKwh

number

Auto-calculated threshold (median) in kWh - can be manually adjusted

Example: 15.5

manualThresholdKwh

number

Manual threshold override (kWh) - takes precedence over calculated threshold

Example: 18

defaultViolationCount

number

Default violation count to trigger flag

Example: 3

defaultViolationWindow

number

Default rolling window in days

Example: 7

SentinelPowerRangeRuleDto[]

Sentinel power range rules for suspected device classification

UpsertSentinelRulesDto

SentinelPowerRangeRuleDto[] · required

Full replacement set of sentinel power range rules for this entity type

EntityMetadata

tenantId

string

Tenant ID

Example: 65a1b2c3d4e5f6a7b8c9d0e1

tenantName

string

Tenant name

Example: Acme Corporation

zoneId

string

Zone ID

Example: 65a1b2c3d4e5f6a7b8c9d0e2

zoneName

string

Zone name

Example: Zone A

ViolationResponseDto

_id

string · required

Violation ID

entityType

string · enum · required

Entity type

Enum values:

ROOM

TENANT

ZONE

entityId

string · required

Entity ID

entityName

string · required

Entity name

date

string · date-time · required

Violation date

dailyUsageKwh

number · required

Actual daily usage (kWh)

thresholdKwh

number · required

Threshold that was exceeded (kWh)

exceedanceKwh

number · required

Amount exceeded (kWh)

exceedancePercent

number · required

Percentage exceeded (%)

isFlagged

boolean · required

Whether violation triggered alert

object

Additional contextual metadata

ViolationsListResponseDto

total

number · required

Total count of items matching filters

Example: 150

page

number · min: 1 · required

Current page number

Example: 1

size

number · min: 1 · required

Items per page

Example: 50

totalPages

number · min: 0 · required

Total number of pages

Example: 3

ViolationResponseDto[] · required

List of violations

LatestViolationDto

date

string · date-time · required

Date of latest violation

dailyUsageKwh

number · required

Daily usage in kWh

thresholdKwh

number · required

Threshold in kWh

exceedanceKwh

number · required

Exceedance in kWh

exceedancePercent

number · required

Exceedance percentage

ViolationMetadata

entityName

string

Entity name (room/tenant/zone)

tenantId

string

Tenant ID if applicable

tenantName

string

Tenant name if applicable

userId

string

Zone ID if applicable

zoneName

string

Zone name if applicable

FlaggedEntityDto

entityId

string · required

Entity ID

entityName

string · required

Entity name

entityType

string · enum · required

Entity type

Enum values:

ROOM

TENANT

ZONE

violationCount

number · required

Total violation count

currentPeriodViolationCount

number · required

Current period violation count

totalFlaggedCount

number · required

Total times this entity has been flagged

thresholdKwh

number · required

Threshold in kWh

firstViolationDate

string · date-time · required

Date of first violation

lastViolationDate

string · date-time · required

Date of last violation

object · required

Latest violation details

allViolationDates

string[] · required

All violation dates

object

Additional violation metadata

FlaggedEntitiesResponseDto

FlaggedEntityDto[] · required

List of flagged entities

total

number · required

Total number of flagged entities

page

number · required

Current page number

size

number · required

Page size

ViolationClearReason

string · enum

Enum values:

ISSUE_RESOLVED

TENANT_COMPLIANT

METER_ERROR

DATA_CORRECTION

EQUIPMENT_UPGRADE

SEASONAL_ADJUSTMENT

WHITELIST_GRANTED

FALSE_POSITIVE

Primary reason for clearing violations

ClearViolationsDto

reason

string · enum · required

Primary reason for clearing violations

Enum values:

ISSUE_RESOLVED

TENANT_COMPLIANT

METER_ERROR

DATA_CORRECTION

EQUIPMENT_UPGRADE

SEASONAL_ADJUSTMENT

WHITELIST_GRANTED

FALSE_POSITIVE

Example: ISSUE_RESOLVED

notes

string

Additional details or context about why violations are being cleared

Example: Tenant installed energy-efficient equipment

ClearViolationsResponseDto

success

boolean · required

Operation success status

entityType

string · enum · required

Entity type

Enum values:

ROOM

TENANT

ZONE

entityId

string · required

Entity ID

deletedCount

number · required

Number of violations deleted

message

string · required

Confirmation message

ToggleMonitoringDto

isEnabled

boolean · required

Whether to enable monitoring (true) or disable it (false)

Example: false

reason

string

Reason for enabling/disabling monitoring for this entity

Example: Approved high-power usage for medical equipment

MonitoringStatusResponseDto

success

boolean · required

Operation success status

entityType

string · enum · required

Entity type

Enum values:

ROOM

TENANT

ZONE

entityId

string · required

Entity ID

isMonitoringDisabled

boolean · required

Whether entity monitoring is currently disabled

message

string · required

Confirmation message

ResetViolationsDto

deleteViolationRecords

boolean

Whether to delete all violation records from database (default: false). If false, only counters are reset but historical records are preserved.

Default: false

ResetCounters

totalFlaggedCount

number · required

Total flagged count before reset

currentPeriodViolationCount

number · required

Current period violation count before reset

ResetViolationsResponseDto

success

boolean · required

Success status

entityType

string · enum · required

Entity type

Enum values:

ROOM

TENANT

ZONE

entityId

string · required

Entity ID

object · required

Counter values before reset

deletedViolations

number · required

Number of violation records deleted

message

string · required

Success message

EntityEnergyBreakdownResponseDto

entityId

string · required

Entity ID

Example: 65a1b2c3d4e5f6a7b8c9d0e1

entityName

string · required

Entity name

Example: Conference Room A

entityType

string · enum · required

Entity type

Enum values:

ROOM

TENANT

ZONE

Example: ROOM

startDate

string · date-time · required

Analysis period start date

endDate

string · date-time · required

Analysis period end date

object · required

MCB measurement type breakdown with cost analysis

EntityCheckResultDto

entityId

string · required

Entity ID

entityName

string · required

Entity name

entityType

string · enum · required

Type of entity

Enum values:

ROOM

TENANT

ZONE

dailyUsageKwh

number · required

Daily usage in kWh

thresholdKwh

number · required

Threshold in kWh

violated

boolean · required

Whether this entity violated the threshold

currentPeriodViolationCount

number · required

Current period violation count after check

totalFlaggedCount

number · required

Total lifetime flagged count after check

DailySurgeCheckResultDto

systemId

string · required

System ID that was checked

checkDate

string · date-time · required

Check date

totalEntitiesChecked

number · required

Total entities checked across all types

totalViolationsDetected

number · required

Total violations detected across all types

EntityCheckResultDto[] · required

Detailed results for each entity checked

summaryByType

object · required

Summary by entity type

Example: {"ROOM":{"checked":10,"violated":2},"TENANT":{"checked":5,"violated":1},"USER":{"checked":20,"violated":3}}

FlaggedEntityDigestResultDto

entityId

string · required

Entity ID

entityName

string · required

Entity name

currentPeriodViolationCount

number · required

Current period violation count

totalFlaggedCount

number · required

Total lifetime flagged count

thresholdKwh

number · required

Threshold in kWh

lastViolationDate

string · date-time · required

Last violation date

SurgeDigestResultDto

systemId

string · required

System ID

entityType

string · enum · required

Entity type for this digest

Enum values:

ROOM

TENANT

ZONE

startDate

string · date-time · required

Rolling window period start date

endDate

string · date-time · required

Rolling window period end date

rollingWindowDays

number · required

Rolling window in days

totalFlaggedEntities

number · required

Total flagged entities in this digest

totalViolations

number · required

Total violations across all flagged entities

FlaggedEntityDigestResultDto[] · required

List of flagged entities included in digest

notificationId

string · required

Notification ID created for this digest

SingleScheduleEntryDto

action

string · enum · required

Action type to perform at the scheduled date-time(s). For simple ON/OFF or complex actions like SET_TEMPERATURE.

Enum values:

OFF

SET_TEMPERATURE

SET_BRIGHTNESS

SET_MODE

TOGGLE_SMART_SWITCH

Example: OFF

dateTime

string · date-time

Single scheduled date and time in ISO 8601 format when the one-time action should execute. Cannot be used with startDateTime/endDateTime. Must be a future timestamp.

Example: 2024-12-31T06:00:00Z

startDateTime

string · date-time

Start date and time of the schedule range in ISO 8601 format. Must be used with endDateTime. Cannot be used with dateTime. Creates daily timers between start and end dates (inclusive) at the specified time.

Example: 2024-12-20T06:00:00Z

endDateTime

string · date-time

End date and time of the schedule range in ISO 8601 format. Must be used with startDateTime. Cannot be used with dateTime. Creates daily timers between start and end dates (inclusive) at the specified time.

Example: 2024-12-31T06:00:00Z

actionValue

number

Optional value for actions that require it (e.g., temperature value for SET_TEMPERATURE, brightness for SET_BRIGHTNESS). Required for certain action types.

Example: 24

ruleName

string

AWS EventBridge rule name associated with this schedule entry. Used for managing and updating the schedule.

Example: device-64b7f1e6-timer-abc123

DailyScheduleEntryDto

time

string · required

Time when the scheduled action should occur in 24-hour format (HH:MM). Applied to recurring weekly schedules.

Example: 06:00

action

string · enum · required

Action type to perform at the scheduled time. For simple ON/OFF or complex actions like SET_TEMPERATURE.

Enum values:

OFF

SET_TEMPERATURE

SET_BRIGHTNESS

SET_MODE

TOGGLE_SMART_SWITCH

Example: OFF

actionValue

number

Optional value for actions that require it (e.g., temperature value for SET_TEMPERATURE, brightness for SET_BRIGHTNESS). Required for certain action types.

Example: 24

DeviceWeeklyScheduleDto

SingleScheduleEntryDto[]

Array of one-time scheduled actions that occur at specific date-times. These schedules execute once and are automatically removed.

DailyScheduleEntryDto[]

Array of scheduled actions for Monday. These execute weekly at specified times.

DailyScheduleEntryDto[]

Array of scheduled actions for Tuesday. These execute weekly at specified times.

DailyScheduleEntryDto[]

Array of scheduled actions for Wednesday. These execute weekly at specified times.

DailyScheduleEntryDto[]

Array of scheduled actions for Thursday. These execute weekly at specified times.

DailyScheduleEntryDto[]

Array of scheduled actions for Friday. These execute weekly at specified times.

DailyScheduleEntryDto[]

Array of scheduled actions for Saturday. These execute weekly at specified times.

DailyScheduleEntryDto[]

Array of scheduled actions for Sunday. These execute weekly at specified times.

DeviceSingleScheduleDto

SingleScheduleEntryDto[]

Array of one-time scheduled actions with specific date-times. These schedules execute once and are automatically removed after execution.

EditDeviceSingleTimerDto

ruleName

string · required

AWS EventBridge rule name of the one-time timer to edit. Used to identify which schedule to update.

Example: device-64b7f1e6-timer-abc123

dateTime

string · date-time · required

Updated scheduled date and time for the timer in ISO 8601 format. Must be a future timestamp.

Example: 2024-12-31T18:00:00Z

action

string · enum · required

Updated action type to perform at the scheduled time. Replaces the existing action in the timer.

Enum values:

OFF

SET_TEMPERATURE

SET_BRIGHTNESS

SET_MODE

TOGGLE_SMART_SWITCH

Example: ON

actionValue

number

Optional value for actions that require it (e.g., temperature value for SET_TEMPERATURE, brightness for SET_BRIGHTNESS). Required for certain action types.

Example: 24

DeleteDeviceSingleTimerDto

ruleName

string · required

AWS EventBridge rule name of the one-time timer to delete. Used to identify which schedule to remove.

Example: device-64b7f1e6-timer-abc123

MergeMode

string · enum

Enum values:

replace

merge

append

Defines how schedules should be merged. REPLACE: Clear all existing schedules and set new ones (default). MERGE: Add new schedules to existing ones, updating duplicates. APPEND: Add new schedules without modifying existing ones.

MassDevicesScheduleDto

deviceIds

string[] · required

Array of unique device identifiers to apply the schedule configuration to. Each device will receive the same schedule.

Example: ["64b7f1e6f9c9d4e5b8a9f7c1","64b7f1e6f9c9d4e5b8a9f7c2"]

object

Schedule configuration containing weekly recurring and one-time schedules to apply to multiple devices.

mergeMode

string · enum

Enum values:

replace

merge

append

Example: merge

Default: replace

MassDevicesSingleScheduleDto

deviceIds

string[] · required

Array of unique device identifiers to apply the one-time schedules to. Each device will receive the same schedule.

Example: ["64b7f1e6f9c9d4e5b8a9f7c1","64b7f1e6f9c9d4e5b8a9f7c2"]

SingleScheduleEntryDto[]

Array of one-time scheduled actions with specific date-times to apply to multiple devices.

DeviceScheduleInfo

ruleName

string · required

AWS EventBridge rule name associated with this device schedule. Used for identifying and managing the schedule.

Example: device-64b7f1e6-timer-abc123

deviceId

string · required

Unique identifier of the device in MongoDB ObjectId format.

Example: 64b7f1e6f9c9d4e5b8a9f7c1

deviceName

string · required

Display name of the device for identification purposes in the UI.

Example: Living Room Smart Plug

MassEditDeviceSingleTimerDto

DeviceScheduleInfo[] · required

Array of device details with EventBridge rule names for the one-time timers to batch edit. All specified timers will be updated with the same new schedule.

Example: [{"deviceId":"64b7f1e6f9c9d4e5b8a9f7c1","deviceName":"Living Room TV Plug","ruleName":"device-64b7f1e6-timer-abc123"},{"deviceId":"64b7f1e6f9c9d4e5b8a9f7c2","deviceName":"Kitchen Appliance Plug","ruleName":"device-64b7f1e6-timer-def456"}]

newDateTime

string · date-time · required

New scheduled date and time to apply to all specified timers. Must be a future timestamp in ISO 8601 format.

Example: 2024-12-31T20:00:00Z

newAction

string · enum · required

New action type to apply to all specified timers at the scheduled time. Replaces existing actions.

Enum values:

OFF

SET_TEMPERATURE

SET_BRIGHTNESS

SET_MODE

TOGGLE_SMART_SWITCH

Example: OFF

newActionValue

number

Optional value for the new action (e.g., temperature for SET_TEMPERATURE, brightness for SET_BRIGHTNESS). Required for certain action types.

Example: 24

MassEditDeviceWeeklyTimerDto

DeviceScheduleInfo[] · required

Array of device details with EventBridge rule names for the recurring weekly timers to batch edit. All specified timers will be updated.

Example: [{"deviceId":"64b7f1e6f9c9d4e5b8a9f7c1","deviceName":"Living Room TV Plug","ruleName":"device-64b7f1e6-weekly-abc123"},{"deviceId":"64b7f1e6f9c9d4e5b8a9f7c2","deviceName":"Kitchen Appliance Plug","ruleName":"device-64b7f1e6-weekly-def456"}]

newTime

string · required

New time in 24-hour format (HH:MM) to apply to all specified weekly timers. Must be valid time between 00:00 and 23:59.

Example: 20:00

newAction

string · enum · required

New action type to apply to all specified weekly timers at the scheduled time. Replaces existing actions.

Enum values:

OFF

SET_TEMPERATURE

SET_BRIGHTNESS

SET_MODE

TOGGLE_SMART_SWITCH

Example: OFF

newActionValue

number

Optional value for the new action (e.g., temperature for SET_TEMPERATURE, brightness for SET_BRIGHTNESS). Required for certain action types.

Example: 24

daysOfWeek

string[]

Optional filter to only edit timers on specific days of the week. If provided, only rules matching these days will be updated. If omitted, all provided rules will be updated (backward compatible).

Enum values:

monday

tuesday

wednesday

thursday

friday

saturday

sunday

Example: ["monday","wednesday","friday"]

MassDeleteDeviceTimerDto

DeviceScheduleInfo[] · required

Array of device details with EventBridge rule names for the timers to batch delete. Supports both one-time and recurring weekly schedules.

GroupedRecurringSchedule

time

string · required

Scheduled time in 24-hour format (HH:MM) when the recurring action executes. Shared by all devices in this group.

Example: 06:00

action

string · enum · required

Action type to perform at the scheduled time. All devices in this group will execute the same action.

Enum values:

OFF

SET_TEMPERATURE

SET_BRIGHTNESS

SET_MODE

TOGGLE_SMART_SWITCH

Example: ON

daysOfWeek

string[] · required

Array of weekday names when this recurring schedule is active. Schedule repeats weekly on these days.

Example: ["monday","tuesday","wednesday"]

deviceCount

number · required

Total number of devices that share this identical recurring schedule pattern.

Example: 50

DeviceScheduleInfo[] · required

Array of device details with their EventBridge rule names. Each device has this same recurring schedule configured.

Example: [{"deviceId":"64b7f1e6f9c9d4e5b8a9f7c1","deviceName":"Living Room TV Plug","ruleName":"device-64b7f1e6-schedule-abc123"},{"deviceId":"64b7f1e6f9c9d4e5b8a9f7c2","deviceName":"Kitchen MCB","ruleName":"device-64b7f1e6-schedule-def456"}]

actionValue

number

Optional value for actions that require it (e.g., temperature, brightness). All devices in this group will use the same value.

Example: 24

GroupedOneTimeSchedule

dateTime

string · date-time · required

Scheduled date and time when this one-time action will execute. Shared by all devices in this group.

Example: 2024-12-31T18:00:00Z

action

string · enum · required

Action type to perform at the scheduled date-time. All devices in this group will execute the same action.

Enum values:

OFF

SET_TEMPERATURE

SET_BRIGHTNESS

SET_MODE

TOGGLE_SMART_SWITCH

Example: OFF

deviceCount

number · required

Total number of devices that share this identical one-time schedule configuration.

Example: 10

DeviceScheduleInfo[] · required

Array of device details with their EventBridge rule names. Each device has this same one-time schedule configured.

actionValue

number

Optional value for actions that require it (e.g., temperature, brightness). All devices in this group will use the same value.

Example: 24

GetSystemGroupedSchedulesDto

GroupedRecurringSchedule[] · required

Array of recurring weekly schedules grouped by time and action. Shows which devices share the same recurring schedule pattern.

GroupedOneTimeSchedule[] · required

Array of one-time schedules grouped by date-time and action. Shows which devices share the same one-time schedule.

totalDevices

number · required

Total count of all schedulable devices in the system (includes devices with and without schedules). Only counts device types that support scheduling.

Example: 100

devicesWithSchedules

number · required

Count of devices that have at least one active schedule configured. Used to calculate scheduling adoption rate.

Example: 75

SuggestionFilter

string · enum

Enum values:

ready

all

AdjustmentType

string · enum

Enum values:

extend_start

extend_end

fill_gap

add_block

shrink_block

split_block

Type of adjustment suggested

DayOfWeek

string · enum

Enum values:

monday

tuesday

wednesday

thursday

friday

saturday

sunday

Which day(s) this adjustment applies to

OverrideAction

string · enum

Enum values:

OFF

What user did

ScheduleMapDto

DailyScheduleEntryDto[] · required

Monday schedule entries

DailyScheduleEntryDto[] · required

Tuesday schedule entries

DailyScheduleEntryDto[] · required

Wednesday schedule entries

DailyScheduleEntryDto[] · required

Thursday schedule entries

DailyScheduleEntryDto[] · required

Friday schedule entries

DailyScheduleEntryDto[] · required

Saturday schedule entries

DailyScheduleEntryDto[] · required

Sunday schedule entries

ScheduleAdjustmentStatus

string · enum

Enum values:

monitoring

ready_for_review

ready_for_auto_apply

pending

accepted

rejected

auto_applied

auto_apply_failed

Status of this suggestion

ScheduleAdjustmentSuggestionDto

_id

string · required

Suggestion ID

Example: 65a1b2c3d4e5f6a7b8c9d0e1

device

string · required

Device ID

Example: 65a1b2c3d4e5f6a7b8c9d0e2

deviceType

string · enum · required

Device type

Enum values:

PLUG

MCB

ENV_SENSOR

SMART_SWITCH

AIRCON_CONTROL

WATER_METER

RIDGE

Example: PLUG

system

string · required

System ID

Example: 65a1b2c3d4e5f6a7b8c9d0e3

adjustmentType

string · enum · required

Type of adjustment suggested

Enum values:

extend_start

extend_end

fill_gap

add_block

shrink_block

split_block

Example: extend_start

affectedDays

DayOfWeek[] · required

Which day(s) this adjustment applies to

Enum values:

monday

tuesday

wednesday

thursday

friday

saturday

sunday

Example: ["monday","tuesday","wednesday","thursday","friday"]

overrideTime

string · required

Time when user triggered this override

Example: 08:15

overrideAction

string · enum · required

What user did

Enum values:

OFF

Example: ON

object · required

Current schedule before adjustment

object · required

Suggested adjusted schedule

status

string · enum · required

Status of this suggestion

Enum values:

monitoring

ready_for_review

ready_for_auto_apply

pending

accepted

rejected

auto_applied

auto_apply_failed

Example: monitoring

occurrenceCount

number · required

Number of times this pattern was detected

Example: 5

firstOccurrence

string · date-time · required

First time this pattern was detected

Example: 2024-02-08T08:12:00.000Z

lastOccurrence

string · date-time · required

Most recent time this pattern was detected

Example: 2024-02-13T08:18:00.000Z

occurrenceTimes

string[] · required

All override times that contributed to this pattern

Example: ["08:12","08:17","08:20","08:15","08:18"]

earliestOverrideTime

string · required

Earliest time from all occurrences (used for adjustment)

Example: 08:12

latestOverrideTime

string · required

Latest time from all occurrences

Example: 08:20

timeRangeMinutes

number · required

Time range in minutes (latest - earliest)

Example: 8

confidenceScore

number · required

Confidence score 0-1 based on occurrences and time range

Example: 0.85

createdAt

string · date-time · required

When this suggestion was created

Example: 2024-02-08T08:12:00.000Z

updatedAt

string · date-time · required

When this suggestion was last updated

Example: 2024-02-13T08:18:00.000Z

deviceName

string

Device name

Example: Living Room AC

roomName

string

Room name the device belongs to

Example: Living Room

reviewedAt

string · date-time

When user responded to this

Example: 2024-02-13T10:30:00.000Z

reviewedByUser

string

User who reviewed this

Example: 65a1b2c3d4e5f6a7b8c9d0e4

estimatedHoursSavedPerWeek

number

Estimated hours saved per week if suggestion is applied (based on schedule diff across affected days)

Example: 1.5

estimatedKwhSavedPerWeek

number

Estimated kWh saved per week based on recent 14-day average daily usage

Example: 0.62

estimatedCostSavedPerWeek

number

Estimated cost saved per week in dollars

Example: 0.18

GetSystemSuggestionsResponseDto

total

number · required

Total number of suggestions

Example: 10

ScheduleAdjustmentSuggestionDto[] · required

Suggestions currently being monitored (below threshold)

ScheduleAdjustmentSuggestionDto[] · required

Suggestions ready for manual review (hit threshold)

ScheduleAdjustmentSuggestionDto[] · required

Suggestions ready for auto-apply on next toggle

ScheduleAdjustmentSuggestionDto[] · required

Suggestions that were accepted and applied

ScheduleAdjustmentSuggestionDto[] · required

Suggestions that were rejected

ScheduleAdjustmentSuggestionDto[] · required

Suggestions that were automatically applied

ScheduleAdjustmentSuggestionDto[] · required

Suggestions where auto-apply failed

GetDeviceSuggestionsResponseDto

total

number · required

Total number of suggestions

Example: 3

ScheduleAdjustmentSuggestionDto[] · required

List of suggestions for the device

AcceptSuggestionResponseDto

message

string · required

Success message

Example: Suggestion accepted and applied successfully

object · required

The accepted suggestion

deviceId

string · required

Device ID

deviceName

string · required

Device name

RejectSuggestionResponseDto

message

string · required

Success message

Example: Suggestion rejected successfully

object · required

The rejected suggestion

InvoiceItemDto

product

string · required

Reference to the product ID

Example: 64b7f1e6f9c9d4e5b8a9f7c3

quantity

number · required

Quantity purchased

Example: 3

CreateInvoiceDto

dueDate

string · required

Due date for the invoice

Example: 2026-01-05T12:00:00Z

InvoiceItemDto[] · required

Array of invoice line items

systemId

string

System ID associated with the invoice

Example: 64b7f1e6f9c9d4e5b8a9f7c3

tenantId

string

Tenant ID associated with the invoice

Example: 64b7f1e6f9c9d4e5b8a9f7c3

invoiceDate

string

Invoice date (defaults to current date)

Example: 2025-12-05T12:00:00Z

taxRate

number

Tax rate as a percentage (e.g., 10 for 10%)

Example: 10

discountAmount

number

Discount amount applied to the invoice

Example: 10

notes

string

Additional notes

Example: Thank you for your business

BillingType

string · enum

Enum values:

TENANT

ZONE

USER

InvoiceStatus

string · enum

Enum values:

PENDING

PAID

OVERDUE

CANCELED

Current payment status

Product

_id

string · required

The unique identifier of the subscription tier

Example: 64b7f1e6f9c9d4e5b8a9f7c3

price

number · required

Price of product

Example: 9.99

name

string · enum · required

Name of product

Enum values:

PLUG

MCB

ENV_SENSOR

SMART_SWITCH

AIRCON_CONTROL

WATER_METER

RIDGE

API_CALL

description

string · required

Description of the product

Example: A smart plug that can be controlled remotely

createdAt

string · date-time · required

The date when the product was created

Example: 2023-08-01T12:00:00Z

updatedAt

string · date-time · required

The date when the product was last updated

Example: 2023-08-01T12:00:00Z

SystemInvoiceItem

object · required

Reference to the product

Example: 64b7f1e6f9c9d4e5b8a9f7c3

quantity

number · required

Quantity purchased

Example: 3

SystemInvoice

_id

string · required

billingType

string · enum · required

Enum values:

TENANT

ZONE

USER

Example: TENANT

system

string · required

System ID reference

invoiceNumber

string · required

Unique invoice number for tracking and reference

Example: INV-2026-01-001

invoiceDate

string · date-time · required

Invoice date

Example: 2026-01-01T00:00:00Z

dueDate

string · date-time · required

Due date for payment

Example: 2026-01-31T23:59:59Z

subtotal

number · required

Subtotal before tax

Example: 100

taxRate

number · required

Tax rate percentage

Example: 9

tax

number · required

Tax amount (subtotal x taxRate / 100)

Example: 9

total

number · required

Final total amount

Example: 109

status

string · enum · required

Current payment status

Enum values:

PENDING

PAID

OVERDUE

CANCELED

Example: PENDING

isDeleted

boolean · required

Soft delete flag

Example: false

createdAt

string · date-time · required

updatedAt

string · date-time · required

SystemInvoiceItem[] · required

Array of invoice line items

discount

number · required

Discount amount

Example: 10

notes

string · required

Additional notes

Example: Thank you for your business

tenant

string

Tenant ID reference

zone

string

user

string

UpdateInvoiceDiscountDto

discountAmount

number · required

Discount amount to be applied to the invoice

Example: 50

UpdateInvoiceStatusDto

status

string · enum · required

New status of the invoice

Enum values:

PENDING

PAID

OVERDUE

CANCELED

Example: PAID

UpdateInvoiceNotesDto

notes

string · maxLength: 1000 · required

Notes for the invoice

Example: Payment received via bank transfer. Reference: TXN123456

InvoiceItemInput

product

string · required

Reference to the product ID

Example: 64b7f1e6f9c9d4e5b8a9f7c3

quantity

number · required

Quantity purchased

Example: 5

UpdateInvoiceItemsDto

InvoiceItemInput[] · required

Array of invoice items to replace the existing items list. Each item requires a product ID and quantity.

Example: [{"product":"64b7f1e6f9c9d4e5b8a9f7c3","quantity":5},{"product":"64b7f1e6f9c9d4e5b8a9f7c4","quantity":10}]

TriggerInvoiceGenerationDto

systemId

string · required

System ID to generate invoice for

Example: 64b7f1e6f9c9d4e5b8a9f7c3

from

string · date-time · required

Start of billing period

Example: 2025-11-01T00:00:00Z

to

string · date-time · required

End of billing period

Example: 2025-11-30T23:59:59Z

taxRate

number

Tax rate percentage (0-100)

Example: 8

Default: 0

GenerateInvoiceResultDto

systemId

string · required

System ID for which the invoice was generated

Example: 64b7f1e6f9c9d4e5b8a9f7c3

systemName

string · required

System name

Example: National University of Singapore

success

boolean · required

Whether invoice generation was successful

Example: true

plugCount

number · required

Number of plugs billed

Example: 10

apiCallCount

number · required

Number of API calls billed

Example: 500

object

Generated invoice (if successful)

error

string

Error message (if failed)

Example: No billable items found for this system

TriggerBulkInvoiceGenerationDto

taxRate

number

Tax rate percentage (0-100)

Example: 8

Default: 0

BulkInvoiceGenerationResultDto

totalSystems

number · required

Total number of systems processed

Example: 10

GenerateInvoiceResultDto[] · required

Results for each system

billingPeriodStart

string · date-time · required

Billing period start date

Example: 2025-11-01T00:00:00Z

billingPeriodEnd

string · date-time · required

Billing period end date

Example: 2025-11-30T23:59:59Z

executedAt

string · date-time · required

Timestamp when the cron job ran

Example: 2025-12-01T00:00:00Z

CreateBillingConfigDto

billingType

string · enum · required

Enum values:

TENANT

ZONE

USER

Example: TENANT

tariffRate

number · required

Price per kWh

Example: 0.25

billingDay

number · required

Day of month to auto-generate invoice (1-28)

Example: 1

billingEmail

string · required

Email address for invoice PDF delivery

Example: billing@acme.com

tenantId

string

Tenant ID (required if billingType is TENANT)

Example: 64b7f1e6f9c9d4e5b8a9f7c3

zoneId

string

Zone ID (required if billingType is ZONE)

Example: 64b7f1e6f9c9d4e5b8a9f7c3

userId

string

User ID (required if billingType is USER)

Example: 64b7f1e6f9c9d4e5b8a9f7c3

replyTo

string

Reply-to email for invoice emails. Replies go to this address.

Example: admin@ecovolt.ai

UpdateBillingConfigDto

tariffRate

number

billingDay

number

billingEmail

string

replyTo

string

Reply-to email for invoice emails. Replies go to this address.

Example: admin@ecovolt.ai

isActive

boolean

BillingConfig

_id

string · required

billingType

string · enum · required

Enum values:

TENANT

ZONE

USER

Example: TENANT

system

string · required

tariffRate

number · required

Price per kWh

Example: 0.25

billingDay

number · required

Day of month (1-28) to auto-generate invoice

Example: 1

billingEmail

string · required

Email address to receive the invoice PDF

Example: billing@acme.com

isActive

boolean · required

isDeleted

boolean · required

createdAt

string · date-time · required

updatedAt

string · date-time · required

tenant

string

zone

string

user

string

replyTo

string

Reply-to email for invoice emails. Replies go to this address.

Example: admin@ecovolt.ai

scheduleName

string

AWS EventBridge schedule name for automated monthly billing

Example: monthly_billing_tenant_64b7f1e6_day_15_prod

EnergyInvoice

_id

string · required

billingType

string · enum · required

Enum values:

TENANT

ZONE

USER

Example: TENANT

system

string · required

System ID reference

invoiceNumber

string · required

Unique invoice number for tracking and reference

Example: INV-2026-01-001

invoiceDate

string · date-time · required

Invoice date

Example: 2026-01-01T00:00:00Z

dueDate

string · date-time · required

Due date for payment

Example: 2026-01-31T23:59:59Z

subtotal

number · required

Subtotal before tax

Example: 100

taxRate

number · required

Tax rate percentage

Example: 9

tax

number · required

Tax amount (subtotal x taxRate / 100)

Example: 9

total

number · required

Final total amount

Example: 109

status

string · enum · required

Current payment status

Enum values:

PENDING

PAID

OVERDUE

CANCELED

Example: PENDING

isDeleted

boolean · required

Soft delete flag

Example: false

createdAt

string · date-time · required

updatedAt

string · date-time · required

billingPeriodFrom

string · date-time · required

Billing period start date

Example: 2026-01-01T00:00:00Z

billingPeriodTo

string · date-time · required

Billing period end date

Example: 2026-01-31T23:59:59Z

totalKwh

number · required

Total energy consumption in kWh during billing period

Example: 150.5

tariffRate

number · required

Tariff rate applied at time of billing (price per kWh)

Example: 0.25

currency

string · required

Currency code (automatically derived from system country code)

Example: SGD

emailSent

boolean · required

Whether invoice email with PDF attachment was successfully sent

Example: false

tenant

string

Tenant ID reference

zone

string

user

string

TriggerBillingDto

entityId

string · required

ID of the entity to bill (tenant ID, zone ID, or user ID)

Example: 64b7f1e6f9c9d4e5b8a9f7c3

billingPeriodFrom

string · required

Start of billing period (ISO date)

Example: 2026-01-01

billingPeriodTo

string · required

End of billing period (ISO date)

Example: 2026-01-31

dueDate

string · required

Invoice due date (ISO date).

Example: 2026-02-28

taxRate

number

Tax rate percentage (0 = no tax)

Example: 9

Default: 0

replyTo

string

Reply-to email address for the invoice. Replies go to this address.

Example: admin@ecovolt.ai

TriggerBillingResponseDto

entityId

string · required

ID of the entity (tenant/zone/user) that was billed

Example: 64b7f1e6f9c9d4e5b8a9f7c3

entityName

string · required

Name of the entity that was billed

Example: Acme Corporation

success

boolean · required

Whether the billing operation was successful

Example: true

totalKwh

number

Total energy consumption in kWh for the billing period

Example: 150.5

totalAmount

number

Total amount billed in the configured currency

Example: 41.01

emailSent

boolean

Whether the invoice email was sent successfully

Example: true

error

string

Error message if the operation failed

Example: No usage data found for billing period

ApiTokenAudience

string · enum

Enum values:

system

tenant

consumer

Audience of the token. System (default) reaches every API-token endpoint; Consumer is restricted to consumer-scoped (zone and below) endpoints.

CreateApiTokenDto

audience

string · enum

Audience of the token. System (default) reaches every API-token endpoint; Consumer is restricted to consumer-scoped (zone and below) endpoints.

Enum values:

system

tenant

consumer

Default: system

ApiTokenResponseDto

token

string · required

Api token string for accessing external APIs

Example: 5cb691c114052d0746daade10116a04b0bf16853364843984ed5022ad08001a12d0e1aae72e285bb8a187e28a24dd7f326ef6d28204f7fbbe96d08dfbc4368b90097b5f3f315458e7f83c9ff0a5405565bcb04d19dfd9fc6d2c3d709f73ca43c

GetSystemDetailsDto

_id

string · required

Unique identifier of the system in the database.

Example: 64b7f1e6f9c9d4e5b8a9f7c1

systemName

string · required

Name of the system. Typically represents an organization, building, or facility using the Ecovolt platform.

Example: National University of Singapore

numberOfDevices

number · required

Total number of devices in the system.

Example: 12

deviceOnCount

number · required

Number of devices currently reporting ON.

Example: 7

deviceOffCount

number · required

Number of devices currently reporting OFF.

Example: 3

deviceInactiveCount

number · required

Number of devices that are currently inactive.

Example: 2

GetAdminDto

_id

string · required

Unique identifier of the admin account in the database.

Example: 64b7f1e6f9c9d4e5b8a9f7c1

name

string · required

Full name of the admin user. Used for identification and display purposes.

Example: Glenn Quah Han Rong

email

string · required

Email address of the admin user. Used for authentication and notifications.

Example: glenn@ecovolt.com

role

string · enum · required

Administrative role determining the level of access and permissions within the system.

Enum values:

SUPERADMIN

ADMIN

USER

TENANT

ROOM

Example: SUPERADMIN

GetSystemDetailsDto[] · required

Array of systems that are linked to and managed by this admin. Includes full system details for each linked system.

approved

boolean · required

Indicates whether the admin account has been approved by a superadmin.

Example: true

createdAt

string · date-time · required

Timestamp when the admin account was created in the system.

Example: 2024-10-15T08:30:00Z

updatedAt

string · date-time · required

Timestamp when the admin account was last modified.

Example: 2024-10-15T14:45:00Z

pending

boolean · required

Indicates whether the admin account is awaiting approval. True if not yet approved.

Example: false

mainSystemId

string · required

Main system ID, typically the first system in the systems array. Used as the default system for the admin.

Example: 64b7f1e6f9c9d4e5b8a9f7c4

associatedUserId

string

Reference to the associated User ID if this admin account is linked to a specific user.

Example: 64b7f1e6f9c9d4e5b8a9f7c5

associatedTenantId

string

Reference to the associated Tenant ID if this admin account is linked to a specific tenant.

Example: 64b7f1e6f9c9d4e5b8a9f7c6

associatedRoomId

string

Reference to the associated Room ID if this admin account is linked to a specific room.

Example: 64b7f1e6f9c9d4e5b8a9f7c7

enable2FA

boolean

Indicates whether two-factor authentication is enabled for this admin account.

Example: false

ApiTokenGeneratedByResponseDto

admin

string · required

GetAdminDto ID reference

ApiTokenUsageDto

_id

string · required

Primary ID of the ApiTokenUsage

Example: 64b7f1e6f9c9d4e5b8a9f7c3

url

string · required

URL accessed using the API token

Example: /api/v1/plug/system/60b7f1e6f9c9d4e5b8a9f7c3

method

string · enum · required

HTTP method used with the API token

Enum values:

GET

POST

PUT

DELETE

PATCH

HEAD

OPTIONS

createdAt

string · date-time · required

Date when the usage was recorded

Example: 2023-10-01T12:00:00Z

updatedAt

string · date-time · required

Date when the usage was last updated

Example: 2023-10-01T12:00:00Z

ApiTokenUsageSearchResultDto

ApiTokenUsageDto[] · required

Array of API token usage records

total

number · required

Total number of matching records

Example: 150

GetApiTokenDto

_id

string · required

Primary ID of the API token

Example: 64b7f1e6f9c9d4e5b8a9f7c3

systemId

string · required

System ID associated with the API token

Example: 64b7f1e6f9c9d4e5b8a9f7c4

GetApiTokenWithUsageDto

_id

string · required

Primary ID of the API token

Example: 64b7f1e6f9c9d4e5b8a9f7c3

admin

string · required

GetAdminDto ID reference

systemId

string · required

System ID associated with the API token

Example: 64b7f1e6f9c9d4e5b8a9f7c4

systemName

string · required

System name associated with the API token

Example: Production System

usageCount

number · required

Number of times this API token has been used

Example: 42

createdAt

string · date-time · required

Date when the API token was created

Example: 2023-10-01T12:00:00Z

updatedAt

string · date-time · required

Date when the API token was last updated

Example: 2023-10-01T12:00:00Z

GetAdminsDto

admins

string[] · required

Array of GetAdminDto IDs

total

number · required

Total count of admin accounts in the database. Used for pagination calculations.

Example: 25

UpdateAdminRoleDto

role

string · required

The new administrative role to assign to the admin. Determines the level of access and permissions within the system.

Example: ADMIN

associatedZone

string

Optional zone ID to associate this admin with a specific zone account

Example: 64b7f1e6f9c9d4e5b8a9f7c4

associatedTenant

string

Optional tenant ID to associate this admin with a specific tenant

Example: 64b7f1e6f9c9d4e5b8a9f7c3

associatedRoom

string

Optional room ID to associate this admin with a specific room

Example: 64b7f1e6f9c9d4e5b8a9f7c2

UpdateAdminDto

name

string

Full name of the admin user. Used for identification and display purposes within the system.

Example: Glenn Quah Han Rong

email

string

Email address of the admin user. Used for authentication and system notifications.

Example: glenn@ecovolt.com

password

string

New password for the admin account. Must be at least 6 characters long and will be hashed before storage.

Example: SecurePass123!

role

string

Administrative role determining the level of access and permissions within the system.

Example: SUPERADMIN

LinkSystemToAdminDto

systemId

string · required

Unique identifier of the system to be linked to the admin account. This establishes a management relationship between the admin and the system.

Example: 64b7f1e6f9c9d4e5b8a9f7c1

UnlinkSystemToAdminDto

systemId

string · required

Unique identifier of the system to be unlinked from the admin account. This removes the management relationship between the admin and the system.

Example: 64b7f1e6f9c9d4e5b8a9f7c1

CreateZoneDto

name

string · required

Full name of the zone to be registered in the system. This will be displayed across the application.

Example: Zone A - Engineering Wing

adminCreation

boolean · required

Flag indicating whether an tenant admin should be created, if so send invite.

email

string

Unique email address for the zone account. Required when adminCreation is true. Must not already exist in the system and will be used for authentication.

Example: zone-a@gmail.com

remarks

string

Optional administrative notes or comments about the zone. Used for internal documentation and context.

Example: Department head - Engineering

zoneType

string

Zone type key. Must be a valid type defined for this system via /entity-type/ZONE.

Example: LABORATORY

LinkMultiplePlugsDto

plugIds

string[] · required

Array of plug identifiers to link to the zone. Used when assigning multiple plugs to a zone at once.

Example: ["64b7f1e6f9c9d4e5b8a9f7c1","64b7f1e6f9c9d4e5b8a9f7c2"]

GetZonesResponseDto

total

number · required

Total count of items matching filters

Example: 150

page

number · min: 1 · required

Current page number

Example: 1

size

number · min: 1 · required

Items per page

Example: 50

totalPages

number · min: 0 · required

Total number of pages

Example: 3

GetZoneDto[] · required

Array of zone objects matching the query criteria

UpdateZoneDto

name

string

Updated full name for the zone. This will replace the existing name in the system.

Example: Zone B - Updated Wing

email

string

Updated email address for the zone. Must be unique and not already in use by another account.

Example: updated-zone@example.com

tenantId

string

Updated tenant identifier to reassign the zone to a different organization.

Example: 64b7f1e6f9c9d4e5b8a9f7c1

remarks

string

Updated administrative notes or comments about the zone. Replaces existing remarks if provided.

Example: Promoted to senior engineer

zoneType

string

Zone type key. Must be a valid type defined for this system via /entity-type/ZONE.

Example: LABORATORY

MigratePlugDto

targetPlugId

string · required

The ID of the target plug

sourcePlugId

string · required

The ID of the source plug

hasPreviousSetup

boolean

Indicates if the source plug has previous setup

EcoguardPlug

_id

string · required

Primary ID of the EcoGuard

Example: 64b7f1e6f9c9d4e5b8a9f7c3

ecoguardEnabled

boolean · required

Ecoguard Timer

Example: true

ecoguardTimer

number · required

Idle Timeout Duration of the Ecoguard (Minutes)

ecoguardIdleThreshold

number · required

Ecoguard Idle Threshold

Example: 60000

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

PlugUpdateItem

plugId

string · required

MongoDB ID of the plug to update

Example: 64b7f1e6f9c9d4e5b8a9f7c3

plugCategory

string

Category of the device connected to this plug. See GET /plug-category for valid values.

Example: CHARGER

deviceBrand

string

Brand of the device connected to this plug

Example: Novita

deviceModel

string

Model of the device connected to this plug

Example: ND-195

remarks

string

Additional remarks or notes about the plug

Example: Water dispenser appliance

BulkUpdatePlugsDto

PlugUpdateItem[] · required

Array of plug update operations to perform in a single batch

Example: [{"plugId":"64b7f1e6f9c9d4e5b8a9f7c3","plugCategory":"CHARGER","deviceBrand":"Novita","deviceModel":"ND-195","remarks":"Water dispenser appliance"}]

AiCategorizePlugsRequestDto

plugIds

string[] · minItems: 1 · maxItems: 100 · required

Array of plug IDs to categorize using AI

Example: ["507f1f77bcf86cd799439011","507f1f77bcf86cd799439012"]

UpdatePlugDto

deviceName

string

Name of the device

Example: Living Room Light

location

string

Physical location of the device

Example: Block 123, Unit 01-23

remarks

string

Additional remarks or notes about the device

Example: Handle with care - critical equipment

tenantId

string

Tenant ID to associate the device with

Example: 64b7f1e6f9c9d4e5b8a9f7c3

zoneId

string

Zone ID to associate the device with

Example: 64b7f1e6f9c9d4e5b8a9f7c4

roomId

string

Room ID to associate the device with

Example: 64b7f1e6f9c9d4e5b8a9f7c5

isLocked

boolean

Whether the device is locked. When locked, the device cannot be toggled ON/OFF.

Example: false

isSpare

boolean

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

Example: false

plugType

string

Type of Plug

Example: SOAPBAR

plugCategory

string

Type of Plug Category

Example: CHARGER

deviceModel

string

Model identifier of the Plug

Example: TP-Link HS110

deviceBrand

string

Brand of the Plug device

Example: TP-Link

batchNumber

number

Batch Number of the Plug

Example: 23

FilteredPlugDto

_id

string · required

Unique database identifier of the device document in the system

Example: 64b7f1e6f9c9d4e5b8a9f7c3

macId

string · required

Unique identifier assigned to the device by the IoT hardware (MAC ID)

Example: 1092384701928347

deviceName

string · required

Friendly name for the device for easy identification

Example: Living Room AC

onStatus

string · enum · required

Current operational status of the device (ON, OFF, INACTIVE, or ERROR)

Enum values:

OFF

INACTIVE

ERROR

ACTIVE

Example: ON

totalEnergyUsage

number · required

Cumulative total energy consumption in kilowatt-hours (kWh) since device installation

Example: 500

tenantId

string · required

Unique identifier of the tenant organization that owns this device

Example: 64b7f1e6f9c9d4e5b8a9f7c4

tenantName

string · required

Name of the tenant organization that owns this device

Example: Faculty of Engineering

zoneId

string · required

Unique identifier of the zone that this device is assigned to

Example: 64b7f1e6f9c9d4e5b8a9f7c5

zoneName

string · required

Name of the zone that this device is assigned to

Example: Zone A

roomId

string · required

Unique identifier of the room where this device is physically located

Example: 64b7f1e6f9c9d4e5b8a9f7c6

roomName

string · required

Name of the room where this device is physically located

Example: Room 101

dbId

string · required

Unique identifier of the distribution box that this device is connected to (for MCBs)

Example: 64b7f1e6f9c9d4e5b8a9f7c7

dbName

string · required

Name of the distribution box that this device is connected to (for MCBs)

Example: Main Distribution Box

systemId

string · required

Unique identifier of the system that this device belongs to

Example: 64b7f1e6f9c9d4e5b8a9f7c3

systemName

string · required

Name of the system that this device belongs to

Example: NUS Engineering Building

realTimePower

number · required

Real-time power consumption in watts (W) measured by the device

Example: 115

realTimeCurrent

number · required

Real-time current draw in amperes (A) measured by the device

Example: 0.5

ssid

string · required

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

Example: XH001

plugType

string · enum · required

Hardware type classification of the plug device (e.g., ADAPTER, EXTENSION)

Enum values:

SOCKET

SOAPBAR

ADAPTER

Example: ADAPTER

plugCategory

string · required

Category classification for the connected device type. See GET /plug-category for valid values.

Example: CHARGER

targetState

string · enum

Pending desired on/off state commanded by backend. Present when a toggle was issued but the device has not yet acknowledged (e.g. issued while INACTIVE). Frontend can derive a "Pending" indicator when this differs from onStatus.

Enum values:

OFF

INACTIVE

ERROR

ACTIVE

Example: ON

targetStateSetAt

string · date-time

Timestamp when the pending targetState was last written.

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

deviceNumber

number

Auto-incremented sequential number for tracking device registration order

Example: 3

batchNumber

number

Manufacturing batch number for tracking production groups and quality control

Example: 23

chipModel

string · enum

Hardware chip model identifier used in the device (e.g., ESP32C2, ESP8266)

Enum values:

ESP8266

ESP32C2

ESP32C5

ESP32

ESP32C3

versionNumber

string

Firmware version number currently running on the device

Example: 1.0.0

object

Weekly and one-time schedule configuration for automated device control

lastSeen

string · date-time

Timestamp when the device last communicated with the system

Example: 2024-10-15T12:30:00.000Z

isLocked

boolean

Lock status indicating if the device is locked

Example: false

inactivityNotificationEnabled

boolean

Whether inactivity notifications are enabled for this device

Example: false

object

Ecoguard power-saving feature configuration and settings for this plug

GetPlugsResponseDto

total

number · required

Total count of items matching filters

Example: 150

page

number · min: 1 · required

Current page number

Example: 1

size

number · min: 1 · required

Items per page

Example: 50

totalPages

number · min: 0 · required

Total number of pages

Example: 3

FilteredPlugDto[] · required

Array of plug device objects matching the query criteria

PlugCategoryEnergyBreakdownDto

plugCategory

string · required

Category classification of the plug device. See GET /plug-category for valid values.

Example: CHARGER

totalEnergyUsage

number · required

Total energy usage (kWh) for all plugs in this category

Example: 342.5

PlugCategoriesBreakdownDto

plugCategory

string · required

Category classification of the plug device. See GET /plug-category for valid values.

Example: CHARGER

count

number · required

Total count of plugs belonging to this specific category in the system

Example: 23

CreateEcoguardPlugDto

ecoguardEnabled

boolean · required

Enable or disable the Ecoguard automatic power-off feature for idle detection. When enabled, the plug monitors power consumption.

Example: true

ecoguardTimer

number · required

Duration in minutes before the plug automatically turns off after detecting idle power usage. Applied when power stays below threshold.

Example: 30

ecoguardIdleThreshold

number · required

Power consumption threshold in watts that defines idle state. When usage falls below this value, the idle timer starts counting.

Example: 5

MCBPoles

string · enum

Enum values:

UNREGISTERED

SINGLE_POLE

DOUBLE_POLE

THREE_POLE

FOUR_POLE

Number of poles in the MCB

SandboxDevice

id

string · required

Unique identifier for the sandbox device

Example: sandbox-device-1

type

string · enum · required

Type of sandbox device

Enum values:

DUMB_MCB

RCCB

Example: DUMB_MCB

name

string · required

User-defined name for the device

Example: Kitchen Lights

digitalTwinX

number · required

X position on the digital twin canvas

Example: 400

rowLine

number · required

Row line position (1-6)

Example: 2

ratedCurrent

number

Rated current in amperes

Example: 16

ratedVoltage

number

Rated voltage in volts

Example: 230

mcbType

string · enum

MCB type (for DUMB_MCB devices)

Enum values:

UNREGISTERED

SWITCH

BUILT_IN

COIL

COIL3P

Example: BUILT_IN

mcbPoles

string · enum

MCB poles configuration (for DUMB_MCB devices)

Enum values:

UNREGISTERED

SINGLE_POLE

DOUBLE_POLE

THREE_POLE

FOUR_POLE

Example: SINGLE_POLE

leakageCurrent

number

Leakage current in milliamperes (for RCCB devices)

Example: 30

color

string

Custom color for visual identification

Example: #94a3b8

notes

string

Additional notes about the device

Example: Connected to kitchen circuit

WireConnection

deviceId

string · required

Device ID (MCB._id or SandboxDevice.id)

Example: sandbox-device-1

deviceType

string · enum · required

Type of device being connected

Enum values:

SMART_MCB

DUMB_MCB

RCCB

Example: DUMB_MCB

side

string · enum · required

Side of the device where the connection is made

Enum values:

LEFT

RIGHT

TOP

BOTTOM

Example: LEFT

SandboxWire

id

string · required

Unique identifier for the wire connection

Example: wire-1

object · required

Source connection point

object · required

Target connection point

color

string

Wire color (hex code)

Example: #fbbf24

Default: #fbbf24

thickness

number

Wire thickness in pixels

Example: 3

Default: 3

label

string

Optional label for the wire

Example: Phase 1

DistributionBox

_id

string · required

Primary ID of the Distribution Box

Example: 64b7f1e6f9c9d4e5b8a9f7c3

name

string · required

Name/identifier of the Distribution Box

Example: Main DB Box - Floor 1

system

string · required

System to which this distribution box belongs

Example: 64b7f1e6f9c9d4e5b8a9f7c3

createdAt

string · date-time · required

Date and time when the distribution box was created

updatedAt

string · date-time · required

Date and time when the distribution box was last updated

boxNumber

number

Unique box number for identification within a system

Example: 1

numberOfRows

number

Number of rows in the distribution box

Example: 1

mcbs

string[]

Array of MCB IDs or partially populated MCB objects (_id, deviceName, macId, onStatus)

Example: ["64b7f1e6f9c9d4e5b8a9f7c3"]

hasMainBreaker

boolean

Whether the distribution box has a main circuit breaker

Example: true

mainBreakerRating

number

Main breaker rating in amperes (if hasMainBreaker is true)

Example: 63

location

string

Physical location where the distribution box is installed

Example: Ground Floor, Electrical Room

remarks

string

Additional remarks or notes about the distribution box

Example: Main distribution panel installed in 2024

tenant

string

Tenant to which this distribution box belongs

Example: 64b7f1e6f9c9d4e5b8a9f7c4

zone

string

Zone to which this distribution box belongs

Example: 64b7f1e6f9c9d4e5b8a9f7c5

room

string

Room where this distribution box is located

Example: 64b7f1e6f9c9d4e5b8a9f7c6

SandboxDevice[]

Array of sandbox (non-smart) devices in the distribution box

SandboxWire[]

Array of wire connections between devices in the distribution box

digitalTwinWidth

number

Width of the digital twin canvas in pixels

Example: 1200

digitalTwinHeight

number

Height of the digital twin canvas in pixels

Example: 800

singleLineDiagramKey

string

S3 key for the single line diagram image

Example: single-line-diagrams/abc123-def456.png

singleLineDiagramUrl

string

CDN URL for the single line diagram image

Example: https://cdn.example.com/single-line-diagrams/abc123-def456.png

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

FilteredMcbDto

_id

string · required

Unique database identifier of the device document in the system

Example: 64b7f1e6f9c9d4e5b8a9f7c3

macId

string · required

Unique identifier assigned to the device by the IoT hardware (MAC ID)

Example: 1092384701928347

deviceName

string · required

Friendly name for the device for easy identification

Example: Living Room AC

onStatus

string · enum · required

Current operational status of the device (ON, OFF, INACTIVE, or ERROR)

Enum values:

OFF

INACTIVE

ERROR

ACTIVE

Example: ON

totalEnergyUsage

number · required

Cumulative total energy consumption in kilowatt-hours (kWh) since device installation

Example: 500

tenantId

string · required

Unique identifier of the tenant organization that owns this device

Example: 64b7f1e6f9c9d4e5b8a9f7c4

tenantName

string · required

Name of the tenant organization that owns this device

Example: Faculty of Engineering

zoneId

string · required

Unique identifier of the zone that this device is assigned to

Example: 64b7f1e6f9c9d4e5b8a9f7c5

zoneName

string · required

Name of the zone that this device is assigned to

Example: Zone A

roomId

string · required

Unique identifier of the room where this device is physically located

Example: 64b7f1e6f9c9d4e5b8a9f7c6

roomName

string · required

Name of the room where this device is physically located

Example: Room 101

dbId

string · required

Unique identifier of the distribution box that this device is connected to (for MCBs)

Example: 64b7f1e6f9c9d4e5b8a9f7c7

dbName

string · required

Name of the distribution box that this device is connected to (for MCBs)

Example: Main Distribution Box

systemId

string · required

Unique identifier of the system that this device belongs to

Example: 64b7f1e6f9c9d4e5b8a9f7c3

systemName

string · required

Name of the system that this device belongs to

Example: NUS Engineering Building

realTimePower

number · required

Real-time power consumption in watts (W) measured by the device

Example: 115

realTimeCurrent

number · required

Real-time current draw in amperes (A) measured by the device

Example: 0.5

ssid

string · required

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

Example: XH001

mcbType

string · enum · required

Type of MCB (trip curve type)

Enum values:

UNREGISTERED

SWITCH

BUILT_IN

COIL

COIL3P

Example: BUILT_IN

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

targetState

string · enum

Enum values:

OFF

INACTIVE

ERROR

ACTIVE

Example: ON

targetStateSetAt

string · date-time

Timestamp when the pending targetState was last written.

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

deviceNumber

number

Auto-incremented sequential number for tracking device registration order

Example: 3

batchNumber

number

Manufacturing batch number for tracking production groups and quality control

Example: 23

chipModel

string · enum

Hardware chip model identifier used in the device (e.g., ESP32C2, ESP8266)

Enum values:

ESP8266

ESP32C2

ESP32C5

ESP32

ESP32C3

versionNumber

string

Firmware version number currently running on the device

Example: 1.0.0

object

Weekly and one-time schedule configuration for automated device control

lastSeen

string · date-time

Timestamp when the device last communicated with the system

Example: 2024-10-15T12:30:00.000Z

isLocked

boolean

Lock status indicating if the device is locked

Example: false

inactivityNotificationEnabled

boolean

Whether inactivity notifications are enabled for this device

Example: false

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

ratedVoltage

number

Rated voltage in volts

Example: 230

realTimeVoltage

number

Real-time voltage in volts

Example: 230

powerFactor

number

Power factor (0-1)

Example: 0.95

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

isReversePower

boolean

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

Example: false

Default: false

GetMCBsResponseDto

total

number · required

Total count of items matching filters

Example: 150

page

number · min: 1 · required

Current page number

Example: 1

size

number · min: 1 · required

Items per page

Example: 50

totalPages

number · min: 0 · required

Total number of pages

Example: 3

FilteredMcbDto[] · required

List of MCBs with organizational hierarchy details

MCBNameSuggestionDto

mcbId

string · required

MCB ID

Example: 64b7f1e6f9c9d4e5b8a9f7c3

suggestedName

string · required

Suggested device name composed of Distribution Box name, Room name, and Measurement type

Example: DB-4-7U-5 | 4/7/E | Lights & Fans

distributionBoxName

string

Distribution Box name

Example: DB-4-7U-5

roomName

string

Room name

Example: 4/7/E

zoneName

string

Zone name

Example: Zone A

tenantName

string

Tenant name

Example: Tenant A

deviceNumber

number

Device number

Example: 1

GetBulkMCBNamesResponseDto

MCBNameSuggestionDto[] · required

Array of MCB IDs with their suggested names

MCBNameUpdateDto

mcbId

string · required

MCB ID

Example: 64b7f1e6f9c9d4e5b8a9f7c3

deviceName

string · required

New device name to save

Example: DB-4-7U-5 | 4/7/E | Lights & Fans

SaveBulkMCBNamesDto

MCBNameUpdateDto[] · required

Array of MCB ID and name pairs to save

Example: [{"mcbId":"64b7f1e6f9c9d4e5b8a9f7c3","deviceName":"DB-4-7U-5 | 4/7/E | Lights & Fans"},{"mcbId":"64b7f1e6f9c9d4e5b8a9f7c4","deviceName":"DB-4-7U-5 | 4/7/E | Aircon"}]

MCBUpdateDto

mcbId

string · required

MCB ID

Example: 64b7f1e6f9c9d4e5b8a9f7c3

ratedCurrent

number

Rated current capacity in amperes (1-100)

Example: 16

ratedVoltage

number

Rated voltage in volts

Example: 230

mcbPoles

string · enum

Number of poles in the MCB

Enum values:

UNREGISTERED

SINGLE_POLE

DOUBLE_POLE

THREE_POLE

FOUR_POLE

Example: SINGLE_POLE

mcbType

string · enum

Type of MCB

Enum values:

UNREGISTERED

SWITCH

BUILT_IN

COIL

COIL3P

Example: COIL

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

MassUpdateMCBDto

MCBUpdateDto[] · required

Array of MCB updates

Example: [{"mcbId":"64b7f1e6f9c9d4e5b8a9f7c3","ratedCurrent":16,"ratedVoltage":230,"mcbPoles":"SINGLE_POLE","mcbType":"COIL","measurementType":"SSO"},{"mcbId":"64b7f1e6f9c9d4e5b8a9f7c4","ratedCurrent":32,"mcbPoles":"DOUBLE_POLE"}]

UpdateMCBDto

deviceName

string

Name of the device

Example: Living Room Light

location

string

Physical location of the device

Example: Block 123, Unit 01-23

remarks

string

Additional remarks or notes about the device

Example: Handle with care - critical equipment

tenantId

string

Tenant ID to associate the device with

Example: 64b7f1e6f9c9d4e5b8a9f7c3

zoneId

string

Zone ID to associate the device with

Example: 64b7f1e6f9c9d4e5b8a9f7c4

roomId

string

Room ID to associate the device with

Example: 64b7f1e6f9c9d4e5b8a9f7c5

isLocked

boolean

Whether the device is locked. When locked, the device cannot be toggled ON/OFF.

Example: false

isSpare

boolean

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

Example: false

deviceNumber

number

Unique device number for identification

Example: 1

mcbType

string · enum

Type of MCB (trip curve type)

Enum values:

UNREGISTERED

SWITCH

BUILT_IN

COIL

COIL3P

Example: BUILT_IN

mcbPoles

string · enum

Number of poles in the MCB

Enum values:

UNREGISTERED

SINGLE_POLE

DOUBLE_POLE

THREE_POLE

FOUR_POLE

Example: SINGLE_POLE

measurementType

string · enum

Measurement type classification for energy usage categorization

Enum values:

SSO

LIGHTS_FANS

LIGHTS

FANS

AIRCON

POWER_OUTLETS

GENERAL

COMBINED

Example: AIRCON

onStatus

string · enum

Status of the MCB

Enum values:

OFF

INACTIVE

ERROR

ACTIVE

Example: ON

ratedCurrent

number

Rated current capacity in amperes

Example: 16

ratedVoltage

number

Rated voltage in volts

Example: 230

distributionBoxId

string

Distribution Box ID containing this MCB

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

MassMoveMCBsDistributionBoxDto

mcbIds

string[] · required

Array of MCB IDs to move to the new distribution box

Example: ["64b7f1e6f9c9d4e5b8a9f7c1","64b7f1e6f9c9d4e5b8a9f7c2"]

newDistributionBoxId

string

ID of the new distribution box to move the MCBs to. If null or undefined, MCBs will be unassigned from their current distribution box.

Example: 64b7f1e6f9c9d4e5b8a9f7c3

MCBPositionDto

mcbId

string · required

MCB ID

Example: 64b7f1e6f9c9d4e5b8a9f7c3

digitalTwinX

number · required

X coordinate for digital twin SVG positioning

Example: 150.5

rowLine

number · required

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

Example: 1

slotNumber

number

Slot/position number on the busbar

Example: 3

BulkUpdateMCBPositionsDto

MCBPositionDto[] · required

Array of MCB positions to update

Example: [{"mcbId":"64b7f1e6f9c9d4e5b8a9f7c3","digitalTwinX":150.5,"rowLine":1,"slotNumber":3},{"mcbId":"64b7f1e6f9c9d4e5b8a9f7c4","digitalTwinX":250.5,"rowLine":2,"slotNumber":4}]

SetReversePowerDto

isReversePower

boolean · required

Whether to enable reverse power mode. When true, negative power/current values are converted to positive (absolute values).

Example: true

SetReversePowerResponseDto

mcbId

string · required

The MCB ID that was updated

Example: 507f1f77bcf86cd799439011

isReversePower

boolean · required

The new reverse power status

Example: true

hourlyRecordsConverted

number · required

Number of hourly usage history records converted to absolute values

Example: 24

dailyRecordsConverted

number · required

Number of daily usage history records converted to absolute values

Example: 7

AirconControlIrType

string · enum

Enum values:

AIRCON

FAN

Type of IR device being controlled (AIRCON or FAN)

AirconControlFanBrand

string · enum

Enum values:

KDK_U48FP

KDK_U60FW

U60FWS

KDK_T60AW

T60AWS

Brand of the fan unit (only applicable when irType is FAN)

AirconControlSeriesType

string · enum

Enum values:

MAXWELL

MAXWELL_PRO

Series type — NORMAL (control only) or PRO (control + ambient temp/humidity sensing)

AirconControl

_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

isIRRemote

boolean · required

Whether this is an IR remote (true) or wired control (false)

Example: true

irType

string · enum · required

Type of IR device being controlled (AIRCON or FAN)

Enum values:

AIRCON

FAN

Example: AIRCON

Default: AIRCON

temperature

number · required

Temperature setting in degrees Celsius

Example: 24

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

Device[]

List of smart devices controlled by this aircon sensor

fanBrand

string · enum

Brand of the fan unit (only applicable when irType is FAN)

Enum values:

KDK_U48FP

KDK_U60FW

U60FWS

KDK_T60AW

T60AWS

Example: KDK_T60AW

fanSpeed

number

Fan speed setting (only applicable when irType is FAN)

Example: 1

brand

string · enum

Brand of the AC unit being controlled

Enum values:

DAIKIN

MITSUBISHI

PANASONIC

SAMSUNG

FUJITSU

TOSHIBA

SHARP

Example: DAIKIN

modelNumber

string

Manufacturer model number (e.g. FTKM50QV1M). Required for consumption estimation via AirconModelSpec lookup. Stored uppercased and trimmed.

Example: FTKM50QV1M

mode

string · enum

AC operation mode (COOL, HEAT, DRY, FAN, AUTO)

Enum values:

COOL

HEAT

DRY

FAN

AUTO

Example: COOL

fan

string · enum

Fan speed setting (LOW, MEDIUM, HIGH, AUTO)

Enum values:

LOW

MEDIUM

HIGH

AUTO

Example: AUTO

swing

string · enum

Swing/oscillation setting (ON, OFF, AUTO)

Enum values:

OFF

AUTO

Example: OFF

temperatureMin

number

Min ambient temperature threshold in Celsius for alerts

Example: 18

temperatureMax

number

Max ambient temperature threshold in Celsius for alerts

Example: 30

humidityMin

number

Min ambient humidity threshold percentage for alerts

Example: 30

humidityMax

number

Max ambient humidity threshold percentage for alerts

Example: 80

notificationThresholdHour

number

Minimum hours between repeated notifications for the same alert type

Example: 4

Default: 4

seriesType

string · enum

Series type — NORMAL (control only) or PRO (control + ambient temp/humidity sensing)

Enum values:

MAXWELL

MAXWELL_PRO

Example: MAXWELL

Default: MAXWELL

targetTemperature

number

Target temperature setting in degrees Celsius for smart mode (automatically adjusts based on ambient conditions)

Example: 22

smartMode

boolean

Whether the device is in smart mode (automatically adjusts settings based on ambient conditions) or manual mode

Example: true

lastSmartModeUpdate

string · date-time

Timestamp of the last update to smart mode settings (used for tracking when thresholds were last updated)

Example: 2024-01-01T12:00:00Z

aggressiveness

number · min: 0 · max: 1

Smart mode proportional gain. Controls how aggressively the AC setpoint compensates for ambient-vs-target deviation. 0 = no compensation (setpoint equals target), 1 = full compensation, >1 = over-compensation. Default: 0.5.

Example: 0.5

Default: 0.5

deadbandTemperature

number · min: 0 · max: 3

Smart mode deadband in °C. If the ambient temperature is within this range of the target, no setpoint adjustment is sent. Prevents oscillation and unnecessary compressor cycling. Default: 0.5.

Example: 0.5

Default: 0.5

smartModeIntervalMinutes

number · min: 1 · max: 1440

Minimum interval in minutes between smart mode recalculations. Prevents excessive updates. Typical values: 15, 30, 60. Default: 60.

Example: 60

Default: 60

SmartDeviceRefDto

_id

string · required

Device ID

macId

string · required

MAC address of the device

deviceType

string · enum · required

Device type

Enum values:

PLUG

MCB

ENV_SENSOR

SMART_SWITCH

AIRCON_CONTROL

WATER_METER

RIDGE

deviceName

string

Display name of the device

FilteredAirconControlDto

_id

string · required

Unique database identifier of the device document in the system

Example: 64b7f1e6f9c9d4e5b8a9f7c3

macId

string · required

Unique identifier assigned to the device by the IoT hardware (MAC ID)

Example: 1092384701928347

deviceName

string · required

Friendly name for the device for easy identification

Example: Living Room AC

onStatus

string · enum · required

Current operational status of the device (ON, OFF, INACTIVE, or ERROR)

Enum values:

OFF

INACTIVE

ERROR

ACTIVE

Example: ON

totalEnergyUsage

number · required

Cumulative total energy consumption in kilowatt-hours (kWh) since device installation

Example: 500

tenantId

string · required

Unique identifier of the tenant organization that owns this device

Example: 64b7f1e6f9c9d4e5b8a9f7c4

tenantName

string · required

Name of the tenant organization that owns this device

Example: Faculty of Engineering

zoneId

string · required

Unique identifier of the zone that this device is assigned to

Example: 64b7f1e6f9c9d4e5b8a9f7c5

zoneName

string · required

Name of the zone that this device is assigned to

Example: Zone A

roomId

string · required

Unique identifier of the room where this device is physically located

Example: 64b7f1e6f9c9d4e5b8a9f7c6

roomName

string · required

Name of the room where this device is physically located

Example: Room 101

dbId

string · required

Unique identifier of the distribution box that this device is connected to (for MCBs)

Example: 64b7f1e6f9c9d4e5b8a9f7c7

dbName

string · required

Name of the distribution box that this device is connected to (for MCBs)

Example: Main Distribution Box

systemId

string · required

Unique identifier of the system that this device belongs to

Example: 64b7f1e6f9c9d4e5b8a9f7c3

systemName

string · required

Name of the system that this device belongs to

Example: NUS Engineering Building

realTimePower

number · required

Real-time power consumption in watts (W) measured by the device

Example: 115

realTimeCurrent

number · required

Real-time current draw in amperes (A) measured by the device

Example: 0.5

ssid

string · required

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

Example: XH001

isIRRemote

boolean · required

Whether this is an IR remote (true) or wired control (false)

Example: true

irType

string · enum · required

Type of IR device being controlled (AIRCON or FAN)

Enum values:

AIRCON

FAN

Example: AIRCON

Default: AIRCON

temperature

number · required

Target temperature setting in degrees Celsius

Example: 24

targetState

string · enum

Enum values:

OFF

INACTIVE

ERROR

ACTIVE

Example: ON

targetStateSetAt

string · date-time

Timestamp when the pending targetState was last written.

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

deviceNumber

number

Auto-incremented sequential number for tracking device registration order

Example: 3

batchNumber

number

Manufacturing batch number for tracking production groups and quality control

Example: 23

chipModel

string · enum

Hardware chip model identifier used in the device (e.g., ESP32C2, ESP8266)

Enum values:

ESP8266

ESP32C2

ESP32C5

ESP32

ESP32C3

versionNumber

string

Firmware version number currently running on the device

Example: 1.0.0

object

Weekly and one-time schedule configuration for automated device control

lastSeen

string · date-time

Timestamp when the device last communicated with the system

Example: 2024-10-15T12:30:00.000Z

isLocked

boolean

Lock status indicating if the device is locked

Example: false

inactivityNotificationEnabled

boolean

Whether inactivity notifications are enabled for this device

Example: false

fanBrand

string · enum

Brand of the fan unit (only applicable when irType is FAN)

Enum values:

KDK_U48FP

KDK_U60FW

U60FWS

KDK_T60AW

T60AWS

Example: KDK_T60AW

fanSpeed

number

Fan speed setting (only applicable when irType is FAN)

Example: 1

brand

string · enum

Brand of the AC unit being controlled

Enum values:

DAIKIN

MITSUBISHI

PANASONIC

SAMSUNG

FUJITSU

TOSHIBA

SHARP

Example: DAIKIN

modelNumber

string

Manufacturer model number (e.g. FTKM50QV1M). Used with brand for consumption estimation via AirconModelSpec lookup.

Example: FTKM50QV1M

mode

string · enum

AC operation mode (COOL, HEAT, DRY, FAN, AUTO)

Enum values:

COOL

HEAT

DRY

FAN

AUTO

Example: COOL

fan

string · enum

Fan speed setting (LOW, MEDIUM, HIGH, AUTO)

Enum values:

LOW

MEDIUM

HIGH

AUTO

Example: AUTO

swing

string · enum

Swing/oscillation setting (ON, OFF, AUTO)

Enum values:

OFF

AUTO

Example: OFF

seriesType

string · enum

Series type — NORMAL (control only) or PRO (control + ambient temp/humidity sensing)

Enum values:

MAXWELL

MAXWELL_PRO

Example: MAXWELL

SmartDeviceRefDto[]

Devices this unit can directly control via MQTT (MAXWELL_PRO only)

smartMode

boolean

Whether the device is in smart mode (automatically adjusts settings based on ambient conditions) or manual mode

Example: false

targetTemperature

number

Target temperature setting in degrees Celsius for smart mode (automatically adjusts based on ambient conditions)

Example: 22

lastSmartModeUpdate

string · date-time

Timestamp of the last update to smart mode settings (used for tracking when thresholds were last updated)

Example: 2024-01-01T12:00:00Z

aggressiveness

number · min: 0 · max: 1

Smart mode proportional gain (0–1). Controls how aggressively the AC setpoint compensates for ambient deviation from target. Default: 0.5.

Example: 0.5

deadbandTemperature

number · min: 0 · max: 3

Smart mode deadband in °C (0–3). Ambient readings within this range of the target temperature are ignored. Default: 0.5.

Example: 0.5

smartModeIntervalMinutes

number · min: 1 · max: 1440

Minimum minutes between smart mode recalculations (1–1440 [24 hours]). Prevents excessive setpoint updates. Default: 60.

Example: 60

GetAirconControlsDto

FilteredAirconControlDto[] · required

List of aircon control devices with organizational hierarchy details

total

number · required

Total number of aircon control devices

Example: 10

page

number · required

Current page number

Example: 1

size

number · required

Number of items per page

Example: 10

UpdateAirconControlDto

deviceName

string

Name of the device

Example: Living Room Light

location

string

Physical location of the device

Example: Block 123, Unit 01-23

remarks

string

Additional remarks or notes about the device

Example: Handle with care - critical equipment

tenantId

string

Tenant ID to associate the device with

Example: 64b7f1e6f9c9d4e5b8a9f7c3

zoneId

string

Zone ID to associate the device with

Example: 64b7f1e6f9c9d4e5b8a9f7c4

roomId

string

Room ID to associate the device with

Example: 64b7f1e6f9c9d4e5b8a9f7c5

isLocked

boolean

Whether the device is locked. When locked, the device cannot be toggled ON/OFF.

Example: false

isSpare

boolean

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

Example: false

isIRRemote

boolean

Whether this is an IR remote (true) or wired control (false)

Example: true

brandType

string · enum

Brand of the AC unit being controlled

Enum values:

DAIKIN

MITSUBISHI

PANASONIC

SAMSUNG

FUJITSU

TOSHIBA

SHARP

Example: DAIKIN

modelNumber

string

Manufacturer model number used to look up rated power for consumption estimation (e.g. FTKM50QV1M).

Example: FTKM50QV1M

irType

string · enum

Type of IR device being controlled (AIRCON or FAN)

Enum values:

AIRCON

FAN

Example: AIRCON

fanBrand

string · enum

Brand of the fan unit (only applicable when irType is FAN)

Enum values:

KDK_U48FP

KDK_U60FW

U60FWS

KDK_T60AW

T60AWS

Example: KDK_T60AW

fanSpeed

number

Fan speed setting (only applicable when irType is FAN)

Example: 1

smartDeviceIds

string[]

IDs of devices this unit can directly control via MQTT. Only applicable for MAXWELL_PRO series.

Example: ["60d5ecb54e3b0c0017e4e1a2"]

smartMode

boolean

Whether the device is in smart mode (automatically adjusts settings based on ambient conditions) or manual mode

Example: false

targetTemperature

number

Target temperature setting in degrees Celsius for smart mode (automatically adjusts based on ambient conditions)

Example: 22

aggressiveness

number · min: 0 · max: 1

Smart mode proportional gain (0–1). Controls how aggressively the AC setpoint compensates for ambient deviation from target. Default: 0.5.

Example: 0.5

deadbandTemperature

number · min: 0 · max: 3

Smart mode deadband in °C (0–3). Ambient readings within this range of the target temperature are ignored. Default: 0.5.

Example: 0.5

smartModeIntervalMinutes

number · min: 1 · max: 1440

Minimum minutes between smart mode recalculations (1–1440 [24 hours]). Prevents excessive setpoint updates. Default: 60.

Example: 60

ControlAirconDto

onStatus

string · enum

Power state of the AC (ON/OFF/INACTIVE)

Enum values:

OFF

INACTIVE

ERROR

ACTIVE

Example: ON

temperature

number · min: 16 · max: 30

Target temperature setting in degrees Celsius

Example: 24

mode

string · enum

AC operation mode (COOL, HEAT, DRY, FAN, AUTO)

Enum values:

COOL

HEAT

DRY

FAN

AUTO

Example: COOL

fan

string · enum

Fan speed setting (LOW, MEDIUM, HIGH, AUTO)

Enum values:

LOW

MEDIUM

HIGH

AUTO

Example: AUTO

swing

string · enum

Swing/oscillation setting (ON, OFF, AUTO)

Enum values:

OFF

AUTO

Example: OFF

fanSpeed

number

Fan speed setting (only applicable when irType is FAN)

Example: 1

smartMode

boolean

Whether the device is in smart mode (automatically adjusts settings based on ambient conditions) or manual mode

Example: false

targetTemperature

number · min: 16 · max: 30

Target temperature setting in degrees Celsius for smart mode (automatically adjusts based on ambient conditions)

Example: 22

brandType

string · enum

Brand of the AC unit (only applicable when irType is AIRCON)

Enum values:

DAIKIN

MITSUBISHI

PANASONIC

SAMSUNG

FUJITSU

TOSHIBA

SHARP

Example: DAIKIN

UpdateAirconControlThresholdDto

temperatureMin

number

Min ambient temperature threshold in Celsius

Example: 18

temperatureMax

number

Max ambient temperature threshold in Celsius

Example: 30

humidityMin

number

Min ambient humidity threshold percentage

Example: 30

humidityMax

number

Max ambient humidity threshold percentage

Example: 80

notificationThresholdHour

number

Minimum hours between repeated notifications for the same alert type

Example: 4

MassUpdateBrandAirconDto

ids

string[] · required

Array of Aircon Control IDs to update

Example: ["507f1f77bcf86cd799439011","507f1f77bcf86cd799439012"]

brandType

string · enum · required

Brand to assign to all specified devices

Enum values:

DAIKIN

MITSUBISHI

PANASONIC

SAMSUNG

FUJITSU

TOSHIBA

SHARP

Example: DAIKIN

BulkControlAirconDto

ids

string[] · required

Array of Aircon Control IDs to control

Example: ["507f1f77bcf86cd799439011","507f1f77bcf86cd799439012"]

onStatus

string · enum

Power state of the AC (ON/OFF/INACTIVE)

Enum values:

OFF

INACTIVE

ERROR

ACTIVE

Example: ON

temperature

number · min: 16 · max: 30

Target temperature setting in degrees Celsius

Example: 24

mode

string · enum

AC operation mode (COOL, HEAT, DRY, FAN, AUTO)

Enum values:

COOL

HEAT

DRY

FAN

AUTO

Example: COOL

fan

string · enum

Fan speed setting (LOW, MEDIUM, HIGH, AUTO)

Enum values:

LOW

MEDIUM

HIGH

AUTO

Example: AUTO

swing

string · enum

Swing/oscillation setting (ON, OFF, AUTO)

Enum values:

OFF

AUTO

Example: OFF

fanSpeed

number

Fan speed setting (only applicable when irType is FAN)

Example: 1

smartMode

boolean

Whether the device is in smart mode (automatically adjusts settings based on ambient conditions) or manual mode

Example: false

targetTemperature

number · min: 16 · max: 30

Target temperature setting in degrees Celsius for smart mode (automatically adjusts based on ambient conditions)

Example: 22

brandType

string · enum

Brand of the AC unit (only applicable when irType is AIRCON)

Enum values:

DAIKIN

MITSUBISHI

PANASONIC

SAMSUNG

FUJITSU

TOSHIBA

SHARP

Example: DAIKIN

EstimateAirconConsumptionDto

startDate

string · required

Start of the date range (ISO 8601). Inclusive.

Example: 2026-05-01T00:00:00.000Z

endDate

string · required

End of the date range (ISO 8601). Inclusive.

Example: 2026-05-27T23:59:59.999Z

AirconConsumptionByModeDto

kwh

number · required

Total kWh accumulated while in this mode

Example: 8.4

hours

number · required

Total runtime hours while in this mode

Example: 9.2

AirconAmbientSource

string · enum

Enum values:

SENSOR

FALLBACK

Where the ambient temperature came from

AirconConsumptionIntervalDto

start

string · date-time · required

end

string · date-time · required

mode

string · enum · required

Operating mode (AIRCON_CONTROL only)

Enum values:

COOL

HEAT

DRY

FAN

AUTO

Example: COOL

temperatureC

number · required

fan

string · enum · required

Fan speed setting (AIRCON_CONTROL only)

Enum values:

LOW

MEDIUM

HIGH

AUTO

Example: AUTO

hours

number · required

Duration in hours

Example: 0.533

powerKw

number · required

Estimated instantaneous power draw in kW

Example: 1.05

kwh

number · required

Estimated energy consumed during this interval in kWh

Example: 0.56

AirconConsumptionEstimateDto

airconId

string · required

brand

string · enum · required

Air conditioner brand (AIRCON_CONTROL only)

Enum values:

DAIKIN

MITSUBISHI

PANASONIC

SAMSUNG

FUJITSU

TOSHIBA

SHARP

Example: DAIKIN

modelNumber

string · required

ratedInputPowerKw

number · required

Rated input power (kW) used as the load reference

Example: 1.42

startDate

string · date-time · required

endDate

string · date-time · required

ambientTempC

number · required

Ambient temperature used in the load-factor calc

Example: 30

ambientSource

string · enum · required

Where the ambient temperature came from

Enum values:

SENSOR

FALLBACK

Example: FALLBACK

totalKwh

number · required

totalRuntimeHours

number · required

object · required

kWh and runtime hours broken down by AirconControlMode. Keys are mode names (COOL, DRY, FAN, AUTO, HEAT). Values are AirconConsumptionByModeDto.

AirconConsumptionIntervalDto[] · required

Per-interval breakdown used to build the totals

accuracyNote

string · required

Disclaimer on accuracy

Example: Estimate ±20-30% — derived from settings history × rated input power × heuristic load factor. Install a circuit-level meter (MCB) for billing-grade accuracy.

tariffCentsPerKwh

number

Current system tariff in cents/kWh used to compute cost. Omitted if no active tariff rate is set on the system.

Example: 28.5

costSgd

number

Total cost in SGD = totalKwh × (tariffCentsPerKwh / 100). Omitted when no active tariff rate is set on the system.

Example: 3.97

CreateRoomDto

name

string · required

Display name for the room. This will be used to identify the room throughout the system.

Example: Living Room

squareMeter

number

Floor area of the room in square meters.

Example: 25.5

remarks

string

Optional administrative notes or comments about the room. Used for describing the room purpose or equipment.

Example: Conference room with presentation equipment

systemId

string

Unique identifier of the system that this room belongs to. Automatically populated from URL parameter.

Example: 64b7f1e6f9c9d4e5b8a9f7c0

tenantId

string

Optional identifier of the tenant organization that owns this room. Can be omitted for single-tenant systems.

Example: 64b7f1e6f9c9d4e5b8a9f7c1

zoneId

string

Optional identifier of the zone to assign this room to. If provided, the room will be accessible by this zone.

Example: 64b7f1e6f9c9d4e5b8a9f7c2

roomType

string

Room type key. Must be a valid type defined for this system via /entity-type/ROOM.

Example: MEETING_ROOM

GetRoomsResponseDto

total

number · required

Total count of items matching filters

Example: 150

page

number · min: 1 · required

Current page number

Example: 1

size

number · min: 1 · required

Items per page

Example: 50

totalPages

number · min: 0 · required

Total number of pages

Example: 3

data

string[] · required

Array of GetRoomDto IDs

UpdateRoomDto

name

string

Updated display name for the room. This will replace the existing room name.

Example: Conference Room A

zoneId

string

Updated zone identifier to reassign room access to a different zone.

Example: 64b7f1e6f9c9d4e5b8a9f7c1

tenantId

string

Updated tenant identifier to reassign the room to a different organization.

Example: 64b7f1e6f9c9d4e5b8a9f7c2

squareMeter

number | null

Updated floor area of the room in square meters. Pass null to clear the existing value.

Example: 25.5

remarks

string

Updated administrative notes or comments about the room. Replaces existing remarks if provided.

Example: Updated with new equipment

roomType

string

Room type key. Must be a valid type defined for this system via /entity-type/ROOM.

Example: MEETING_ROOM

AirconModelSpecDto

_id

string · required

brand

string · enum · required

Air conditioner brand (AIRCON_CONTROL only)

Enum values:

DAIKIN

MITSUBISHI

PANASONIC

SAMSUNG

FUJITSU

TOSHIBA

SHARP

Example: DAIKIN

modelNumber

string · required

ratedCoolingKw

number · required

ratedInputPowerKw

number · required

verifiedAt

string · date-time · required

createdAt

string · date-time · required

updatedAt

string · date-time · required

cspf

number

annualKwhSg

number

notes

string

AirconModelSpecsResponseDto

total

number · required

Total count of items matching filters

Example: 150

page

number · min: 1 · required

Current page number

Example: 1

size

number · min: 1 · required

Items per page

Example: 50

totalPages

number · min: 0 · required

Total number of pages

Example: 3

AirconModelSpecDto[] · required

Aircon model spec rows matching the query

CreateAirconModelSpecDto

brand

string · enum · required

Air conditioner brand (AIRCON_CONTROL only)

Enum values:

DAIKIN

MITSUBISHI

PANASONIC

SAMSUNG

FUJITSU

TOSHIBA

SHARP

Example: DAIKIN

modelNumber

string · required

Manufacturer model number. Server uppercases + trims.

Example: FTKM50QV1M

ratedCoolingKw

number · required

ratedInputPowerKw

number · required

cspf

number

annualKwhSg

number

verifiedAt

string · date-time

When this row was verified. Defaults to now if omitted.

Example: 2026-05-27T00:00:00.000Z

notes

string

UpdateAirconModelSpecDto

brand

string · enum

Air conditioner brand (AIRCON_CONTROL only)

Enum values:

DAIKIN

MITSUBISHI

PANASONIC

SAMSUNG

FUJITSU

TOSHIBA

SHARP

Example: DAIKIN

modelNumber

string

Manufacturer model number. Server uppercases + trims.

Example: FTKM50QV1M

ratedCoolingKw

number

ratedInputPowerKw

number

cspf

number

annualKwhSg

number

verifiedAt

string · date-time

When this row was verified. Defaults to now if omitted.

Example: 2026-05-27T00:00:00.000Z

notes

string

EnvironmentSensorType

string · enum

Enum values:

FRIDGE_SENSOR

IAQ4

IAQ9

Type of the environment sensor device (e.g., IAQ4, IAQ9)

EnvironmentSensor

_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

Device[] · required

List of smart devices controlled by this environment sensor

environmentSensorType

string · enum · required

Type of the environment sensor device (e.g., IAQ4, IAQ9)

Enum values:

FRIDGE_SENSOR

IAQ4

IAQ9

Example: IAQ4

notificationThresholdHour

number · required

Hourly notification threshold for the Environment Sensor

Example: 4

carbonDioxide

number · required

Threshold CO2 reading in ppm

Example: 400

lux

number · required

Threshold light level in lux (lx)

Example: 500

formaldehyde

number · required

Threshold formaldehyde (HCHO) reading in ppm

Example: 0.03

temperatureMin

number · required

Min Threshold temperature reading in degrees Celsius

Example: 24

temperatureMax

number · required

MaxThreshold temperature reading in degrees Celsius

Example: 24

humidity

number · required

Threshold humidity percentage

Example: 24

fineParticulateMatter

number · required

Threshold Fine Particulate Matter in µg/m3

Example: 1

coarseParticulateMatter

number · required

Threshold Coarse Particulate Matter in µg/m3

Example: 1

totalVolatileOrganicCompounds

number · required

Threshold Total Volatile Organic Compounds in ppm

Example: 1

soundLevel

number · required

Threshold Sound Level in dB

Example: 1

motionDetected

boolean · required

Motion detection status

Example: true

thresholdGroupName

string | null · required

Name of the threshold group this sensor belongs to

Example: Office Sensors

smartModeIntervalMinutes

number · min: 1 · max: 1440 · required

Minimum interval in minutes between smart mode recalculations triggered by this sensor. Typical values: 15, 30, 60. Default: 60.

Example: 60

Default: 60

lastSmartModeUpdate

string | null · date-time · required

Timestamp of the last smart mode update dispatched by this sensor. Used to enforce the smartModeIntervalMinutes cooldown.

Example: 2024-01-01T12:00:00Z

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

FilteredEnvironmentSensorDto

_id

string · required

Unique database identifier of the device document in the system

Example: 64b7f1e6f9c9d4e5b8a9f7c3

macId

string · required

Unique identifier assigned to the device by the IoT hardware (MAC ID)

Example: 1092384701928347

deviceName

string · required

Friendly name for the device for easy identification

Example: Living Room AC

onStatus

string · enum · required

Current operational status of the device (ON, OFF, INACTIVE, or ERROR)

Enum values:

OFF

INACTIVE

ERROR

ACTIVE

Example: ON

totalEnergyUsage

number · required

Cumulative total energy consumption in kilowatt-hours (kWh) since device installation

Example: 500

tenantId

string · required

Unique identifier of the tenant organization that owns this device

Example: 64b7f1e6f9c9d4e5b8a9f7c4

tenantName

string · required

Name of the tenant organization that owns this device

Example: Faculty of Engineering

zoneId

string · required

Unique identifier of the zone that this device is assigned to

Example: 64b7f1e6f9c9d4e5b8a9f7c5

zoneName

string · required

Name of the zone that this device is assigned to

Example: Zone A

roomId

string · required

Unique identifier of the room where this device is physically located

Example: 64b7f1e6f9c9d4e5b8a9f7c6

roomName

string · required

Name of the room where this device is physically located

Example: Room 101

dbId

string · required

Unique identifier of the distribution box that this device is connected to (for MCBs)

Example: 64b7f1e6f9c9d4e5b8a9f7c7

dbName

string · required

Name of the distribution box that this device is connected to (for MCBs)

Example: Main Distribution Box

systemId

string · required

Unique identifier of the system that this device belongs to

Example: 64b7f1e6f9c9d4e5b8a9f7c3

systemName

string · required

Name of the system that this device belongs to

Example: NUS Engineering Building

realTimePower

number · required

Real-time power consumption in watts (W) measured by the device

Example: 115

realTimeCurrent

number · required

Real-time current draw in amperes (A) measured by the device

Example: 0.5

ssid

string · required

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

Example: XH001

temperatureMin

number · required

Minimum threshold temperature reading in degrees Celsius

Example: 18

temperatureMax

number · required

Maximum threshold temperature reading in degrees Celsius

Example: 26

targetState

string · enum

Enum values:

OFF

INACTIVE

ERROR

ACTIVE

Example: ON

targetStateSetAt

string · date-time

Timestamp when the pending targetState was last written.

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

deviceNumber

number

Auto-incremented sequential number for tracking device registration order

Example: 3

batchNumber

number

Manufacturing batch number for tracking production groups and quality control

Example: 23

chipModel

string · enum

Hardware chip model identifier used in the device (e.g., ESP32C2, ESP8266)

Enum values:

ESP8266

ESP32C2

ESP32C5

ESP32

ESP32C3

versionNumber

string

Firmware version number currently running on the device

Example: 1.0.0

object

Weekly and one-time schedule configuration for automated device control

lastSeen

string · date-time

Timestamp when the device last communicated with the system

Example: 2024-10-15T12:30:00.000Z

isLocked

boolean

Lock status indicating if the device is locked

Example: false

inactivityNotificationEnabled

boolean

Whether inactivity notifications are enabled for this device

Example: false

environmentSensorType

string · enum

Type of environment sensor (IAQ4, IAQ9, or temperature sensor)

Enum values:

FRIDGE_SENSOR

IAQ4

IAQ9

Example: IAQ4

temperature

number

Current temperature reading in degrees Celsius

Example: 24.5

carbonDioxide

number

Threshold CO2 reading in ppm

Example: 800

lux

number

Threshold light level in lux (lx)

Example: 500

formaldehyde

number

Threshold formaldehyde (HCHO) reading in ppm

Example: 0.08

humidity

number

Threshold humidity percentage

Example: 60

fineParticulateMatter

number

Threshold Fine Particulate Matter (PM2.5) in µg/m³

Example: 35

coarseParticulateMatter

number

Threshold Coarse Particulate Matter (PM10) in µg/m³

Example: 50

totalVolatileOrganicCompounds

number

Threshold Total Volatile Organic Compounds in ppm

Example: 0.5

soundLevel

number

Threshold Sound Level in dB

Example: 70

motionDetected

boolean

Motion detection status

Example: false

thresholdGroupName

string

Name of the threshold group this sensor belongs to

Example: Office Sensors

SmartDeviceRefDto[]

Devices this sensor can directly control via MQTT

smartModeIntervalMinutes

number · min: 1 · max: 1440

Minimum minutes between smart mode recalculations triggered by this sensor (1–1440). Default: 60.

Example: 60

lastSmartModeUpdate

string · date-time

Timestamp of the last smart mode update dispatched by this sensor.

Example: 2024-01-01T12:00:00Z

GetEnvironmentSensorsDto

total

number · required

Total count of items matching filters

Example: 150

page

number · min: 1 · required

Current page number

Example: 1

size

number · min: 1 · required

Items per page

Example: 50

totalPages

number · min: 0 · required

Total number of pages

Example: 3

FilteredEnvironmentSensorDto[] · required

List of environment sensor devices

UpdateEnvironmentSensorDeviceDto

onStatus

string · enum · required

Operational status of the environment sensor device

Enum values:

OFF

INACTIVE

ERROR

ACTIVE

Example: ON

deviceName

string

Name of the device

Example: Living Room Light

location

string

Physical location of the device

Example: Block 123, Unit 01-23

remarks

string

Additional remarks or notes about the device

Example: Handle with care - critical equipment

tenantId

string

Tenant ID to associate the device with

Example: 64b7f1e6f9c9d4e5b8a9f7c3

zoneId

string

Zone ID to associate the device with

Example: 64b7f1e6f9c9d4e5b8a9f7c4

roomId

string

Room ID to associate the device with

Example: 64b7f1e6f9c9d4e5b8a9f7c5

isLocked

boolean

Whether the device is locked. When locked, the device cannot be toggled ON/OFF.

Example: false

isSpare

boolean

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

Example: false

smartDeviceIds

string[]

IDs of devices this sensor can directly control via MQTT.

Example: ["60d5ecb54e3b0c0017e4e1a2"]

smartModeIntervalMinutes

number · min: 1 · max: 1440

Minimum minutes between smart mode recalculations triggered by this sensor (1–1440). Default: 60.

Example: 60

UpdateEnvironmentSensorThresholdDto

temperatureMin

number

Min Threshold temperature reading in degrees Celsius

Example: 24

temperatureMax

number

Max Threshold temperature reading in degrees Celsius

Example: 24

carbonDioxide

number

Threshold CO2 reading in ppm

Example: 400

lux

number

Threshold light level in lux (lx)

Example: 500

formaldehyde

number

Threshold formaldehyde (HCHO) reading in ppm

Example: 0.03

humidity

number

Threshold humidity percentage

Example: 24

fineParticulateMatter

number

Threshold Fine Particulate Matter in µg/m3

Example: 1

coarseParticulateMatter

number

Threshold Coarse Particulate Matter in µg/m3

Example: 1

totalVolatileOrganicCompounds

number

Threshold Total Volatile Organic Compounds in ppm

Example: 1

soundLevel

number

Threshold Sound Level in dB

Example: 1

motionDetected

boolean

Motion detection status

Example: true

notificationThresholdHour

number

Hourly notification threshold for the Environment Sensor

Example: 4

BulkUpdateEnvironmentSensorThresholdsDto

environmentSensorIds

string[] · required

IDs of environment sensors to update

carbonDioxide

number

Threshold CO2 reading in ppm

Example: 400

lux

number

Threshold light level in lux (lx)

Example: 500

formaldehyde

number

Threshold formaldehyde (HCHO) in ppm

Example: 0.03

temperatureMin

number

Min Threshold temperature in °C

Example: 18

temperatureMax

number

Max Threshold temperature in °C

Example: 26

humidity

number

Threshold humidity percentage

Example: 60

fineParticulateMatter

number

Threshold Fine Particulate Matter in µg/m3

Example: 15

coarseParticulateMatter

number

Threshold Coarse Particulate Matter in µg/m3

Example: 35

totalVolatileOrganicCompounds

number

Threshold Total Volatile Organic Compounds in ppm

Example: 1

soundLevel

number

Threshold Sound Level in dB

Example: 70

motionDetected

boolean

Motion detection enabled

Example: true

notificationThresholdHour

number

Hourly notification threshold — minimum hours between repeat notifications

Example: 4

EnvironmentSensorThresholdGroup

_id

string · required

Primary ID of the Threshold Group

Example: 64b7f1e6f9c9d4e5b8a9f7c3

name

string · required

User-defined group name

Example: Office Sensors

systemId

string · required

System this group belongs to

Example: 507f1f77bcf86cd799439011

environmentSensorType

string · enum · required

Type of environment sensors in this group

Enum values:

FRIDGE_SENSOR

IAQ4

IAQ9

Example: IAQ4

sensorIds

string[] · required

Sensors assigned to this group

Example: ["507f1f77bcf86cd799439011"]

temperatureMin

number

Min temperature threshold in degrees Celsius

Example: 18

temperatureMax

number

Max temperature threshold in degrees Celsius

Example: 28

humidity

number

Max humidity threshold percentage

Example: 70

carbonDioxide

number

Max CO2 threshold in ppm

Example: 1000

lux

number

Max light level threshold in lux (lx)

Example: 1000

formaldehyde

number

Max formaldehyde (HCHO) threshold in ppm

Example: 0.08

fineParticulateMatter

number

Max PM2.5 threshold in ug/m3

Example: 35

coarseParticulateMatter

number

Max PM10 threshold in ug/m3

Example: 150

totalVolatileOrganicCompounds

number

Max TVOC threshold in ppm

Example: 0.5

soundLevel

number

Max sound level threshold in dB

Example: 65

CreateEnvironmentSensorThresholdGroupDto

name

string · required

User-defined group name

Example: Office Sensors

environmentSensorType

string · enum · required

Type of environment sensors in this group

Enum values:

FRIDGE_SENSOR

IAQ4

IAQ9

Example: IAQ4

sensorIds

string[]

Sensor IDs to assign to this group. Each sensor must match the group's environmentSensorType. Sensors are automatically removed from their previous group.

Example: ["507f1f77bcf86cd799439011","507f1f77bcf86cd799439012"]

temperatureMin

number

Min temperature threshold in degrees Celsius

Example: 18

temperatureMax

number

Max temperature threshold in degrees Celsius

Example: 28

humidity

number

Max humidity threshold percentage

Example: 70

carbonDioxide

number

Max CO2 threshold in ppm

Example: 1000

lux

number

Max light level threshold in lux (lx)

Example: 1000

formaldehyde

number

Max formaldehyde (HCHO) threshold in ppm

Example: 0.08

fineParticulateMatter

number

Max PM2.5 threshold in ug/m3

Example: 35

coarseParticulateMatter

number

Max PM10 threshold in ug/m3

Example: 150

totalVolatileOrganicCompounds

number

Max TVOC threshold in ppm

Example: 0.5

soundLevel

number

Max sound level threshold in dB

Example: 65

UpdateEnvironmentSensorThresholdGroupDto

name

string

Updated group name

Example: Office Sensors Updated

sensorIds

string[]

Full list of sensor IDs to assign to this group (replaces existing assignments). Each sensor must match the group's environmentSensorType. Sensors are automatically removed from their previous group.

Example: ["507f1f77bcf86cd799439011","507f1f77bcf86cd799439012"]

temperatureMin

number

Min temperature threshold in degrees Celsius

Example: 18

temperatureMax

number

Max temperature threshold in degrees Celsius

Example: 28

humidity

number

Max humidity threshold percentage

Example: 70

carbonDioxide

number

Max CO2 threshold in ppm

Example: 1000

lux

number

Max light level threshold in lux (lx)

Example: 1000

formaldehyde

number

Max formaldehyde (HCHO) threshold in ppm

Example: 0.08

fineParticulateMatter

number

Max PM2.5 threshold in ug/m3

Example: 35

coarseParticulateMatter

number

Max PM10 threshold in ug/m3

Example: 150

totalVolatileOrganicCompounds

number

Max TVOC threshold in ppm

Example: 0.5

soundLevel

number

Max sound level threshold in dB

Example: 65

FilteredSmartSwitchDto

_id

string · required

Unique database identifier of the device document in the system

Example: 64b7f1e6f9c9d4e5b8a9f7c3

macId

string · required

Unique identifier assigned to the device by the IoT hardware (MAC ID)

Example: 1092384701928347

deviceName

string · required

Friendly name for the device for easy identification

Example: Living Room AC

onStatus

string · enum · required

Current operational status of the device (ON, OFF, INACTIVE, or ERROR)

Enum values:

OFF

INACTIVE

ERROR

ACTIVE

Example: ON

totalEnergyUsage

number · required

Cumulative total energy consumption in kilowatt-hours (kWh) since device installation

Example: 500

tenantId

string · required

Unique identifier of the tenant organization that owns this device

Example: 64b7f1e6f9c9d4e5b8a9f7c4

tenantName

string · required

Name of the tenant organization that owns this device

Example: Faculty of Engineering

zoneId

string · required

Unique identifier of the zone that this device is assigned to

Example: 64b7f1e6f9c9d4e5b8a9f7c5

zoneName

string · required

Name of the zone that this device is assigned to

Example: Zone A

roomId

string · required

Unique identifier of the room where this device is physically located

Example: 64b7f1e6f9c9d4e5b8a9f7c6

roomName

string · required

Name of the room where this device is physically located

Example: Room 101

dbId

string · required

Unique identifier of the distribution box that this device is connected to (for MCBs)

Example: 64b7f1e6f9c9d4e5b8a9f7c7

dbName

string · required

Name of the distribution box that this device is connected to (for MCBs)

Example: Main Distribution Box

systemId

string · required

Unique identifier of the system that this device belongs to

Example: 64b7f1e6f9c9d4e5b8a9f7c3

systemName

string · required

Name of the system that this device belongs to

Example: NUS Engineering Building

realTimePower

number · required

Real-time power consumption in watts (W) measured by the device

Example: 115

realTimeCurrent

number · required

Real-time current draw in amperes (A) measured by the device

Example: 0.5

ssid

string · required

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

Example: XH001

switchType

string · enum · required

Type of appliance the switch controls (LIGHT, FAN, AIRCON, or UNREGISTERED)

Enum values:

UNREGISTERED

LIGHT

FAN

AIRCON

Example: LIGHT

numberOfGangs

number · min: 1 · max: 4 · required

Number of gangs/buttons on the switch (1-4)

Example: 2

GangSwitchState[] · required

Array of gang switch states - each gang has its own independent on/off state

Example: [{"gangNumber":1,"onStatus":"OFF","label":"Main Light"},{"gangNumber":2,"onStatus":"OFF","label":"Accent Light"}]

targetState

string · enum

Enum values:

OFF

INACTIVE

ERROR

ACTIVE

Example: ON

targetStateSetAt

string · date-time

Timestamp when the pending targetState was last written.

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

deviceNumber

number

Auto-incremented sequential number for tracking device registration order

Example: 3

batchNumber

number

Manufacturing batch number for tracking production groups and quality control

Example: 23

chipModel

string · enum

Hardware chip model identifier used in the device (e.g., ESP32C2, ESP8266)

Enum values:

ESP8266

ESP32C2

ESP32C5

ESP32

ESP32C3

versionNumber

string

Firmware version number currently running on the device

Example: 1.0.0

object

Weekly and one-time schedule configuration for automated device control

lastSeen

string · date-time

Timestamp when the device last communicated with the system

Example: 2024-10-15T12:30:00.000Z

isLocked

boolean

Lock status indicating if the device is locked

Example: false

inactivityNotificationEnabled

boolean

Whether inactivity notifications are enabled for this device

Example: false

GetSmartSwitchesDto

FilteredSmartSwitchDto[] · required

List of Smart Switches with organizational hierarchy details

total

number · required

Total number of Smart Switches

Example: 42

page

number · required

Current page number

Example: 1

size

number · required

Number of items per page

Example: 10

UpdateSmartSwitchDto

deviceName

string

Name of the device

Example: Living Room Light

location

string

Physical location of the device

Example: Block 123, Unit 01-23

remarks

string

Additional remarks or notes about the device

Example: Handle with care - critical equipment

tenantId

string

Tenant ID to associate the device with

Example: 64b7f1e6f9c9d4e5b8a9f7c3

zoneId

string

Zone ID to associate the device with

Example: 64b7f1e6f9c9d4e5b8a9f7c4

roomId

string

Room ID to associate the device with

Example: 64b7f1e6f9c9d4e5b8a9f7c5

isLocked

boolean

Whether the device is locked. When locked, the device cannot be toggled ON/OFF.

Example: false

isSpare

boolean

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

Example: false

onStatus

string · enum

Status of the Smart Switch

Enum values:

OFF

INACTIVE

ERROR

ACTIVE

Example: ON

switchType

string · enum

Type of appliance the switch controls

Enum values:

UNREGISTERED

LIGHT

FAN

AIRCON

Example: LIGHT

numberOfGangs

number · min: 1 · max: 4

Number of gangs/buttons on the switch (1-4)

Example: 2

SmartSwitch

_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

switchType

string · enum · required

Type of appliance the switch controls (LIGHT, FAN, AIRCON, or UNREGISTERED)

Enum values:

UNREGISTERED

LIGHT

FAN

AIRCON

Example: LIGHT

numberOfGangs

number · min: 1 · max: 4 · required

Number of gangs/buttons on the switch (1-4)

Example: 2

GangSwitchState[] · required

Array of gang switch states - each gang has its own independent on/off state

Example: [{"gangNumber":1,"onStatus":"OFF","label":"Main Light"},{"gangNumber":2,"onStatus":"OFF","label":"Accent Light"}]

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

ControlSmartSwitchDto

gangStates

number[] · required

Array of binary gang switch states where 1 = ON and 0 = OFF. Array index corresponds to gang number (e.g., [1, 0, 0, 1] means gang 1 ON, gang 2 OFF, gang 3 OFF, gang 4 ON)

Example: [1,0,0,1]

triggerSource

string · enum

Source that triggered the control command

Enum values:

MANUAL

CLOUD

SCHEDULED

ECOGUARD

WATCHDOG

LWT

UNKNOWN

BOOTUP

Example: CLOUD

BulkControlSmartSwitchDto

ids

string[] · required

Array of Smart Switch IDs to control

Example: ["64b7f1e6f9c9d4e5b8a9f7c3","64b7f1e6f9c9d4e5b8a9f7c4"]

onStatus

string · enum

Desired power state for all gangs on all Smart Switches. Use ON to turn all gangs on, or OFF to turn all gangs off.

Enum values:

OFF

INACTIVE

ERROR

ACTIVE

Example: ON

CreateDistributionBoxDto

name

string · required

Name/identifier of the Distribution Box

Example: Main DB Box - Floor 1

systemId

string · required

System ID to which this Distribution Box belongs

Example: 64b7f1e6f9c9d4e5b8a9f7c3

numberOfRows

number

Number of rows in the distribution box

Example: 1

hasMainBreaker

boolean

Whether the distribution box has main circuit breaker

Example: true

mainBreakerRating

number

Main breaker rating in amperes (if hasMainBreaker is true)

Example: 63

tenantId

string

Tenant ID to which this Distribution Box belongs

zoneId

string

Zone ID to which this Distribution Box belongs

roomId

string

Room ID to which this Distribution Box belongs

mcbIds

string[]

Array of MCB IDs to be assigned to this distribution box

Example: ["64b7f1e6f9c9d4e5b8a9f7c3","64b7f1e6f9c9d4e5b8a9f7c4"]

location

string

Location of the Distribution Box

Example: Ground Floor, Electrical Room

remarks

string

Remarks for the Distribution Box

digitalTwinWidth

number

Width of the digital twin canvas in pixels

Example: 1200

digitalTwinHeight

number

Height of the digital twin canvas in pixels

Example: 800

GetDistributionBoxesDto

DistributionBox[] · required

Array of Distribution Boxes

total

number · required

Total number of Distribution Boxes

Example: 100

page

number · required

Current page number

Example: 1

size

number · required

Number of items per page

Example: 10

SandboxDeviceInputDto

id

string · required

Unique identifier for the sandbox device

Example: sandbox-device-1

type

string · enum · required

Type of sandbox device

Enum values:

DUMB_MCB

RCCB

Example: DUMB_MCB

name

string · required

User-defined name for the device

Example: Kitchen Lights

digitalTwinX

number · required

X position on the digital twin canvas

Example: 400

rowLine

number · required

Row line position (1-6)

Example: 2

ratedCurrent

number

Rated current in amperes

Example: 16

ratedVoltage

number

Rated voltage in volts

Example: 230

mcbType

string · enum

MCB type (for DUMB_MCB devices)

Enum values:

UNREGISTERED

SWITCH

BUILT_IN

COIL

COIL3P

Example: BUILT_IN

mcbPoles

string · enum

MCB poles configuration (for DUMB_MCB devices)

Enum values:

UNREGISTERED

SINGLE_POLE

DOUBLE_POLE

THREE_POLE

FOUR_POLE

Example: SINGLE_POLE

leakageCurrent

number

Leakage current in milliamperes (for RCCB devices)

Example: 30

color

string

Custom color for visual identification (hex code)

Example: #94a3b8

notes

string

Additional notes about the device

Example: Connected to kitchen circuit

WireConnectionDto

deviceId

string · required

Device ID (MCB._id or SandboxDevice.id)

Example: sandbox-device-1

deviceType

string · enum · required

Type of device being connected

Enum values:

SMART_MCB

DUMB_MCB

RCCB

Example: DUMB_MCB

side

string · enum · required

Side of the device where the connection is made

Enum values:

LEFT

RIGHT

TOP

BOTTOM

Example: LEFT

SandboxWireInputDto

id

string · required

Unique identifier for the wire connection

Example: wire-1

object · required

Source connection point

object · required

Target connection point

color

string

Wire color (hex code)

Example: #fbbf24

Default: #fbbf24

thickness

number

Wire thickness in pixels

Example: 3

Default: 3

label

string

Optional label for the wire

Example: Phase 1

UpdateDistributionBoxDto

name

string

Name/identifier of the Distribution Box

Example: Main DB Box - Floor 2

numberOfRows

number

Number of rows in the distribution box

Example: 1

hasMainBreaker

boolean

Whether the distribution box has main circuit breaker

Example: true

mainBreakerRating

number

Main breaker rating in amperes (if hasMainBreaker is true)

Example: 63

tenantId

string

Tenant ID to which this Distribution Box belongs

zoneId

string

Zone ID to which this Distribution Box belongs

roomId

string

Room ID to which this Distribution Box belongs

mcbIds

string[]

Array of MCB IDs to be assigned to this distribution box

Example: ["64b7f1e6f9c9d4e5b8a9f7c3","64b7f1e6f9c9d4e5b8a9f7c4"]

location

string

Location of the Distribution Box

Example: Ground Floor, Electrical Room

remarks

string

Remarks for the Distribution Box

SandboxDeviceInputDto[]

Array of sandbox (non-smart) devices in the distribution box

SandboxWireInputDto[]

Array of wire connections between devices in the distribution box

digitalTwinWidth

number

Width of the digital twin canvas in pixels

Example: 1200

digitalTwinHeight

number

Height of the digital twin canvas in pixels

Example: 800

AddMCBToDistributionBoxDto

mcbId

string · required

MCB ID to add to the distribution box

Example: 64b7f1e6f9c9d4e5b8a9f7c3

RemoveMCBFromDistributionBoxDto

mcbId

string · required

MCB ID to remove from the distribution box

Example: 64b7f1e6f9c9d4e5b8a9f7c3

GetMCBEnergyUsageDto

mcbId

string · required

MCB ID

Example: 64b7f1e6f9c9d4e5b8a9f7c3

deviceName

string · required

MCB name

Example: Living Room AC MCB

totalEnergyUsage

number · required

Total energy usage in kWh

Example: 125.5

realTimePower

number

Real-time power consumption in watts

Example: 1500

realTimeCurrent

number

Real-time current in amperes

Example: 6.5

GetDistributionBoxEnergyUsageDto

distributionBoxId

string · required

Distribution Box ID

Example: 64b7f1e6f9c9d4e5b8a9f7c3

name

string · required

Distribution Box name

Example: Main DB Box - Floor 1

totalEnergyUsage

number · required

Total energy usage in kWh (sum of all MCBs)

Example: 1250.75

mcbCount

number · required

Number of MCBs in this distribution box

Example: 12

GetMCBEnergyUsageDto[] · required

Individual MCB energy usage details

GetAggregatedDistributionBoxEnergyUsageDto

totalEnergyUsage

number · required

Total aggregated energy usage in kWh

Example: 5250.75

distributionBoxCount

number · required

Number of distribution boxes included

Example: 5

GetDistributionBoxEnergyUsageDto[] · required

Individual distribution box energy usage details

CreateSandboxDeviceDto

type

string · enum · required

Type of sandbox device

Enum values:

DUMB_MCB

RCCB

Example: DUMB_MCB

name

string · required

User-defined name for the device

Example: Kitchen Lights

digitalTwinX

number · required

X position on the digital twin canvas

Example: 400

rowLine

number · required

Row line position (1-6)

Example: 2

ratedCurrent

number

Rated current in amperes

Example: 16

ratedVoltage

number

Rated voltage in volts

Example: 230

mcbType

string · enum

MCB type (for DUMB_MCB devices)

Enum values:

UNREGISTERED

SWITCH

BUILT_IN

COIL

COIL3P

Example: BUILT_IN

mcbPoles

string · enum

MCB poles configuration (for DUMB_MCB devices)

Enum values:

UNREGISTERED

SINGLE_POLE

DOUBLE_POLE

THREE_POLE

FOUR_POLE

Example: SINGLE_POLE

leakageCurrent

number

Leakage current in milliamperes (for RCCB devices)

Example: 30

color

string

Custom color for visual identification (hex code)

Example: #94a3b8

notes

string

Additional notes about the device

Example: Connected to kitchen circuit

UpdateSandboxDeviceDto

type

string · enum

Type of sandbox device

Enum values:

DUMB_MCB

RCCB

Example: DUMB_MCB

name

string

User-defined name for the device

Example: Kitchen Lights

digitalTwinX

number

X position on the digital twin canvas

Example: 400

rowLine

number

Row line position (1-6)

Example: 2

ratedCurrent

number

Rated current in amperes

Example: 16

ratedVoltage

number

Rated voltage in volts

Example: 230

mcbType

string · enum

MCB type (for DUMB_MCB devices)

Enum values:

UNREGISTERED

SWITCH

BUILT_IN

COIL

COIL3P

Example: BUILT_IN

mcbPoles

string · enum

MCB poles configuration (for DUMB_MCB devices)

Enum values:

UNREGISTERED

SINGLE_POLE

DOUBLE_POLE

THREE_POLE

FOUR_POLE

Example: SINGLE_POLE

leakageCurrent

number

Leakage current in milliamperes (for RCCB devices)

Example: 30

color

string

Custom color for visual identification (hex code)

Example: #94a3b8

notes

string

Additional notes about the device

Example: Connected to kitchen circuit

CreateSandboxWireDto

object · required

Source connection point

object · required

Target connection point

color

string

Wire color (hex code)

Example: #fbbf24

Default: #fbbf24

thickness

number

Wire thickness in pixels

Example: 3

Default: 3

label

string

Optional label for the wire

Example: Phase 1

UpdateSandboxWireDto

object

Source connection point

object

Target connection point

color

string

Wire color (hex code)

Example: #fbbf24

thickness

number

Wire thickness in pixels

Example: 3

label

string

Optional label for the wire

Example: Phase 1

UpdateSandboxElementsDto

SandboxDeviceInputDto[] · required

Array of all sandbox devices (replaces existing)

SandboxWireInputDto[] · required

Array of all sandbox wires (replaces existing)

CreateSurgeOverrideDto

name

string · required

Display name

Example: Boost 8 kWh

applicableEntityTypes

MonitoringEntityType[] · required

Entity types this override can be applied to

Enum values:

ROOM

TENANT

ZONE

thresholdKwh

number · required

Absolute daily threshold (kWh) granted while the override is active

Example: 8

price

number · required

Price

Example: 9.9

description

string

Customer-facing description

isActive

boolean

Whether the override is sellable

Default: true

SurgeOverrideResponseDto

_id

string · required

name

string · required

applicableEntityTypes

MonitoringEntityType[] · required

Enum values:

ROOM

TENANT

ZONE

thresholdKwh

number · required

price

number · required

isActive

boolean · required

createdAt

string · date-time · required

updatedAt

string · date-time · required

description

string

UpdateSurgeOverrideDto

name

string

Display name

Example: Boost 8 kWh

description

string

Customer-facing description

applicableEntityTypes

MonitoringEntityType[]

Entity types this override can be applied to

Enum values:

ROOM

TENANT

ZONE

thresholdKwh

number

Absolute daily threshold (kWh) granted while the override is active

Example: 8

price

number

Price

Example: 9.9

isActive

boolean

Whether the override is sellable

Default: true

PurchaseSurgeOverrideDto

surgeOverrideId

string · required

SurgeOverride catalog id

entityType

string · enum · required

Entity type the override should apply to

Enum values:

ROOM

TENANT

ZONE

entityId

string · required

Entity id (room/tenant/zone)

paymentId

string

Optional Payment record id to link to this purchase (refunds handled via payment module)

PurchaseStatus

string · enum

Enum values:

ACTIVE

CANCELLED

SurgeOverridePurchaseResponseDto

_id

string · required

surgeOverride

string · required

system

string · required

entityType

string · enum · required

Type of entity to start usage surge analysis for

Enum values:

ROOM

TENANT

ZONE

entityId

string · required

thresholdKwh

number · required

activeFrom

string · date-time · required

status

string · enum · required

Enum values:

ACTIVE

CANCELLED

purchasedBy

string · required

createdAt

string · date-time · required

updatedAt

string · date-time · required

payment

string

purchasedByName

string

Display name of the admin who purchased

entityName

string

Display name of the entity (room/tenant/zone)

cancelledAt

string · date-time

cancelledBy

string

cancelReason

string

CancelSurgeOverrideDto

reason

string

Reason supplied at cancellation time

Example: Customer requested refund

SurgeOverridePurchaseListResponseDto

SurgeOverridePurchaseResponseDto[] · required

total

number · required

page

number · required

size

number · required

SurgeOverridePurchaseActiveMapResponseDto

object · required

Map of entityId → active SurgeOverridePurchase. Only entities with an active override are included.

total

number · required

CreateSystemOnboardingDto

customerEmails

string[] · required

OnboardingStatus

string · enum

Enum values:

PENDING

IN_PROGRESS

COMPLETED

PhaseStatus

string · enum

Enum values:

PENDING

ACTIVE

SUGGESTIONS_READY

COMPLETED

OnboardingPhase

status

string · enum · required

Enum values:

PENDING

ACTIVE

SUGGESTIONS_READY

COMPLETED

startDate

string · date-time

gcalEventId

string

activationScheduledTaskName

string

AWS Scheduler task name for auto-activating this phase on startDate

endDate

string · date-time

DefaultStaticSchedule

DailyScheduleEntry[]

ScheduleGroup

plugIds

string[] · required

Plug IDs assigned to this schedule group

DefaultStaticSchedule · required

StaticSchedulePhase

status

string · enum · required

Enum values:

PENDING

ACTIVE

SUGGESTIONS_READY

COMPLETED

includePublicHolidays

boolean · required

startDate

string · date-time

gcalEventId

string

activationScheduledTaskName

string

AWS Scheduler task name for auto-activating this phase on startDate

endDate

string · date-time

object

Fallback schedule applied to unlocked plugs not in any scheduleGroup

ScheduleGroup[]

Per-group device schedules. Devices in a group get the group schedule; remaining unlocked devices get defaultStaticSchedule.

ascentAIScheduledTaskName

string

AscentAIPhase

status

string · enum · required

Enum values:

PENDING

ACTIVE

SUGGESTIONS_READY

COMPLETED

autoSuggestionsEnabled

boolean · required

startDate

string · date-time

gcalEventId

string

activationScheduledTaskName

string

AWS Scheduler task name for auto-activating this phase on startDate

endDate

string · date-time

suggestionsGeneratedAt

string · date-time

suggestionsActivatedAt

string · date-time

OnboardingIterationDto

iterationNumber

number · required

status

string · enum · required

Enum values:

PENDING

IN_PROGRESS

COMPLETED

OnboardingPhase · required

StaticSchedulePhase · required

AscentAIPhase · required

OnboardingPhase · required

name

string

startedAt

string · date-time

completedAt

string · date-time

ascentAiRecommendations

object

SystemOnboardingResponseDto

_id

string · required

system

string · required

customerEmails

string[] · required

activeIterationIndex

number · required

OnboardingIterationDto[] · required

createdAt

string · date-time · required

updatedAt

string · date-time · required

UpdateCustomerEmailsDto

customerEmails

string[] · required

DefaultStaticScheduleDto

DailyScheduleEntryDto[]

Monday schedule entries

DailyScheduleEntryDto[]

Tuesday schedule entries

DailyScheduleEntryDto[]

Wednesday schedule entries

DailyScheduleEntryDto[]

Thursday schedule entries

DailyScheduleEntryDto[]

Friday schedule entries

DailyScheduleEntryDto[]

Saturday schedule entries

DailyScheduleEntryDto[]

Sunday schedule entries

ScheduleGroupDto

plugIds

string[] · required

DefaultStaticScheduleDto · required

UpdateOnboardingPhaseDto

startDate

string

ISO 8601 date string

endDate

string

ISO 8601 date string

includePublicHolidays

boolean

object

Default schedule auto-applied to unlocked plugs on Phase 2 activation

ScheduleGroupDto[]

Per-group device schedules for Phase 2. Devices in a group get the group schedule; remaining unlocked devices get defaultStaticSchedule.

gcalEventTitle

string

gcalEventTime

string

ISO 8601 date string for the GCal event time (independent of phase startDate/endDate)

skipGcal

boolean

Set to true to skip GCal invite creation even if this phase normally requires one

EcoguardRecommendationDto

suitable

boolean · required

Whether this device category benefits from EcoGuard

Example: true

reason

string · required

Human-readable explanation shown to users

Example: This device type is suitable for EcoGuard idle detection.

suggestedIdleThreshold

number

Suggested idle power threshold in watts (with 1.1x buffer). Only present if suitable is true.

Example: 5.5

suggestedTimer

number

Suggested auto-shutoff timer in minutes. Only present if suitable is true.

Example: 30

RecommendationTier

string · enum

Enum values:

rule-based

clustering

llm

Recommendation tier used: "rule-based" (fast, ~5ms), "clustering" (medium, ~10ms), or "llm" (slow, ~60s). Indicates the analysis method used.

PlugRecommendationDto

deviceId

string · required

The unique identifier of the device (Plug or MCB)

Example: 507f1f77bcf86cd799439011

macId

string · required

The MAC address of the device

Example: AA:BB:CC:DD:EE:FF

deviceName

string · required

The name of the device for easy identification

Example: Office AC Unit

plugCategory

string · required

The category of the plug device (only for Plugs, empty for MCBs)

Example: Air Conditioning

DailyScheduleEntryDto[]

Array of AI-recommended schedule entries for Monday based on usage patterns

DailyScheduleEntryDto[]

Array of AI-recommended schedule entries for Tuesday based on usage patterns

DailyScheduleEntryDto[]

Array of AI-recommended schedule entries for Wednesday based on usage patterns

DailyScheduleEntryDto[]

Array of AI-recommended schedule entries for Thursday based on usage patterns

DailyScheduleEntryDto[]

Array of AI-recommended schedule entries for Friday based on usage patterns

DailyScheduleEntryDto[]

Array of AI-recommended schedule entries for Saturday based on usage patterns

DailyScheduleEntryDto[]

Array of AI-recommended schedule entries for Sunday based on usage patterns

summary

string

AI-generated summary explaining the recommended schedule and detected behavioral patterns

Example: Work-from-home behavior detected on weekdays with consistent 9 AM-5 PM active periods. Weekend usage minimal.

predictedIdleEnergyUsage

number

Predicted average power consumption during idle periods in watts based on historical data

Example: 12.3

totalNumberOfIdleHours

number

Total count of hours identified as idle or low-usage periods across the analysis timeframe

Example: 84

averageUsagePerDay

number

Average daily power consumption in watts calculated over the analyzed time period

Example: 42.7

flags

string[]

Array of flags highlighting anomalies, data gaps, or notable behavioral patterns detected by AI

Example: ["Insufficient data for Tuesday","Constant usage detected on Saturday","Casual/WFH usage pattern on Friday"]

object

EcoGuard suitability and suggested configuration for this device

deviceNumber

number

The device number assigned to the device

Example: 42

tier

string · enum

Recommendation tier used: "rule-based" (fast, ~5ms), "clustering" (medium, ~10ms), or "llm" (slow, ~60s). Indicates the analysis method used.

Enum values:

rule-based

clustering

llm

Example: rule-based

confidenceScore

number

Confidence score (0-1) indicating pattern clarity. Higher score = simpler, more predictable pattern.

Example: 0.95

BulkPlugRecommendationsResponseDto

object · required

Map of plug IDs to their AI-generated ON/OFF schedule recommendations. Each key is a plug ID, and the value contains the complete recommendation data including weekday schedules, summary, and metrics.

bulkSummary

string · required

AI-generated overall summary analyzing all plugs together. Identifies common patterns (e.g., "Working hours appear to be 9 AM - 6 PM across all devices"), optimization opportunities (e.g., "Coffee machine only used on Tuesdays and Thursdays"), cross-device insights, and collective energy-saving recommendations.

Example: Overall Pattern: Most devices show consistent weekday usage from 8 AM to 6 PM, suggesting office hours. The coffee machine is only active on Tuesday and Thursday mornings (7:30-9:00 AM), indicating team meeting days. Weekend usage is minimal across all devices. Optimization Opportunity: By implementing the recommended schedules, you could save an estimated 156 kWh per week (23% reduction). The AC unit has the highest optimization potential with 45 idle hours detected.

ReportFormat

string · enum

Enum values:

pdf

docx

json

excel

StartIterationDto

name

string

Optional name for this iteration, e.g. "Pilot", "Full Rollout"

UpdateIterationNameDto

name

string · required

New name for the iteration

IterationSummaryDto

iterationNumber

number · required

index

number · required

Zero-based index in the iterations array

status

string · enum · required

Enum values:

PENDING

IN_PROGRESS

COMPLETED

isActive

boolean · required

name

string

startedAt

string · date-time

completedAt

string · date-time

IterationListResponseDto

IterationSummaryDto[] · required

total

number · required

activeIterationIndex

number · required

ReportType

string · enum

Enum values:

TENANT

SYSTEM

ROOM

ZONE

Scope level for the requested AI-generated energy report (ROOM, SYSTEM, TENANT, or USER)

EnergyReportTypeDto

reportType

string · enum · required

Scope level for the requested AI-generated energy report (ROOM, SYSTEM, TENANT, or USER)

Enum values:

TENANT

SYSTEM

ROOM

ZONE

Example: ROOM

EnergyUsageRecommendationReportDto

DailyScheduleEntryDto[]

Array of AI-recommended schedule entries for Monday based on usage patterns

DailyScheduleEntryDto[]

Array of AI-recommended schedule entries for Tuesday based on usage patterns

DailyScheduleEntryDto[]

Array of AI-recommended schedule entries for Wednesday based on usage patterns

DailyScheduleEntryDto[]

Array of AI-recommended schedule entries for Thursday based on usage patterns

DailyScheduleEntryDto[]

Array of AI-recommended schedule entries for Friday based on usage patterns

DailyScheduleEntryDto[]

Array of AI-recommended schedule entries for Saturday based on usage patterns

DailyScheduleEntryDto[]

Array of AI-recommended schedule entries for Sunday based on usage patterns

summary

string

AI-generated summary explaining the recommended schedule and detected behavioral patterns

Example: Work-from-home behavior detected on weekdays with consistent 9 AM-5 PM active periods. Weekend usage minimal.

predictedIdleEnergyUsage

number

Predicted average power consumption during idle periods in watts based on historical data

Example: 12.3

totalNumberOfIdleHours

number

Total count of hours identified as idle or low-usage periods across the analysis timeframe

Example: 84

averageUsagePerDay

number

Average daily power consumption in watts calculated over the analyzed time period

Example: 42.7

flags

string[]

Array of flags highlighting anomalies, data gaps, or notable behavioral patterns detected by AI

Example: ["Insufficient data for Tuesday","Constant usage detected on Saturday","Casual/WFH usage pattern on Friday"]

object

EcoGuard suitability and suggested configuration for this device

BulkPlugRecommendationsRequestDto

plugIds

string[] · minItems: 1 · maxItems: 200 · required

Array of plug IDs to generate AI recommendations for. Minimum 1, maximum 200 plugs per request. For larger batches, split into multiple requests.

Example: ["507f1f77bcf86cd799439011","507f1f77bcf86cd799439012","507f1f77bcf86cd799439013"]

EnergyReportDto

reportType

string · enum · required

Scope level of this AI-generated energy report (ROOM, SYSTEM, TENANT, or USER)

Enum values:

TENANT

SYSTEM

ROOM

ZONE

Example: ROOM

executiveSummary

string · required

High-level executive summary highlighting the most important insights and findings

Example: This report provides a comprehensive analysis of energy usage patterns showing a 15% reduction in consumption and opportunities for further optimization.

consumptionAnalysis

string · required

Detailed analysis of overall energy consumption patterns including totals and peak periods

Example: Total consumption of 2,100 kWh in March 2025, with weekday peaks occurring between 12:00-15:00 and notable reductions during weekend hours.

scheduleRecommendations

string[] · required

Array of schedule-based recommendations comparing current plug schedules with actual usage patterns to optimize energy consumption. Each recommendation includes the plug name, current schedule, recommended changes, and estimated savings.

Example: ["Water Dispenser (Currently: ON 24/7, Recommended: OFF 10PM-6AM, Est. savings: **15 kWh/month**) /system/plugs/507f1f77bcf86cd799439011","Coffee Machine (Currently: No schedule, Recommended: OFF 7PM-7AM weekdays, OFF all day weekends, Est. savings: **22 kWh/month**) /system/plugs/507f1f77bcf86cd799439012","Conference Room Display (Currently: OFF 8PM-8AM, Recommended: OFF 6PM-8AM (usage drops at 6PM), Est. savings: **8 kWh/month**) /system/plugs/507f1f77bcf86cd799439013"]

createdAt

string · date-time

Timestamp when this AI report was generated by the system

Example: 2024-10-15T14:30:00.000Z

energyUsageBreakdown

string

Categorical breakdown of energy usage by device type or plug groupings showing percentage contributions

Example: Lighting plugs contributed 35% of total energy usage, followed by workstation outlets at 28%, and HVAC systems at 22%.

highLoadDevices

string[]

Array of plug devices or equipment with the highest power consumption for targeted optimization

Example: ["PRISM+ A453 TV (60W average)","HP ZBook Laptop Charger (45W average)","Lab Equipment Dryer #3 (120W average)"]

usageTrends

string

Temporal trends and recurring patterns identified across different days and hours from historical data

Example: Energy usage peaks during weekdays, especially on Tuesdays and Thursdays between 9 AM-5 PM. Weekend usage averages 40% lower than weekdays.

scheduleCompliance

string

Analysis of how well actual plug on/off behavior aligns with configured schedules

Example: 5% of devices remained active beyond their scheduled off periods, primarily affecting after-hours energy consumption.

anomalyInsights

string[]

Array of detected anomalies, unusual behaviors, or operational assumptions that may require attention

Example: ["Low power factor detected on Lab Equipment (0.65)","Sustained weekend idle load of 15W across multiple devices"]

estimatedCarbonEmissions

string

Calculated Scope 2 carbon emissions estimate based on energy consumption and regional emission factors

Example: Estimated carbon emissions for March 2025: 1.05 metric tons CO₂ equivalent based on local grid carbon intensity.

improvements

string

Comparative analysis showing improvement or decline in energy efficiency over time

Example: Energy usage has decreased by 10% compared to the previous month, driven by improved schedule adherence and reduced idle consumption.

DeviceStatusBreakdownDto

total

number · required

Total number of devices

Example: 5000

active

number · required

Number of active devices

Example: 4200

inactive

number · required

Number of inactive devices

Example: 600

offline

number · required

Number of offline devices

Example: 200

spare

number · required

Number of spare devices (excluded from active/inactive/offline counts)

Example: 50

TrendDirection

string · enum

Enum values:

down

stable

Trend direction

CostMetricDto

value

number · required

Current cost value (SGD)

Example: 37500.25

trend

number · required

Trend indicator (positive = increase, negative = decrease)

Example: 5.2

trendDirection

string · enum · required

Trend direction

Enum values:

down

stable

Example: up

Indicator

string · enum

Enum values:

positive

neutral

negative

Indicator status

CarbonMetricDto

value

number · required

Carbon emissions saved (kg CO₂)

Example: 52500.75

indicator

string · enum · required

Indicator status

Enum values:

positive

neutral

negative

Example: positive

PlatformOverviewDto

totalSystems

number · required

Total number of systems registered

Example: 150

totalTenants

number · required

Total number of active tenants

Example: 450

object · required

Total number of plugs with status breakdown

totalZones

number · required

Total number of active zones

Example: 1200

totalRooms

number · required

Total number of active rooms

Example: 800

totalEnergyMonitored

number · required

Total energy monitored across all systems (kWh)

Example: 125000.5

object · required

Estimated total energy cost (SGD)

object · required

Total carbon emissions avoided (kg CO₂)

TimePeriod

string · enum

Enum values:

daily

weekly

monthly

EnergyDataPointDto

label

string · required

Date/time label for the data point

Example: 2024-01-15

value

number · required

Energy value (kWh)

Example: 5250.5

timestamp

string · date-time · required

Timestamp of the data point

Example: 2024-01-15T00:00:00.000Z

EnergyUsageDto

period

string · enum · required

Time period used for aggregation

Enum values:

daily

weekly

monthly

Example: daily

totalEnergy

number · required

Total energy consumed in the period (kWh)

Example: 125000.5

EnergyDataPointDto[] · required

Energy usage data points

averageEnergy

number · required

Average energy per time unit (kWh)

Example: 5000.25

SystemEnergyDto

systemId

string · required

System ID

Example: 64b7f1e6f9c9d4e5b8a9f7c3

systemName

string · required

System name

Example: Building A - North Tower

energyConsumed

number · required

Total energy consumed (kWh)

Example: 52500.25

plugCount

number · required

Number of plugs in the system

Example: 250

percentageOfTotal

number · required

Percentage of total energy

Example: 21.5

rank

number · required

Rank position

Example: 1

TopSystemsDto

SystemEnergyDto[] · required

List of top systems by energy consumption

totalEnergy

number · required

Total energy consumed by all systems (kWh)

Example: 250000.5

HourlyUsageDto

hour

number · required

Hour of day (0-23)

Example: 18

energy

number · required

Energy consumed during this hour (kWh)

Example: 8500.5

percentageOfDay

number · required

Percentage of daily total

Example: 12.5

isPeak

boolean · required

Is this a peak hour?

Example: true

PeakHoursDto

HourlyUsageDto[] · required

Peak usage hours data

overallPeakHour

number · required

Overall peak hour

Example: 18

peakHourEnergy

number · required

Peak hour energy value (kWh)

Example: 8500.5

offPeakAverageEnergy

number · required

Off-peak average energy (kWh)

Example: 3200.25

GrowthDataPointDto

month

string · required

Month label

Example: Jan 2024

count

number · required

Number of new active plugs (>1kWh)

Example: 125

cumulative

number · required

Cumulative total

Example: 1250

date

string · date-time · required

Date of the data point

Example: 2024-01-01T00:00:00.000Z

GrowthTrendDto

GrowthDataPointDto[] · required

Monthly growth data points

totalGrowth

number · required

Total growth count

Example: 1250

averageMonthlyGrowth

number · required

Average monthly growth

Example: 104.2

growthRate

number · required

Growth rate percentage

Example: 25.5

ProjectionDataPointDto

month

string · required

Month label

Example: Apr 2024

projectedCount

number · required

Projected device count

Example: 145

lowerBound

number · required

Lower bound estimate

Example: 130

upperBound

number · required

Upper bound estimate

Example: 160

date

string · date-time · required

Date of projection

Example: 2024-04-01T00:00:00.000Z

RegressionParametersDto

slope

number · required

Slope coefficient

Example: 12.5

intercept

number · required

Y-intercept

Example: 1000

rSquared

number · required

R-squared value (goodness of fit)

Example: 0.92

GrowthProjectionDto

ProjectionDataPointDto[] · required

Projected growth for next 3 months

object · required

Linear regression parameters

expectedTotal

number · required

Expected total devices after 3 months

Example: 1650

confidence

number · required

Confidence level (0-1)

Example: 0.85

RoleCountDto

role

string · required

Role name

Example: SUPERADMIN

count

number · required

Number of admins with this role

Example: 25

percentage

number · required

Percentage of total

Example: 10

RoleDistributionDto

RoleCountDto[] · required

Role distribution data

totalAdmins

number · required

Total number of admins

Example: 250

CategoryCountDto

category

string · required

Plug category

Example: AIR_CONDITIONER

count

number · required

Number of plugs in this category

Example: 850

percentage

number · required

Percentage of total plugs

Example: 17

PlugCategoryDistributionDto

CategoryCountDto[] · required

Category distribution data

totalPlugs

number · required

Total number of plugs

Example: 5000

CategoryEnergyDto

category

string · required

Plug category

Example: AIRCONDITIONER

energy

number · required

Total energy consumed by this category (kWh)

Example: 52500.25

percentage

number · required

Percentage of total energy

Example: 42

plugCount

number · required

Number of plugs in category

Example: 850

averageEnergyPerPlug

number · required

Average energy per plug (kWh)

Example: 61.76

PlugCategoryEnergyDistributionDto

CategoryEnergyDto[] · required

Category energy distribution data

totalEnergy

number · required

Total energy consumed (kWh)

Example: 125000.5

SystemPlugCountDto

systemId

string · required

System ID

Example: 64b7f1e6f9c9d4e5b8a9f7c3

systemName

string · required

System name

Example: Building A - North Tower

plugCount

number · required

Number of plugs in this system

Example: 250

percentage

number · required

Percentage of total plugs

Example: 5

PlugSystemDistributionDto

SystemPlugCountDto[] · required

System distribution data

totalPlugs

number · required

Total number of plugs

Example: 5000

totalSystems

number · required

Total number of systems

Example: 150

CategoryAnalyticsResponseDto

category

string · required

The plug category being analyzed

Example: AIRCONDITIONER

numberOfDevices

number · required

Number of devices in this category

Example: 15

UsageHistoryDayBreakdownDto[] · required

Daily energy usage breakdown

totalKwh

number · required

Total kWh consumed in the period

Example: 1234.56

averageKwhPerDay

number · required

Average kWh per day across all devices in category

Example: 82.3

averageKwhPerDayPerDevice

number · required

Average kWh per day per device

Example: 5.49

predictedKwhPerYear

number · required

Predicted kWh consumption per year (based on average)

Example: 30033.95

totalCostSgd

number · required

Total cost in SGD for the period (at $0.3065/kWh)

Example: 378.39

predictedAnnualCostSgd

number · required

Predicted annual cost in SGD (at $0.3065/kWh)

Example: 9205.41

predictedAnnualCostPerDeviceSgd

number · required

Predicted annual cost in SGD per device (at $0.3065/kWh)

Example: 613.69

GranularityType

string · enum

Enum values:

hour

day

week

month

Time granularity for data aggregation

EnergyBreakdownRequestDto

systemId

string · required

System ID

Example: 64b7f1e6f9c9d4e5b8a9f7c3

startDate

string · required

Start date for energy data (ISO 8601 format)

Example: 2024-01-01

endDate

string · required

End date for energy data (ISO 8601 format)

Example: 2024-01-31

granularity

string · enum · required

Time granularity for data aggregation

Enum values:

hour

day

week

month

Example: day

compareStartDate

string

Start date for comparison period (optional)

Example: 2023-01-01

compareEndDate

string

End date for comparison period (optional)

Example: 2023-01-31

EnergyBreakdownPointDto

timestamp

string · required

Timestamp of this data point

Example: 2024-01-01T00:00:00.000Z

energy

number · required

Energy consumption in kWh

Example: 12.45

cost

number · required

Cost in SGD (calculated using tariff rate active at this timestamp)

Example: 3.82

tariffRate

number · required

Tariff rate used for this calculation (cents per kWh)

Example: 30.65

EnergyPeriodDto

totalEnergy

number · required

Total energy consumption for period (kWh)

Example: 450.25

totalCost

number · required

Total cost for period (SGD)

Example: 138.02

EnergyBreakdownPointDto[] · required

Breakdown by time bucket

EnergyComparisonDto

totalEnergy

number · required

Total energy consumption for period (kWh)

Example: 450.25

totalCost

number · required

Total cost for period (SGD)

Example: 138.02

EnergyBreakdownPointDto[] · required

Breakdown by time bucket

energyDelta

number · required

Energy delta compared to main period (kWh)

Example: -45.5

costDelta

number · required

Cost delta compared to main period (SGD)

Example: -13.96

EnergyBreakdownResponseDto

object · required

Main period energy and cost data

calculatedAt

string · required

Timestamp when these costs were calculated

Example: 2024-01-15T10:30:00.000Z

object

Comparison period data (if comparison dates provided)

ToolDefinitionDto

name

string · required

Tool name (unique identifier)

description

string · required

Tool description for LLM

object · required

JSON Schema for tool input parameters

AgentChatRequestDto

ChatMessageDto[] · required

Conversation history including user and assistant messages

systemId

string · required

System ID the chat operates on. Required — used to enforce the AI_FEATURE entitlement and to scope context-aware tool calls.

ToolDefinitionDto[]

Available tools for the LLM to call

sessionId

string

Session ID for chat history persistence

TranscribeAudioResponseDto

text

string · required

Transcribed text from the audio recording

RangerChatHistorySummaryDto

sessionId

string · required

UUID identifying the chat session

Example: 550e8400-e29b-41d4-a716-446655440000

messageCount

number · required

Total number of messages in the session

Example: 6

preview

string · required

First user message truncated to 120 chars

Example: How much energy did Building A consume last week?

createdAt

string · date-time · required

Timestamp when the session was first created

Example: 2024-01-15T08:30:00.000Z

updatedAt

string · date-time · required

Timestamp of the last message saved to this session

Example: 2024-01-15T08:35:00.000Z

adminEmail

string

Email of the account that initiated the session

Example: admin@example.com

RangerChatHistoryPaginatedDto

total

number · required

Total count of items matching filters

Example: 150

page

number · min: 1 · required

Current page number

Example: 1

size

number · min: 1 · required

Items per page

Example: 50

totalPages

number · min: 0 · required

Total number of pages

Example: 3

RangerChatHistorySummaryDto[] · required

Chat session summaries for the current page

RangerChatHistoryDetailDto

sessionId

string · required

UUID identifying the chat session

Example: 550e8400-e29b-41d4-a716-446655440000

messageCount

number · required

Total number of messages in the session

Example: 6

preview

string · required

First user message truncated to 120 chars

Example: How much energy did Building A consume last week?

createdAt

string · date-time · required

Timestamp when the session was first created

Example: 2024-01-15T08:30:00.000Z

updatedAt

string · date-time · required

Timestamp of the last message saved to this session

Example: 2024-01-15T08:35:00.000Z

ChatMessageDto[] · required

adminEmail

string

Email of the account that initiated the session

Example: admin@example.com

CalendarPreviewRoomDto

roomId

string · required

Room ID

roomName

string · required

Room name as stored in the system

deviceCount

number · required

Number of devices in this room that would receive schedules

RecurrenceType

string · enum

Enum values:

DAILY

WEEKLY

Recurrence pattern type. Only present when isRecurring is true.

CalendarPreviewEventDto

uid

string · required

External event ID — Google event ID, iCal UID, or Microsoft event ID

eventTitle

string · required

Original event title from the calendar

startTime

string · date-time · required

Event start time

endTime

string · date-time · required

Event end time

matched

boolean · required

True if at least one room matched the event title

include

boolean · required

Whether to include this event in the confirm step. Defaults to true when matched, false when unmatched.

CalendarPreviewRoomDto[] · required

Rooms matched from the event title. Empty when matched=false.

isRecurring

boolean · required

True if the event is a recurring event (daily or weekly pattern)

recurrenceType

string · enum

Recurrence pattern type. Only present when isRecurring is true.

Enum values:

DAILY

WEEKLY

recurrenceDays

number[]

Days of week the event recurs on (0=Sun … 6=Sat). Only present for weekly recurrence.

Example: [1,3,5]

CalendarPreviewResponseDto

CalendarPreviewEventDto[] · required

List of calendar events parsed from the calendar source, each with room-match results.

totalMatched

number · required

Number of events that matched at least one room

totalUnmatched

number · required

Number of events that matched no room

ScheduleType

string · enum

Enum values:

SINGLE

RECURRING

Schedule type: single one-time schedule or recurring weekly schedule

ConfirmCalendarEventDto

uid

string · required

External event ID (from preview response)

eventTitle

string · required

Event title (used for mapping storage)

startTime

string · required

Event start time (may be user-adjusted)

endTime

string · required

Event end time (may be user-adjusted)

include

boolean · required

Set to false to skip this event — no schedules will be created for it

roomIds

string[] · required

Room IDs to schedule (may be user-adjusted from preview)

scheduleType

string · enum · required

Schedule type: single one-time schedule or recurring weekly schedule

Enum values:

SINGLE

RECURRING

daysOfWeek

number[]

Days of week for recurring schedule (0=Sun … 6=Sat). Required when scheduleType is RECURRING.

Example: [1,3]

onTime

string

ON time for recurring schedule in HH:MM format. Required when scheduleType is RECURRING.

Example: 09:00

offTime

string

OFF time for recurring schedule in HH:MM format. Required when scheduleType is RECURRING.

Example: 17:00

ConfirmCalendarUploadDto

ConfirmCalendarEventDto[] · required

List of calendar events to confirm. Must contain at least one entry.

gracePeriodMinutes

number

Grace period in minutes. Devices turn ON this many minutes before the event starts and turn OFF this many minutes after it ends. Only applies to one-time (SINGLE) schedules. Defaults to 0.

Example: 15

Default: 0

CalendarImportResultDto

imported

number · required

Number of events for which schedules were successfully created

Example: 5

skipped

number · required

Number of events skipped (include=false, past, or no devices in room)

Example: 2

PreviewIcsUrlDto

icsUrl

string · required

Publicly accessible ICS calendar feed URL. Must be a valid HTTPS URL pointing to a .ics file. Private/internal network addresses are not permitted.

Example: https://calendar.google.com/calendar/ical/example%40gmail.com/public/basic.ics

ConfirmIcsUrlDto

icsUrl

string · required

Publicly accessible ICS calendar feed URL. Saved for ongoing background polling. Must be HTTPS; private/internal addresses are not permitted.

Example: https://calendar.google.com/calendar/ical/example%40gmail.com/public/basic.ics

ConfirmCalendarEventDto[] · required

List of calendar events to confirm. Must contain at least one entry.

gracePeriodMinutes

number

Grace period in minutes. Devices turn ON this many minutes before the event starts and turn OFF this many minutes after it ends. Saved for ongoing syncs. Defaults to 0.

Example: 15

Default: 0

SubscribeIcsUrlDto

icsUrl

string · required

Publicly accessible ICS calendar feed URL. Must be a valid HTTPS URL pointing to a .ics file. Private/internal network addresses are not permitted.

Example: https://calendar.google.com/calendar/ical/example%40gmail.com/public/basic.ics

gracePeriodMinutes

number

Grace period in minutes. Devices turn ON this many minutes before the event starts and turn OFF this many minutes after it ends. Defaults to 0.

Example: 15

Default: 0

CalendarType

string · enum

Enum values:

GOOGLE

MICROSOFT

ICS_URL

ICS_FILE

The calendar provider type for this connection (e.g., GOOGLE, MICROSOFT, ICS)

ConnectionScope

string · enum

Enum values:

SYSTEM

USER

Scope of this connection — whether it applies system-wide or per-user

CalendarConnectionResponseDto

id

string · required

Unique identifier of the calendar connection

Example: 64b7f1e6f9c9d4e5b8a9f7c3

systemId

string · required

System this calendar connection belongs to

Example: 64b7f1e6f9c9d4e5b8a9f7c1

calendarType

string · enum · required

The calendar provider type for this connection (e.g., GOOGLE, MICROSOFT, ICS)

Enum values:

GOOGLE

MICROSOFT

ICS_URL

ICS_FILE

Example: GOOGLE

scope

string · enum · required

Scope of this connection — whether it applies system-wide or per-user

Enum values:

SYSTEM

USER

Example: SYSTEM

isActive

boolean · required

Whether this calendar connection is currently active

Example: true

createdAt

string · date-time · required

Timestamp when this calendar connection was created

userId

string

Admin user ID that owns this connection; null indicates a system-wide connection

Example: 64b7f1e6f9c9d4e5b8a9f7c2

googleCalendarId

string

Google Calendar ID used for this connection (e.g., "primary")

Example: primary

icsUrl

string

ICS feed URL for ICS-type calendar connections

Example: https://calendar.google.com/calendar/ical/example%40gmail.com/public/basic.ics

lastSyncedAt

string · date-time

Timestamp of the last successful sync for this connection

EntityTypeKind

string · enum

Enum values:

ROOM

TENANT

ZONE

EntityTypeResponseDto

_id

string · required

Entity type ID

name

string · required

Unique type key

Example: MEETING_ROOM

displayName

string · required

Human-readable display name

Example: Meeting Room

system

string · required

System ID this type belongs to

createdAt

string · date-time · required

Creation timestamp

createdBy

string

Admin who created this type

EntityTypeListResponseDto

EntityTypeResponseDto[] · required

total

number · required

CreateEntityTypeDto

name

string · required

Unique type key — must be UPPER_SNAKE_CASE, unique within the system

Example: MEETING_ROOM

displayName

string · required

Human-readable display name

Example: Meeting Room

UpdateEntityTypeDto

displayName

string · required

Human-readable display name

Example: Meeting Room

Generate2dFloorPlanResponseDto

floorPlanId

string · required

Floor plan document ID (upserted)

plan2d

object · required

2D geometry preview — not yet saved

Room2DDto

id

string · required

name

string · required

type

string · required

polygon

array[] · required

CCW polygon vertices [[x,z],...]

Opening2DDto

start

number · required

end

number · required

kind

string · required

Wall2DDto

start

number[] · required

[x, z] coordinate

end

number[] · required

[x, z] coordinate

kind

string · required

Opening2DDto[]

Stair2DDto

id

string · required

bottom

number[] · required

[x, z] coordinate

top

number[] · required

[x, z] coordinate

width

number · required

FloorPlanStyle

string · enum

Enum values:

DEFAULT

WARM

COOL

NIGHT

Visual style/theme for the 3D floor plan

Save2dFloorPlanDto

width

number · required

height

number · required

Room2DDto[] · required

Wall2DDto[] · required

Stair2DDto[] · required

style

string · enum

Visual style/theme for the 3D floor plan

Enum values:

DEFAULT

WARM

COOL

NIGHT

Default: DEFAULT

Plan2dStatus

string · enum

Enum values:

none

draft

ready

FloorPlan

_id

string · required

zone

string · required

Zone this floor plan belongs to

system

string · required

System this floor plan belongs to

name

string · required

Display name for this floor plan

schemaVersion

number · required

Floor plan JSON schema version

Example: 1

plan2dStatus

string · enum · required

Enum values:

none

draft

ready

style

string · enum · required

Visual style/theme for the 3D floor plan

Enum values:

DEFAULT

WARM

COOL

NIGHT

Default: DEFAULT

plan2d

object

2D geometry before 3D conversion

roomMappings

string[]

Mappings from AI room IDs to real Room documents

RenameRoomDto

jsonRoomId

string · required

newName

string · required

MapRoomDto

jsonRoomId

string · required

realRoomId

string

Real Room ObjectId — omit or null to unmap

CreateIssueDto

title

string · required

Issue title

body

string · required

Issue body

labels

string[] · required

Labels to add

Example: ["bug","backend"]

assignees

string[]

Assignees to add

Example: ["glenn-quah"]

imageUrl

string

Public URL of an image to embed

Example: https://example.com/image.png

image

string

Image file to upload and embed

IssueDto

id

number · required

number

number · required

title

string · required

body

string · required

state

string · required

url

string · required

createdAt

string · required

authorLogin

string · required

authorAvatarUrl

string · required

authorUrl

string · required

labels

string[] · required

assignees

string[] · required

ReleaseNotesRepository

string · enum

Enum values:

software

hardware

ReleaseNoteDto

tagName

string · required

Git tag version of the release

Example: v1.2.0

title

string · required

Title of the release (usually same as tag or human readable)

Example: Version 1.2.0

body

string · required

Full markdown content of the release note

Example: ## 🚀 Features - Added dashboard - Improved sync ## 🐛 Fixes - Fixed login bug

publishedAt

string · date-time · required

Date when the release was published

Example: 2024-07-06T10:00:00Z

url

string · required

URL linking to the release on GitHub

Example: https://github.com/ecovolt-sg/ecovolt-external-apis/releases/tag/v1.2.0

developerName

string · required

Name of the developer who created the release

Example: Glenn Quah Han Rong

developerUrl

string · required

URL of the developer's GitHub profile

Example: https://github.com/glennquahhanrong

developerAvatarUrl

string · required

Avatar URL of the developer who created the release

Example: https://avatars.githubusercontent.com/u/12345678?v=4

PaymentMethod

string · enum

Enum values:

CREDIT_CARD

PAYPAL

STRIPE

GOOGLE_PAY

APPLE_PAY

SAMSUNG_PAY

PAYLAH

BANK_TRANSFER

Method used for payment processing. Determines the payment gateway and processing flow.

PaymentStatus

string · enum

Enum values:

PENDING

COMPLETED

FAILED

REFUNDED

Current status of the payment transaction. Tracks the payment lifecycle from pending to completion or failure.

PaymentValidityPeriod

string · enum

Enum values:

MONTHLY

QUARTERLY

YEARLY

Duration of the subscription period covered by this payment. Determines how long the system will have access to paid features.

CreatePaymentDto

amount

number · required

Payment amount in the base currency. Represents the total cost for the subscription period.

Example: 99.99

paymentMethod

string · enum · required

Method used for payment processing. Determines the payment gateway and processing flow.

Enum values:

CREDIT_CARD

PAYPAL

STRIPE

GOOGLE_PAY

APPLE_PAY

SAMSUNG_PAY

PAYLAH

BANK_TRANSFER

Example: CREDIT_CARD

status

string · enum · required

Current status of the payment transaction. Tracks the payment lifecycle from pending to completion or failure.

Enum values:

PENDING

COMPLETED

FAILED

REFUNDED

Example: COMPLETED

externalPaymentId

string · required

External reference ID from the payment gateway. Used for tracking and reconciliation with third-party payment providers.

Example: pi_3MtwBwLkdIwHu7ix28a3tqPa

adminId

string · required

Unique identifier of the admin who initiated the payment. Links the payment to the admin account.

Example: 64b7f1e6f9c9d4e5b8a9f7c1

systemId

string · required

Unique identifier of the system for which the payment is made. Links the payment to the system subscription.

Example: 64b7f1e6f9c9d4e5b8a9f7c2

paymentDate

string · required

Date and time when the payment was processed. Used for billing records and subscription start date calculation.

Example: 2024-10-15T14:30:00Z

validityPeriod

string · enum · required

Duration of the subscription period covered by this payment. Determines how long the system will have access to paid features.

Enum values:

MONTHLY

QUARTERLY

YEARLY

Example: MONTHLY

subscriptionTierId

string · required

Unique identifier of the subscription tier being purchased. Determines the feature set and limitations for the payment period.

Example: 64b7f1e6f9c9d4e5b8a9f7c3

message

string

Additional notes or transaction details. Useful for documenting special circumstances or payment gateway responses.

Example: Payment processed successfully via Stripe

Payment

_id

string · required

The unique identifier of the subscription tier

Example: 64b7f1e6f9c9d4e5b8a9f7c3

amount

number · required

Payment amount

Example: 9.99

paymentMethod

string · enum · required

Payment method

Enum values:

CREDIT_CARD

PAYPAL

STRIPE

GOOGLE_PAY

APPLE_PAY

SAMSUNG_PAY

PAYLAH

BANK_TRANSFER

paymentDate

string · date-time · required

Payment Date

Example: 2023-08-01T12:00:00Z

validityPeriod

string · enum · required

Payment validity period

Enum values:

MONTHLY

QUARTERLY

YEARLY

status

string · enum · required

Payment status

Enum values:

PENDING

COMPLETED

FAILED

REFUNDED

Example: completed

externalPaymentId

string · required

External payment ID

Example: DBS_1Ff7Q2L2z2z2z2

admin

string · required

Admin ID reference

system

string · required

System ID reference

object · required

The subscription tier associated with the payment

createdAt

string · date-time · required

The date when the payment was created

Example: 2023-08-01T12:00:00Z

updatedAt

string · date-time · required

The date when the payment was last updated

Example: 2023-08-01T12:00:00Z

isDeleted

boolean · required

Indicates whether the payment is deleted

Example: false

Default: false

message

string

Optional message or reason for the payment status update

Example: Payment was successful

GetPaymentsDto

Payment[] · required

Array of payment records

total

number · required

Total number of payments matching the filter

Example: 100

page

number · required

Current page number

Example: 1

size

number · required

Number of items per page

Example: 10

UpdatePaymentStatusDto

status

string · enum · required

New payment status to update. Used to transition the payment through its lifecycle (pending, completed, failed, refunded).

Enum values:

PENDING

COMPLETED

FAILED

REFUNDED

Example: COMPLETED

message

string

Additional notes explaining the status update. Useful for documenting reasons for failures, refunds, or special circumstances.

Example: Payment confirmed by payment gateway after initial delay

CreateFeatureDto

name

string · required

Display name of the feature. Used for identification in the user interface.

Example: Tenant Management

featureType

string · enum · required

Feature type identifier from the predefined feature enum. Determines the functional category of the feature.

Enum values:

ZONE_MANAGEMENT

ROOMS_MANAGEMENT

RELATIONSHIP_MAP

ADMIN_PANEL

TENANT_MANAGEMENT

SMART_PLUGS

AI_FEATURE

HEATMAP

Example: TENANT_MANAGEMENT

description

string · required

Detailed description of what the feature does and its purpose within the system.

Example: Allows management of tenants within the system, including creation, updates, and relationship assignments

UpdateFeatureDto

name

string · required

Display name of the feature. Used for identification in the user interface.

Example: Tenant Management

featureType

string · enum · required

Feature type identifier from the predefined feature enum. Determines the functional category of the feature.

Enum values:

ZONE_MANAGEMENT

ROOMS_MANAGEMENT

RELATIONSHIP_MAP

ADMIN_PANEL

TENANT_MANAGEMENT

SMART_PLUGS

AI_FEATURE

HEATMAP

Example: TENANT_MANAGEMENT

description

string · required

Detailed description of what the feature does and its purpose within the system.

Example: Allows management of tenants within the system, including creation, updates, and relationship assignments

CreateSubscriptionTierDto

name

string · required

Name of the subscription tier. Used for identification and display to customers.

Example: Premium

description

string · required

Detailed description of what the subscription tier includes. Helps customers understand the value proposition.

Example: Access to all premium features including advanced analytics, unlimited users, and priority support

monthlyPrice

number · required

Monthly subscription price in the base currency. Billed on a monthly basis.

Example: 29.99

quarterlyPrice

number · required

Quarterly subscription price in the base currency. Typically offered at a discount compared to monthly pricing.

Example: 79.99

yearlyPrice

number · required

Annual subscription price in the base currency. Usually offers the best value with maximum discount.

Example: 299.99

features

string[] · required

Array of feature identifiers included in this subscription tier. Determines which features are accessible to subscribers.

Example: ["64b7f1e6f9c9d4e5b8a9f7c1","64b7f1e6f9c9d4e5b8a9f7c2"]

UpdateSubscriptionTierDto

name

string · required

Name of the subscription tier. Used for identification and display to customers.

Example: Premium

description

string · required

Detailed description of what the subscription tier includes. Helps customers understand the value proposition.

Example: Access to all premium features including advanced analytics, unlimited users, and priority support

monthlyPrice

number · required

Monthly subscription price in the base currency. Billed on a monthly basis.

Example: 29.99

quarterlyPrice

number · required

Quarterly subscription price in the base currency. Typically offered at a discount compared to monthly pricing.

Example: 79.99

yearlyPrice

number · required

Annual subscription price in the base currency. Usually offers the best value with maximum discount.

Example: 299.99

features

string[] · required

Array of feature identifiers included in this subscription tier. Determines which features are accessible to subscribers.

Example: ["64b7f1e6f9c9d4e5b8a9f7c1","64b7f1e6f9c9d4e5b8a9f7c2"]

TelegramStatusResponseDto

connected

boolean · required

Whether this system has a Telegram group linked

Example: true

groupName

string

Name of the linked Telegram group

Example: EcoVolt Alerts

TelegramPairingCodeResponseDto

code

string · required

Short pairing code the admin sends in their Telegram group

Example: ECO-A3B7

expiresIn

number · required

Seconds until the code expires

Example: 600

TelegramWebhookDto

RegisterWebhookResponseDto

ok

boolean · required

Whether the request was successful

Example: true

result

boolean · required

Telegram API result

Example: true

description

string

Description from Telegram

Example: Webhook was set

ForecastGranularity

string · enum

Enum values:

HOURLY

DAILY

ForecastPointDto

hour

string · required

ISO 8601 UTC timestamp

kWh

number · required

Predicted energy usage (kWh)

lower

number · required

Lower confidence bound (kWh)

upper

number · required

Upper confidence bound (kWh)

ForecastReason

string · enum

Enum values:

insufficient_data

no_forecast_available

Set only when predictions is empty. insufficient_data: device has < 30 days of usage history (expected for new devices). no_forecast_available: device qualifies but no fresh forecast doc exists (precompute failed or has not yet run for this device).

DeviceForecastResponseDto

deviceId

string · required

Unique identifier for the device

ForecastPointDto[] · required

Forecast data points for the device

modelVersion

string · required

Model version

granularity

string · required

Granularity of returned data

hasSufficientData

boolean · required

Whether this device has sufficient data for forecasting

reason

string · enum

Enum values:

insufficient_data

no_forecast_available

daysUntilEligible

number

Only present when reason = insufficient_data. Number of additional days of usage history needed before the device becomes eligible.

AggregatedForecastResponseDto

entityId

string · required

Entity ID (zone, tenant, or system)

entityType

string · required

Entity type (zone, tenant, or system)

ForecastPointDto[] · required

Aggregated forecast (sum of all device forecasts under this entity)

totalDevices

number · required

Total devices included in aggregation

devicesWithSufficientData

number · required

Devices that contributed predictions to the aggregated forecast

devicesWithInsufficientData

number · required

Devices with < 30 days of usage history

devicesWithoutForecast

number · required

Devices that qualify (>= 30 days) but have no fresh forecast doc — precompute has not yet reached them, or failed for those devices

granularity

string · required

Granularity of returned data

TrainingStatus

string · enum

Enum values:

failed

Outcome of the training run

TrainingStatusDto

status

string · enum · required

Outcome of the training run

Enum values:

failed

Example: ok

completedAt

string · required

ISO 8601 timestamp of when training completed

Example: 2026-05-18T10:30:00.000Z

error

string

Error message if training failed

Example: Insufficient data for model convergence

PrecomputeStatusDto

completedAt

string · required

ISO 8601 timestamp of when precompute completed

ok

number · required

Forecast documents successfully written

failed

number · required

Devices that failed during precompute

eligibleDevices

number · required

Total eligible devices processed

skippedDevices

number · required

Devices skipped due to insufficient data

CreateProductDto

name

string · required

Name of the product

Example: Smart Plug

price

number · required

Price of the product

Example: 9.99

description

string

Description of the product

Example: A smart plug that can be controlled remotely

UpdateProductDto

name

string

Name of the product

Example: Smart Plug Pro

description

string

Description of the product

Example: An upgraded smart plug with additional features

price

number

Price of the product

Example: 12.99

ErrorSource

string · enum

Enum values:

FRONTEND

BACKEND

Origin of the error

ReportingApp

string · enum

Enum values:

BASE

TREK

LANDING_PAGE

EVEREST

Frontend app the error was reported from (FRONTEND errors)

HttpRequestMethod

string · enum

Enum values:

GET

POST

PUT

PATCH

DELETE

HEAD

OPTIONS

HTTP method of the failed request

CreateErrorLogDto

source

string · enum · required

Origin of the error

Enum values:

FRONTEND

BACKEND

Example: FRONTEND

httpMethod

string · enum · required

HTTP method of the failed request

Enum values:

GET

POST

PUT

PATCH

DELETE

HEAD

OPTIONS

Example: GET

requestUrl

string · required

URL of the HTTP request that failed

Example: /api/plug/system/64b7/list

errorMessage

string · required

Description of the error

Example: Network Error: Failed to fetch plug list

statusCode

number · required

HTTP status code received

Example: 500

reportedApp

string · enum

Frontend app the error was reported from (FRONTEND errors)

Enum values:

BASE

TREK

LANDING_PAGE

EVEREST

Example: EVEREST

pageUrl

string

Frontend page URL where the error occurred (FRONTEND errors)

Example: https://app.ecovolt.sg/system/64b7/dashboard

system

string

System the account was operating in when the error occurred

Example: 64b7f1e6f9c9d4e5b8a9f7c3

stackTrace

string

Stack trace string (BACKEND errors)

ErrorLogSystemRefDto

_id

string · required

systemName

string · required

ErrorLogAdminRefDto

_id

string · required

name

string · required

email

string · required

GetErrorLogDto

_id

string · required

Primary ID of the error log

Example: 64b7f1e6f9c9d4e5b8a9f7c3

source

string · enum · required

Origin of the error

Enum values:

FRONTEND

BACKEND

Example: FRONTEND

httpMethod

string · enum · required

HTTP method of the failed request

Enum values:

GET

POST

PUT

PATCH

DELETE

HEAD

OPTIONS

Example: GET

requestUrl

string · required

URL of the HTTP request that failed

Example: /api/plug/system/64b7/list

errorMessage

string · required

Description of the error

Example: Network Error: Failed to fetch plug list

statusCode

number · required

HTTP status code received

Example: 500

solved

boolean · required

Whether this error has been resolved

Example: false

createdAt

string · date-time · required

Timestamp when the log was created

updatedAt

string · date-time · required

Timestamp when the log was last updated

reportedApp

string · enum

Frontend app the error was reported from (FRONTEND only)

Enum values:

BASE

TREK

LANDING_PAGE

EVEREST

Example: EVEREST

pageUrl

string

Frontend page URL where the error occurred (FRONTEND only)

Example: https://app.ecovolt.sg/system/64b7/dashboard

object

System the account was operating in when the error occurred

object

Admin (Account) that encountered the error — present for FRONTEND errors, absent for BACKEND errors

stackTrace

string

Stack trace string (BACKEND errors only)

resolvedAt

string · date-time

Timestamp when the error was marked as resolved

Example: 2026-06-02T10:00:00.000Z

object

Admin (SUPERADMIN) who resolved the error

GetErrorLogsResponseDto

total

number · required

Total count of items matching filters

Example: 150

page

number · min: 1 · required

Current page number

Example: 1

size

number · min: 1 · required

Items per page

Example: 50

totalPages

number · min: 0 · required

Total number of pages

Example: 3

GetErrorLogDto[] · required

Array of error log entries

UpdateErrorLogDto

solved

boolean · required

Mark the error as resolved or unresolved

Example: true

NfcTargetType

string · enum

Enum values:

ROOM

DEVICE

Target type

GenerateNfcTokenResponseDto

token

string · required

Encrypted NFC token

Example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

publicUrl

string · required

Public URL for NFC page

Example: http://localhost:3000/nfc/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

nfcId

string · required

NFC document ID

Example: 64b7f1e6f9c9d4e5b8a9f7c3

targetType

string · enum · required

Target type

Enum values:

ROOM

DEVICE

Example: ROOM

targetId

string · required

Target ID (room or device)

Example: 64b7f1e6f9c9d4e5b8a9f7c3

targetName

string · required

Target name

Example: Conference Room A

createdAt

string · date-time · required

Created at timestamp

Example: 2026-02-06T08:30:00.000Z

NfcTokenInfoDto

nfcId

string · required

NFC document ID

Example: 64b7f1e6f9c9d4e5b8a9f7c3

targetType

string · enum · required

Target type

Enum values:

ROOM

DEVICE

Example: ROOM

targetId

string · required

Target ID

Example: 64b7f1e6f9c9d4e5b8a9f7c3

targetName

string · required

Target name

Example: Conference Room A

usageCount

number · required

Token usage count

Example: 42

isActive

boolean · required

Whether token is active

Example: true

token

string · required

Encrypted token string

Example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

createdAt

string · date-time · required

Created at timestamp

Example: 2026-02-06T08:30:00.000Z

expiresAt

string · date-time

Optional expiration date

Example: 2026-12-06T08:30:00.000Z

ListNfcTokensResponseDto

NfcTokenInfoDto[] · required

List of NFC tokens

total

number · required

Total number of tokens

Example: 5

NfcToggleDto

onStatus

string · enum · required

Target device status

Enum values:

OFF

INACTIVE

ERROR

ACTIVE

Example: ON

deviceId

string

Optional device ID to toggle specific device in room (room tokens only)

Example: 64b7f1e6f9c9d4e5b8a9f7c3

NfcToggleResponseDto

successful

string[] · required

Successfully toggled device IDs

Example: ["64b7f1e6f9c9d4e5b8a9f7c3","64b7f1e6f9c9d4e5b8a9f7c4"]

failed

string[] · required

Failed device IDs

Example: []

total

number · required

Total devices attempted

Example: 2

action

string · enum · required

Action performed

Enum values:

OFF

INACTIVE

ERROR

ACTIVE

Example: ON

targetName

string · required

Target name

Example: Conference Room A

NfcAnalyticsQueryDto

startDate

string · date-time · required

Start date for analytics query

Example: 2026-02-01T00:00:00.000Z

endDate

string · date-time · required

End date for analytics query

Example: 2026-02-06T23:59:59.999Z

NfcTargetInfoDto

id

string · required

Target ID

Example: 64b7f1e6f9c9d4e5b8a9f7c3

name

string · required

Target name

Example: Conference Room A

type

string · enum · required

Type of NFC target (DEVICE, ROOM, USER)

Enum values:

ROOM

DEVICE

Example: ROOM

onStatus

string · enum

Device ON/OFF status (only for DEVICE targets)

Enum values:

OFF

INACTIVE

ERROR

ACTIVE

Example: ON

NfcControllableFeaturesDto

temperature

boolean · required

Whether temperature control is supported

Example: true

mode

boolean · required

Whether operating mode control is supported

Example: true

fan

boolean · required

Whether fan speed control is supported

Example: true

swing

boolean · required

Whether swing control is supported

Example: false

NfcGangSwitchStateDto

gangNumber

number · required

Gang number (1-4)

Example: 1

onStatus

string · enum · required

ON/OFF status of this gang

Enum values:

OFF

INACTIVE

ERROR

ACTIVE

Example: ON

label

string

Optional label for the gang

Example: Main Light

NfcDeviceInfoDto

id

string · required

Device ID

Example: 64b7f1e6f9c9d4e5b8a9f7c3

name

string · required

Device name

Example: Coffee Machine

deviceType

string · enum · required

Type of device (PLUG, MCB, etc.)

Enum values:

PLUG

MCB

ENV_SENSOR

SMART_SWITCH

AIRCON_CONTROL

WATER_METER

RIDGE

Example: PLUG

onStatus

string · enum · required

Device ON/OFF status

Enum values:

OFF

INACTIVE

ERROR

ACTIVE

Example: OFF

temperature

number

Temperature setting in Celsius (AIRCON_CONTROL only)

Example: 24

mode

string · enum

Aircon operating mode (AIRCON_CONTROL only)

Enum values:

COOL

HEAT

DRY

FAN

AUTO

Example: COOL

fan

string · enum

Fan speed setting (AIRCON_CONTROL only)

Enum values:

LOW

MEDIUM

HIGH

AUTO

Example: AUTO

swing

string · enum

Swing setting (AIRCON_CONTROL only)

Enum values:

OFF

AUTO

Example: OFF

brand

string · enum

Aircon brand (AIRCON_CONTROL only)

Enum values:

DAIKIN

MITSUBISHI

PANASONIC

SAMSUNG

FUJITSU

TOSHIBA

SHARP

Example: DAIKIN

object

Indicates which control features are physically supported by this aircon (AIRCON_CONTROL only)

numberOfGangs

number · min: 1 · max: 4

Number of gangs/buttons on the switch (SMART_SWITCH only)

Example: 2

NfcGangSwitchStateDto[]

Individual gang switch states (SMART_SWITCH only)

Example: [{"gangNumber":1,"onStatus":"ON","label":"Main Light"},{"gangNumber":2,"onStatus":"OFF","label":"Accent Light"}]

switchType

string · enum

Type of appliance the switch controls (SMART_SWITCH only)

Enum values:

UNREGISTERED

LIGHT

FAN

AIRCON

Example: LIGHT

totalEnergyUsage

number

Total energy usage in watt-hours (PLUG/MCB only)

Example: 125000

DateRangeDto

startDate

string · date-time · required

Start date of the queried range

Example: 2026-02-01T00:00:00.000Z

endDate

string · date-time · required

End date of the queried range

Example: 2026-02-06T23:59:59.999Z

NfcAnalyticsResponseDto

object · required

Target information

UsageHistoryDayWithCostBreakdownDto[] · required

Usage history data by day with cost breakdown

object · required

Date range queried

deviceType

string · enum

Device type (for device-level tokens only)

Enum values:

PLUG

MCB

ENV_SENSOR

SMART_SWITCH

AIRCON_CONTROL

WATER_METER

RIDGE

Example: AIRCON_CONTROL

object

Device details with current state (for device-level tokens)

object

Room details (for room-level tokens)

NfcDeviceInfoDto[]

Device list (only for ROOM tokens, includes all toggleable devices in the room)

NfcAirconControlDto

deviceId

string

Specific device ID to control (for room-level tokens)

Example: 507f1f77bcf86cd799439011

power

string · enum

Power ON/OFF control

Enum values:

OFF

INACTIVE

ERROR

ACTIVE

Example: ON

temperature

number · min: 16 · max: 30

Temperature setting in Celsius (16-30)

Example: 24

mode

string · enum

Aircon operating mode

Enum values:

COOL

HEAT

DRY

FAN

AUTO

Example: COOL

fan

string · enum

Fan speed setting

Enum values:

LOW

MEDIUM

HIGH

AUTO

Example: AUTO

swing

string · enum

Swing setting for aircon vents

Enum values:

OFF

AUTO

Example: ON

NfcControlResponseDto

success

boolean · required

Whether the control operation was successful

Example: true

message

string · required

Human-readable message describing the result

Example: Device controlled successfully

object · required

Updated device information after control operation

NfcSmartSwitchControlDto

deviceId

string

Specific device ID to control (for room-level tokens)

Example: 507f1f77bcf86cd799439011

power

string · enum

Power ON/OFF control

Enum values:

OFF

INACTIVE

ERROR

ACTIVE

Example: ON

gangNumber

number · min: 1 · max: 4

Gang number to control (1-4). Omit to control all gangs.

Example: 2

onStatus

string · enum

ON/OFF status for the targeted gang(s)

Enum values:

OFF

INACTIVE

ERROR

ACTIVE

Example: ON

NfcControlDto

deviceId

string

Specific device ID to control (for room-level tokens)

Example: 507f1f77bcf86cd799439011

power

string · enum

Power ON/OFF control

Enum values:

OFF

INACTIVE

ERROR

ACTIVE

Example: ON

WaterMeterSize

string · enum

Enum values:

DN15

DN20

DN25

DN32

DN40

DN50

Pipe diameter size (DN15, DN20, DN25, etc.)

WaterMeter

_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

meterSize

string · enum · required

Pipe diameter size (DN15, DN20, DN25, etc.)

Enum values:

DN15

DN20

DN25

DN32

DN40

DN50

realTimeFlowRate

number · required

Current flow rate in liters per minute

realTimePressure

number · required

Water pressure in bar

waterConsumption

number · required

Total water consumption in liters (incremented hourly)

Default: 0

isLeakDetected

boolean · required

Whether a leak is currently detected

leakThresholdFlowRate

number · required

Current leak detection threshold in liters per minute

Default: 5

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

meterModel

string

Meter model/manufacturer

realTimeTemperature

number

Water temperature in Celsius (optional)

flowRateMax

number

Max Threshold flow rate reading in L/min

Example: 10

flowRateMin

number

Min Threshold flow rate reading in L/min

Example: 10

pressureMax

number

Max Threshold pressure reading in bar

Example: 10

pressureMin

number

Min Threshold pressure reading in bar

Example: 10

temperatureMin

number

Min Threshold temperature reading in degrees Celsius

Example: 24

temperatureMax

number

Max Threshold temperature reading in degrees Celsius

Example: 24

lastLeakNotificationAt

string · date-time

Timestamp of last leak notification received

notificationThresholdHour

number

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

Example: 4

FilteredWaterMeterDto

_id

string · required

Unique database identifier of the device document in the system

Example: 64b7f1e6f9c9d4e5b8a9f7c3

macId

string · required

Unique identifier assigned to the device by the IoT hardware (MAC ID)

Example: 1092384701928347

deviceName

string · required

Friendly name for the device for easy identification

Example: Living Room AC

onStatus

string · enum · required

Current operational status of the device (ON, OFF, INACTIVE, or ERROR)

Enum values:

OFF

INACTIVE

ERROR

ACTIVE

Example: ON

totalEnergyUsage

number · required

Cumulative total energy consumption in kilowatt-hours (kWh) since device installation

Example: 500

tenantId

string · required

Unique identifier of the tenant organization that owns this device

Example: 64b7f1e6f9c9d4e5b8a9f7c4

tenantName

string · required

Name of the tenant organization that owns this device

Example: Faculty of Engineering

zoneId

string · required

Unique identifier of the zone that this device is assigned to

Example: 64b7f1e6f9c9d4e5b8a9f7c5

zoneName

string · required

Name of the zone that this device is assigned to

Example: Zone A

roomId

string · required

Unique identifier of the room where this device is physically located

Example: 64b7f1e6f9c9d4e5b8a9f7c6

roomName

string · required

Name of the room where this device is physically located

Example: Room 101

dbId

string · required

Unique identifier of the distribution box that this device is connected to (for MCBs)

Example: 64b7f1e6f9c9d4e5b8a9f7c7

dbName

string · required

Name of the distribution box that this device is connected to (for MCBs)

Example: Main Distribution Box

systemId

string · required

Unique identifier of the system that this device belongs to

Example: 64b7f1e6f9c9d4e5b8a9f7c3

systemName

string · required

Name of the system that this device belongs to

Example: NUS Engineering Building

realTimePower

number · required

Real-time power consumption in watts (W) measured by the device

Example: 115

realTimeCurrent

number · required

Real-time current draw in amperes (A) measured by the device

Example: 0.5

ssid

string · required

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

Example: XH001

meterSize

string · enum · required

Pipe diameter size (DN15, DN20, DN25, etc.)

Enum values:

DN15

DN20

DN25

DN32

DN40

DN50

realTimeFlowRate

number · required

Current flow rate in liters per minute

Example: 0

realTimePressure

number · required

Water pressure in bar

Example: 0

waterConsumption

number · required

Total water consumption in liters (incremented hourly)

Default: 0

isLeakDetected

boolean · required

Whether a leak is currently detected

Example: false

leakThresholdFlowRate

number · required

Current leak detection threshold in liters per minute

Default: 5

targetState

string · enum

Enum values:

OFF

INACTIVE

ERROR

ACTIVE

Example: ON

targetStateSetAt

string · date-time

Timestamp when the pending targetState was last written.

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

deviceNumber

number

Auto-incremented sequential number for tracking device registration order

Example: 3

batchNumber

number

Manufacturing batch number for tracking production groups and quality control

Example: 23

chipModel

string · enum

Hardware chip model identifier used in the device (e.g., ESP32C2, ESP8266)

Enum values:

ESP8266

ESP32C2

ESP32C5

ESP32

ESP32C3

versionNumber

string

Firmware version number currently running on the device

Example: 1.0.0

object

Weekly and one-time schedule configuration for automated device control

lastSeen

string · date-time

Timestamp when the device last communicated with the system

Example: 2024-10-15T12:30:00.000Z

isLocked

boolean

Lock status indicating if the device is locked

Example: false

inactivityNotificationEnabled

boolean

Whether inactivity notifications are enabled for this device

Example: false

meterModel

string

Meter model/manufacturer

realTimeTemperature

number

Water temperature in Celsius (optional)

lastLeakNotificationAt

string · date-time

Timestamp of last leak notification received

flowRateMax

number

Max Threshold flow rate reading in L/min

Example: 10

flowRateMin

number

Min Threshold flow rate reading in L/min

Example: 10

pressureMax

number

Max Threshold pressure reading in bar

Example: 10

pressureMin

number

Min Threshold pressure reading in bar

Example: 10

temperatureMin

number

Min Threshold temperature reading in degrees Celsius

Example: 24

temperatureMax

number

Max Threshold temperature reading in degrees Celsius

Example: 24

GetWaterMetersResponseDto

total

number · required

Total count of items matching filters

Example: 150

page

number · min: 1 · required

Current page number

Example: 1

size

number · min: 1 · required

Items per page

Example: 50

totalPages

number · min: 0 · required

Total number of pages

Example: 3

FilteredWaterMeterDto[] · required

List of water meters with organizational hierarchy details

UpdateWaterMeterDto

deviceName

string

Name of the device

Example: Living Room Light

location

string

Physical location of the device

Example: Block 123, Unit 01-23

remarks

string

Additional remarks or notes about the device

Example: Handle with care - critical equipment

tenantId

string

Tenant ID to associate the device with

Example: 64b7f1e6f9c9d4e5b8a9f7c3

zoneId

string

Zone ID to associate the device with

Example: 64b7f1e6f9c9d4e5b8a9f7c4

roomId

string

Room ID to associate the device with

Example: 64b7f1e6f9c9d4e5b8a9f7c5

isLocked

boolean

Whether the device is locked. When locked, the device cannot be toggled ON/OFF.

Example: false

isSpare

boolean

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

Example: false

meterSize

string · enum

Size/diameter of the water meter

Enum values:

DN15

DN20

DN25

DN32

DN40

DN50

meterModel

string

Model name/number of the water meter

Example: Sensus 620M

UpdateWaterMeterThresholdDto

flowRateMax

number

Max Threshold flow rate reading in L/min

Example: 10

flowRateMin

number

Min Threshold flow rate reading in L/min

Example: 0

pressureMax

number

Max Threshold pressure reading in bar

Example: 10

pressureMin

number

Min Threshold pressure reading in bar

Example: 0

temperatureMax

number

Max Threshold temperature reading in degrees Celsius

Example: 40

temperatureMin

number

Min Threshold temperature reading in degrees Celsius

Example: 0

notificationThresholdHour

number

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

Example: 4

SetLeakThresholdDto

thresholdFlowRate

number · min: 0 · required

Threshold flow rate in liters per minute

Example: 5

LeakHistoryResponseDto

total

number · required

Total count of items matching filters

Example: 150

page

number · min: 1 · required

Current page number

Example: 1

size

number · min: 1 · required

Items per page

Example: 50

totalPages

number · min: 0 · required

Total number of pages

Example: 3

Notification[] · required

Array of leak detection notifications

AlertThresholdHistory

waterMeter

string · required

Water meter ID

thresholdFlowRate

number · required

Threshold flow rate in liters per minute

Example: 5

createdAt

string · date-time · required

Timestamp when this record was created

updatedAt

string · date-time · required

Timestamp when this record was last updated

ThresholdHistoryResponseDto

total

number · required

Total count of items matching filters

Example: 150

page

number · min: 1 · required

Current page number

Example: 1

size

number · min: 1 · required

Items per page

Example: 50

totalPages

number · min: 0 · required

Total number of pages

Example: 3

AlertThresholdHistory[] · required

Array of threshold configuration history records

WaterMeterLatestReadingDto

realTimeFlowRate

number · required

Current flow rate in liters per minute

Example: 12.5

realTimePressure

number · required

Water pressure in bar

Example: 3.2

lastSeen

string · date-time · required

Last time the device sent data

Example: 2026-01-14T10:08:20.717Z

realTimeTemperature

number

Water temperature in Celsius (optional)

Example: 22

BulkSetLeakThresholdDto

waterMeterIds

string[] · required

Array of water meter IDs to update

Example: ["64b7f1e6f9c9d4e5b8a9f7c1","64b7f1e6f9c9d4e5b8a9f7c2"]

thresholdFlowRate

number · required

Leak detection threshold in liters per minute

Example: 5

FailedWaterMeterDto

waterMeterId

string · required

Water meter ID that failed

Example: 507f1f77bcf86cd799439011

error

string · required

Error message explaining why it failed

Example: Water meter not found

BulkWaterMeterResponseDto

WaterMeter[] · required

Array of successfully processed water meters

FailedWaterMeterDto[] · required

Array of failed water meters with error details

summary

string · required

Summary of the bulk operation

Example: Successfully processed 8 out of 10 water meters

BulkUpdateWaterMeterThresholdsDto

waterMeterIds

string[] · required

IDs of water meters to update

flowRateMax

number

Max Threshold flow rate in L/min

Example: 10

flowRateMin

number

Min Threshold flow rate in L/min

Example: 1

pressureMax

number

Max Threshold pressure in bar

Example: 10

pressureMin

number

Min Threshold pressure in bar

Example: 1

temperatureMax

number

Max Threshold temperature in °C

Example: 40

temperatureMin

number

Min Threshold temperature in °C

Example: 5

notificationThresholdHour

number

Hourly notification threshold — minimum hours between repeat notifications

Example: 4

DashboardLayoutItemDto

i

string · required

Panel ID reference

Example: 64b7f1e6f9c9d4e5b8a9f7c3

x

number · required

X position in grid

Example: 0

y

number · required

Y position in grid

Example: 0

w

number · required

Width in grid units

Example: 6

h

number · required

Height in grid units

Example: 4

minW

number

Minimum width

minH

number

Minimum height

maxW

number

Maximum width

maxH

number

Maximum height

static

boolean

Whether the item is static/immovable

CreateDashboardDto

name

string · required

Name of the dashboard

Example: Main Controller Dashboard

refreshInterval

number · min: 0

Auto-refresh interval in seconds. Set to 0 to disable auto-refresh.

Example: 5

Default: 5

DashboardLayoutItemDto[]

Layout configuration

panelIds

string[]

Panel IDs to include

globalTransformIds

string[]

Global Transform IDs

DashboardResponseDto

_id

string · required

Dashboard ID

system

string · required

System ID

name

string · required

Name of the dashboard

DashboardLayoutItemDto[] · required

Layout configuration

panels

string[] · required

Panel IDs or populated panels

createdAt

string · date-time · required

updatedAt

string · date-time · required

refreshInterval

number

Auto-refresh interval in seconds. 0 means disabled.

Example: 5

globalTransforms

string[]

Global transform IDs or populated transforms

UpdateDashboardDto

name

string

Name of the dashboard

Example: Main Controller Dashboard

refreshInterval

number · min: 0

Auto-refresh interval in seconds. Set to 0 to disable auto-refresh.

Example: 5

Default: 5

DashboardLayoutItemDto[]

Layout configuration

panelIds

string[]

Panel IDs to include

globalTransformIds

string[]

Global Transform IDs

DataSourceType

string · enum

Enum values:

REST_API

Type of data source

AuthType

string · enum

Enum values:

BEARER

API_KEY_HEADER

NONE

How the API key is sent. BEARER = Authorization: Bearer , API_KEY_HEADER = custom header (default x-api-key), NONE = no auth

CreateDataSourceDto

name

string · required

Name of the data source

Example: Main InfluxDB

type

string · enum · required

Type of data source

Enum values:

REST_API

url

string · required

Base URL

Example: https://influxdb.example.com

authType

string · enum

How the API key is sent. BEARER = Authorization: Bearer , API_KEY_HEADER = custom header (default x-api-key), NONE = no auth

Enum values:

BEARER

API_KEY_HEADER

NONE

Default: BEARER

apiKeyHeaderName

string

Custom header name when authType is API_KEY_HEADER (defaults to x-api-key)

Example: x-api-key

apiKey

string

API Key (will be encrypted before storage)

DataSourceResponseDto

_id

string · required

Data source ID

system

string · required

System ID

name

string · required

Name of the data source

type

string · enum · required

Type of data source

Enum values:

REST_API

url

string · required

Base URL

createdAt

string · date-time · required

updatedAt

string · date-time · required

authType

string · enum

How the API key is sent

Enum values:

BEARER

API_KEY_HEADER

NONE

apiKeyHeaderName

string

Custom header name when authType is API_KEY_HEADER

connectionParams

object

Connection parameters

UpdateDataSourceDto

name

string

Name of the data source

Example: Main InfluxDB

type

string · enum

Type of data source

Enum values:

REST_API

url

string

Base URL

Example: https://influxdb.example.com

authType

string · enum

How the API key is sent. BEARER = Authorization: Bearer , API_KEY_HEADER = custom header (default x-api-key), NONE = no auth

Enum values:

BEARER

API_KEY_HEADER

NONE

Default: BEARER

apiKeyHeaderName

string

Custom header name when authType is API_KEY_HEADER (defaults to x-api-key)

Example: x-api-key

apiKey

string

API Key (will be encrypted before storage)

ChartType

string · enum

Enum values:

LINE

BAR

PIE

AREA

JSON

TABLE

BUTTON

HttpMethod

string · enum

Enum values:

GET

POST

PUT

PATCH

DELETE

DebugSnapshotDto

transformType

string · required

Transform type applied at this step

order

number · required

Execution order of this step

data

object · required

Data state after this transform step

ProxyDebugResponseDto

data

object · required

The final transformed data

DebugSnapshotDto[]

Debug snapshots from the compute service for each transform step (only present when debug=true)

TransformType

string · enum

Enum values:

EXTRACT

SELECT

RENAME

FIELDS

FILTER

SORT

LIMIT

REDUCE

Type of transformation. Raw JSON types: EXTRACT, SELECT, RENAME, FIELDS, FILTER, SORT, LIMIT, REDUCE. DataFrame types: DF_RENAME_FIELDS, DF_ORGANIZE_FIELDS, DF_SELECT_FIELDS, DF_FILTER_FIELDS_BY_NAME, DF_FILTER_BY_VALUE, DF_FILTER_BY_QUERY, DF_CALCULATE, DF_CUMULATIVE, DF_REDUCE, DF_GROUP_BY, DF_JOIN, DF_MERGE, DF_CONCATENATE, DF_TIME_SERIES_LONG_TO_WIDE, DF_TIME_SERIES_WIDE_TO_LONG, DF_TIME_SERIES_TO_ROWS, DF_TIME_SERIES_TO_TABLE, DF_PIVOT, DF_ROWS_TO_FIELDS, DF_LABELS_TO_FIELDS, DF_LOOKUP, DF_CONFIG_FROM_QUERY, DF_REGRESSION, DF_EXTRACT_LABELS.

TransformerResponseDto

_id

string · required

Unique transformer identifier

Example: 64b8c3d2e1f4a2b3c4d5e6f7

panel

string · required

Panel ID this transformer belongs to

Example: 64b8c3d2e1f4a2b3c4d5e6f8

name

string · required

Human-readable name of the transformer

Example: Calculate Profit Margin

type

string · enum · required

Enum values:

EXTRACT

SELECT

RENAME

FIELDS

FILTER

SORT

LIMIT

REDUCE

enabled

boolean · required

Whether this transformer is enabled in the pipeline. Disabled transformers are skipped.

Example: true

order

number · required

Execution order within the pipeline. Lower numbers execute first.

Example: 0

createdAt

string · date-time · required

Timestamp when the transformer was created

Example: 2026-03-14T10:30:00.000Z

updatedAt

string · date-time · required

Timestamp when the transformer was last updated

Example: 2026-03-14T10:30:00.000Z

config

object

Configuration object whose shape depends on the transform type. See CreateTransformerDto config documentation for schemas per type.

Example: {"outputField":"profit","operation":"subtract","fieldA":"revenue","fieldB":"cost"}

ProxyCallUsageResponseDto

_id

string · required

Usage document ID

system

string · required

System ID

method

string · enum · required

HTTP method used

Enum values:

GET

POST

PUT

PATCH

DELETE

url

string · required

Final URL used for the proxy call

statusCode

number · required

HTTP status code from external source

Example: 200

authorization

boolean · required

Whether Authorization header was present

createdAt

string · date-time · required

updatedAt

string · date-time · required

responseTimeMs

number

Response time in milliseconds

Example: 150

dataSource

string

Related DataSource ID

dashboard

string

Related Dashboard ID

panel

string

Related Panel ID

body

object

Custom body for the proxy request (for POST/PUT)

PanelResponseDto

_id

string · required

Panel ID

system

string · required

System ID

title

string · required

Title of the panel

chartType

string · enum · required

Type of chart

Enum values:

LINE

BAR

PIE

AREA

JSON

TABLE

BUTTON

dataSource

string · required

Data source ID or populated object

createdAt

string · date-time · required

updatedAt

string · date-time · required

description

string

Description of the panel

colorPalette

string[]

Color palette for chart series

endpoint

string

API endpoint path

httpMethod

string · enum

HTTP method for the proxy request

Enum values:

GET

POST

PUT

PATCH

DELETE

headers

object

Custom headers for the proxy request

xAxisField

string

X-Axis field

yAxisField

string

Y-Axis field

TransformerResponseDto[]

Populated transformers linked to this panel

options

object

Visualization options

ProxyCallUsageResponseDto[]

Recent proxy call usages for this panel

body

object

Custom body for the panel request (for POST/PUT)

PanelThresholdDto

value

number

Threshold value

Example: 100

color

string

Threshold color

Example: #ff0000

label

string

Threshold label

Example: High

PanelVisualizationOptionsDto

colors

object

Color mappings

Example: {"voltage":"#00ff00"}

yMin

number

Y-axis minimum value

yMax

number

Y-axis maximum value

showLegend

boolean

Whether to show legend

showGrid

boolean

Whether to show grid lines

PanelThresholdDto[]

Thresholds for gauge/alert visualizations

unit

string

Unit label

Example: kWh

decimals

number

Number of decimal places

CreatePanelDto

title

string · required

Title of the panel

Example: System Voltage History

chartType

string · enum · required

Type of chart

Enum values:

LINE

BAR

PIE

AREA

JSON

TABLE

BUTTON

dataSource

string · required

ID of the Data Source

description

string

Description of the panel

Example: Displays voltage trends over the last 24 hours

Default:

colorPalette

string[]

Color palette for chart series. The frontend cycles through these colors.

Example: ["#FF6384","#36A2EB","#FFCE56","#4BC0C0"]

Default: []

endpoint

string

API endpoint path appended to the data source base URL

Example: /api/v1/energy?range=1h

httpMethod

string · enum

HTTP method for the proxy request

Enum values:

GET

POST

PUT

PATCH

DELETE

Default: GET

headers

object

Custom headers to include in the proxy request

Example: {"X-Custom-Header":"value"}

xAxisField

string

X-Axis field name

Example: time

yAxisField

string

Y-Axis field name

Example: value

object

Visualization options

body

object

Custom body for the panel request (for POST/PUT)

UpdatePanelDto

title

string

Title of the panel

Example: System Voltage History

description

string

Description of the panel

Example: Displays voltage trends over the last 24 hours

Default:

colorPalette

string[]

Color palette for chart series. The frontend cycles through these colors.

Example: ["#FF6384","#36A2EB","#FFCE56","#4BC0C0"]

Default: []

chartType

string · enum

Type of chart

Enum values:

LINE

BAR

PIE

AREA

JSON

TABLE

BUTTON

dataSource

string

ID of the Data Source

endpoint

string

API endpoint path appended to the data source base URL

Example: /api/v1/energy?range=1h

httpMethod

string · enum

HTTP method for the proxy request

Enum values:

GET

POST

PUT

PATCH

DELETE

Default: GET

headers

object

Custom headers to include in the proxy request

Example: {"X-Custom-Header":"value"}

xAxisField

string

X-Axis field name

Example: time

yAxisField

string

Y-Axis field name

Example: value

object

Visualization options

body

object

Custom body for the panel request (for POST/PUT)

CreateTransformerDto

name

string · required

Name of the transformer

Example: Extract Temperature

type

string · enum · required

Type of transformation to apply. Raw JSON types: EXTRACT, SELECT, RENAME, FIELDS, FILTER, SORT, LIMIT, REDUCE. DataFrame types (DF_ prefix): DF_RENAME_FIELDS, DF_ORGANIZE_FIELDS, DF_SELECT_FIELDS, DF_FILTER_FIELDS_BY_NAME, DF_FILTER_BY_VALUE, DF_FILTER_BY_QUERY, DF_CALCULATE, DF_CUMULATIVE, DF_REDUCE, DF_GROUP_BY, DF_JOIN, DF_MERGE, DF_CONCATENATE, DF_TIME_SERIES_LONG_TO_WIDE, DF_TIME_SERIES_WIDE_TO_LONG, DF_TIME_SERIES_TO_ROWS, DF_TIME_SERIES_TO_TABLE, DF_PIVOT, DF_ROWS_TO_FIELDS, DF_LABELS_TO_FIELDS, DF_LOOKUP, DF_CONFIG_FROM_QUERY, DF_REGRESSION, DF_EXTRACT_LABELS.

Enum values:

EXTRACT

SELECT

RENAME

FIELDS

FILTER

SORT

LIMIT

REDUCE

config

object

Configuration object for the transform. Shape depends on the transform type. See TRANSFORMATIONS.md for the full config reference per type.

Example: {}

Default: {}

enabled

boolean

Whether this transformer is enabled in the pipeline. Disabled transformers are skipped during execution.

Example: true

Default: true

order

number · min: 0

Execution order within the pipeline. Lower numbers execute first.

Example: 0

Default: 0

UpdateTransformerDto

name

string

Name of the transformer

Example: Extract Temperature

type

string · enum

Type of transformation to apply.

Enum values:

EXTRACT

SELECT

RENAME

FIELDS

FILTER

SORT

LIMIT

REDUCE

config

object

Configuration object for the transform. Shape depends on the transform type. See TRANSFORMATIONS.md for the full config reference per type.

Example: {}

enabled

boolean

Whether this transformer is enabled in the pipeline. Disabled transformers are skipped during execution.

Example: true

Default: true

order

number · min: 0

Execution order within the pipeline. Lower numbers execute first.

Example: 0

Default: 0

HealthStatus

string · enum

Enum values:

HEALTHY

WARNING

CRITICAL

OFFLINE

DeviceHealthItemDto

deviceId

string · required

Device ID

deviceName

string · required

Device name or macId

healthScore

number · required

Health score 0-100

Example: 85

healthStatus

string · enum · required

Health status

Enum values:

HEALTHY

WARNING

CRITICAL

OFFLINE

openAnomalyCount

number · required

Number of open anomalies

Example: 1

monitoringEnabled

boolean · required

Whether predictive maintenance monitoring is active for this device

Example: true

Default: true

mlRiskScore

number

ML model anomaly risk score 0.0–1.0

mlIsAnomaly

boolean

Whether ML model flagged this device as anomalous

DeviceHealthSummaryDto

DeviceHealthItemDto[] · required

total

number · required

Total device count (after filtering)

Example: 25

page

number · required

Current page number

Example: 1

size

number · required

Items per page

Example: 50

AnomalyType

string · enum

Enum values:

SPIKE

DEGRADATION

DEAD_DEVICE

AnomalySeverity

string · enum

Enum values:

LOW

MEDIUM

HIGH

CRITICAL

AnomalyStatus

string · enum

Enum values:

OPEN

ACKNOWLEDGED

RESOLVED

FALSE_POSITIVE

DeviceAnomalyResponseDto

_id

string · required

Anomaly ID

device

string · required

Device ID

system

string · required

System ID

anomalyType

string · enum · required

Enum values:

SPIKE

DEGRADATION

DEAD_DEVICE

severity

string · enum · required

Enum values:

LOW

MEDIUM

HIGH

CRITICAL

detectedAt

string · date-time · required

baselineValue

number · required

actualValue

number · required

deviationPercentage

number · required

explanation

string · required

status

string · enum · required

Enum values:

OPEN

ACKNOWLEDGED

RESOLVED

FALSE_POSITIVE

deviceName

string

Device name (populated for convenience)

notes

string

Staff notes about this anomaly

PaginatedAnomaliesDto

DeviceAnomalyResponseDto[] · required

total

number · required

page

number · required

size

number · required

DayType

string · enum

Enum values:

weekday

weekend

DeviceBaselineDataDto

dayType

string · enum · required

Enum values:

weekday

weekend

Example: weekday

calculatedAt

string · date-time · required

When baseline was last calculated

windowDays

number · required

Rolling window in days

Example: 28

healthScore

number · required

Health score 0-100

Example: 85

hourlyAvgUsage

number · required

Average hourly energy usage (kWh) while ON

Example: 1.5

hourlyStdDev

number · required

Std dev of hourly usage

Example: 0.3

dailyAvgUsage

number · required

Average daily energy usage (kWh)

Example: 12

dailyStdDev

number · required

Std dev of daily usage

Example: 1.2

peakHourAvg

number · required

Peak hour average usage (kWh)

Example: 2.1

offPeakHourAvg

number · required

Off-peak hour average usage (kWh)

Example: 0.8

avgPowerFactor

number · required

Average power factor

Example: 0.95

avgCurrent

number · required

Average current (A)

Example: 2.1

avgVoltage

number · required

Average voltage (V)

Example: 230

avgPower

number · required

Average power (W)

Example: 480

avgCyclesPerDay

number · required

Average on/off cycles per day

Example: 4

avgActiveHoursPerDay

number · required

Average active hours per day

Example: 8

monitoringEnabled

boolean · required

Whether monitoring is enabled

Example: true

baselineResetAt

string | null · date-time

When baseline was last reset

mlRiskScore

number

ML anomaly risk score 0.0–1.0

mlIsAnomaly

boolean

Whether ML flagged as anomalous

mlScoredAt

string · date-time

When ML score was last updated

DeviceDetailResponseDto

deviceId

string · required

Device ID

DeviceAnomalyResponseDto[] · required

All anomalies for this device

object

Weekday baseline

object

Weekend baseline

UpdateAnomalyStatusDto

status

string · enum · required

New status for the anomaly

Enum values:

OPEN

ACKNOWLEDGED

RESOLVED

FALSE_POSITIVE

notes

string · maxLength: 1000

Notes about what happened or actions taken

Example: Checked on-site — compressor wear confirmed. Scheduled for replacement next week.

BulkMonitoringRequestDto

deviceIds

string[] · required

Device IDs to enable or disable monitoring for

Example: ["507f1f77bcf86cd799439011","507f1f77bcf86cd799439012"]

BulkResetBaselineResponseDto

affected

number · required

Number of devices reset

Example: 3

deviceIds

string[] · required

Device IDs that were successfully reset

baselineResetAt

string · date-time · required

Timestamp the reset was triggered

weekdayRecalibratingUntil

string · date-time · required

Weekday anomaly detection resumes after this date (28 days from reset)

weekendRecalibratingUntil

string · date-time · required

Weekend anomaly detection resumes after this date (70 days from reset)

message

string · required

Human-readable confirmation message

BulkMonitoringResponseDto

affected

number · required

Number of devices affected

Example: 3

deviceIds

string[] · required

Device IDs that were successfully updated

message

string · required

Human-readable confirmation message

Example: Monitoring enabled for 3 device(s).

MlTrainingResponseDto

samplesUsed

number · required

Number of baseline samples used to train the model

ConsumerOrderLocation

string · enum

Enum values:

Central

North

Northeast

East

West

Location of the customer

ConsumerOrderHousingType

string · enum

Enum values:

HDB

Condominium

Landed

Commercial

Other

Type of housing

ConsumerOrderDevice

string · enum

Enum values:

smart-tv

water-cooler

air-purifier

printer

aircon

washing-machine

home-coffee-machine

Device type identifier

ConsumerSelectedDeviceDto

deviceType

string · enum · required

Device type identifier

Enum values:

smart-tv

water-cooler

air-purifier

printer

aircon

washing-machine

home-coffee-machine

Example: aircon

qty

number · min: 1 · required

Number of units of this device

Example: 2

CreateConsumerOrderDto

firstName

string · required

First name of the customer

Example: Jane

lastName

string · required

Last name of the customer

Example: Doe

mobile

string · required

Mobile number of the customer

Example: +6591234567

email

string · required

Email address of the customer

Example: jane.doe@example.com

location

string · enum · required

Location of the customer

Enum values:

Central

North

Northeast

East

West

Example: Central

housingType

string · enum · required

Type of housing

Enum values:

HDB

Condominium

Landed

Commercial

Other

Example: HDB

ConsumerSelectedDeviceDto[] · required

High-energy appliances the customer wants to monitor, with quantities

CreateConsumerOrderResponseDto

message

string · required

Confirmation message

Example: Order submitted successfully.

SceneStateResponseDto

sceneId

string · required

label

string · required

clipUrl

string · required

Absolute URL of the backdrop video to loop for this scene.

Example: https://exhibit-public-bucket.s3.ap-southeast-1.amazonaws.com/day_scene.mp4

updatedAt

string · required

ISO timestamp of when this scene became active.

Example: 2026-06-10T09:30:00.000Z

SetSceneDto

sceneId

string · required

Stable id of the scene to activate (see GET /exhibit/scenes).

Example: day

setBy

string

Optional label for who triggered the change (audit only).

Example: ipad-control