API docs by Redocly

EMS Webapi (1.0.0)

Download OpenAPI specification:

REST API for the EMS smart-meter platform: read system data, browse the configuration (Devices → Loads → Signals) and get realtime / historical measurements.

Domain model

  • Device: a physical or logical meter known to the gateway (e.g. the built-in main meter or a Modbus-connected EM24).
  • Load: a measurement context that groups the signals produced by a single physical channel and carries protocol-specific configuration (meterBus, tcp, rtu, virtual, P1).
  • Signal: a single quantity exposed by a Load (voltage, current, energy counter, …) identified by a stable signal-identifier code.
  • Realtime: the latest sampled value of a Signal.
  • History: the historical sampled value of a Signal.

Authentication

Every endpoint except GET /ver and POST /v1/auth/login requires a Bearer JWT obtained from the login endpoint. Tokens expire 30 minutes after issue.

Pass the token in the Authorization header:

Authorization: Bearer <token>

Login

Create a POST request with JSON body with username and password of a API role account. The returned token expires 30 minutes after issue and must be sent as Authorization: Bearer <token> on every protected endpoint.

Request Body schema: application/json
required
username
required
string
password
required
string <password>

Responses

Request samples

Content type
application/json
{
  • "username": "admin",
  • "password": "s3cret!"
}

Response samples

Content type
application/json
{
  • "token": "eyJhbGciOi…<jwt>…"
}

Get API version

Returns the version of this API. Public — no token required.

Responses

Response samples

Content type
application/json
{
  • "api_ver": 1
}

Get EMS serial number

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "sn": "BX10000000"
}

Get the EMS MAC address

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "mac": "00:1A:2B:3C:4D:5E"
}

Get EMS Firmware version

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "fw": "EMS_1.0.0.0.250101.000000"
}

Get EMS Part number

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "pn": "EMS10AV5S1X"
}

Get current local date and timezone

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "date": "2025-01-01 00:00:00",
  • "tz": "+00:00 UTC"
}

List devices

Authorizations:
bearerAuth
query Parameters
uids
string
Example: uids=1,2,59

Comma-separated list of UIDs to filter by.

protocol
string
Enum: "rtu" "tcp" "meterBus" "virtual" "P1"

Filter by protocol. Accepted values: rtu, tcp, meterBus, virtual, P1.

Responses

Response samples

Content type
application/json
{
  • "devices": {
    }
}

Get a device by UID

Authorizations:
bearerAuth
path Parameters
uid
required
integer
Example: 1

Resource UID

Responses

Response samples

Content type
application/json
{
  • "uid": 1,
  • "label": "Main meter",
  • "partNumber": "EMS10AV5S1X",
  • "system": "1P"
}

List loads

Authorizations:
bearerAuth
query Parameters
uids
string
Example: uids=1,2,59

Comma-separated list of UIDs to filter by.

protocol
string
Enum: "rtu" "tcp" "meterBus" "virtual" "P1"

Filter by protocol. Accepted values: rtu, tcp, meterBus, virtual, P1.

Responses

Response samples

Content type
application/json
Example
{
  • "loads": {
    }
}

Get a load by UID

Authorizations:
bearerAuth
path Parameters
uid
required
integer
Example: 1

Resource UID

Responses

Response samples

Content type
application/json
{
  • "uid": 2,
  • "label": "Main",
  • "enable": true,
  • "index": 1,
  • "type": 0,
  • "did": 1,
  • "meterBus": { },
  • "tcp": { },
  • "rtu": { },
  • "virtual": { },
  • "P1": { }
}

List loads belonging to a device

Authorizations:
bearerAuth
path Parameters
uid
required
integer
Example: 1

Resource UID

Responses

Response samples

Content type
application/json
{
  • "loads": {
    }
}

List signals

Authorizations:
bearerAuth
query Parameters
uids
string
Example: uids=1,2,59

Comma-separated list of UIDs to filter by.

limit
integer
Default: 1000
Example: limit=100

Maximum number of records to return. Default 1000.

page
integer
Default: 1
Example: page=1

1-based page number. Default 1.

Responses

Response samples

Content type
application/json
{
  • "signals": {
    }
}

Get a signal by UID

Authorizations:
bearerAuth
path Parameters
uid
required
integer
Example: 1

Resource UID

Responses

Response samples

Content type
application/json
{
  • "uid": 100,
  • "si": 29,
  • "sir": 29,
  • "enable": true,
  • "lid": 83,
  • "did": 82
}

List signals belonging to a device

Authorizations:
bearerAuth
path Parameters
uid
required
integer
Example: 1

Resource UID

Responses

Response samples

Content type
application/json
{
  • "signals": {
    }
}

List signals belonging to a load

Authorizations:
bearerAuth
path Parameters
uid
required
integer
Example: 1

Resource UID

Responses

Response samples

Content type
application/json
{
  • "signals": {
    }
}

Latest realtime values for many signals

Authorizations:
bearerAuth
query Parameters
uids
string
Example: uids=1,2,59

Comma-separated list of UIDs to filter by.

limit
integer
Default: 1000
Example: limit=100

Maximum number of records to return. Default 1000.

page
integer
Default: 1
Example: page=1

1-based page number. Default 1.

Responses

Response samples

Content type
application/json
{
  • "realtime": {
    }
}

Latest realtime value for a single signal

Authorizations:
bearerAuth
path Parameters
uid
required
integer
Example: 1

Resource UID

Responses

Response samples

Content type
application/json
{
  • "uid": 100,
  • "si": 29,
  • "v": 230.4,
  • "t": 1752493029975,
  • "s": 1,
  • "r": 0
}

Latest realtime values for all signals of a device

Authorizations:
bearerAuth
path Parameters
uid
required
integer
Example: 1

Resource UID

Responses

Response samples

Content type
application/json
{
  • "realtime": {
    }
}

Latest realtime values for all signals of a load

Authorizations:
bearerAuth
path Parameters
uid
required
integer
Example: 1

Resource UID

Responses

Response samples

Content type
application/json
{
  • "realtime": {
    }
}

Historical sample for many signals

Authorizations:
bearerAuth
query Parameters
uids
string
Example: uids=1,2,59

Comma-separated list of UIDs to filter by.

start
string
Example: start=1735689600000

Start of the time range — Unix timestamp in milliseconds.

end
string
Example: end=1735776000000

End of the time range — Unix timestamp in milliseconds.

limit
integer
Default: 1000
Example: limit=100

Maximum number of records to return. Default 1000.

page
integer
Default: 1
Example: page=1

1-based page number. Default 1.

Responses

Response samples

Content type
application/json
{
  • "history": {
    }
}

Historical sample for a single signal

Authorizations:
bearerAuth
path Parameters
uid
required
integer
Example: 1

Resource UID

query Parameters
start
string
Example: start=1735689600000

Start of the time range — Unix timestamp in milliseconds.

end
string
Example: end=1735776000000

End of the time range — Unix timestamp in milliseconds.

limit
integer
Default: 1000
Example: limit=100

Maximum number of records to return. Default 1000.

page
integer
Default: 1
Example: page=1

1-based page number. Default 1.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Last historical sample for many signals

Authorizations:
bearerAuth
query Parameters
uids
string
Example: uids=1,2,59

Comma-separated list of UIDs to filter by.

limit
integer
Default: 1000
Example: limit=100

Maximum number of records to return. Default 1000.

page
integer
Default: 1
Example: page=1

1-based page number. Default 1.

Responses

Response samples

Content type
application/json
{
  • "history": {
    }
}

Last historical sample for a single signal

Authorizations:
bearerAuth
path Parameters
uid
required
integer
Example: 1

Resource UID

Responses

Response samples

Content type
application/json
{
  • "uid": 3,
  • "t": 1735689659,
  • "p": 1735689660,
  • "v": 10.5,
  • "d": 0,
  • "max": 100,
  • "min": 0
}

Historical sample for all signals of a device

Authorizations:
bearerAuth
path Parameters
uid
required
integer
Example: 1

Resource UID

query Parameters
start
string
Example: start=1735689600000

Start of the time range — Unix timestamp in milliseconds.

end
string
Example: end=1735776000000

End of the time range — Unix timestamp in milliseconds.

limit
integer
Default: 1000
Example: limit=100

Maximum number of records to return. Default 1000.

page
integer
Default: 1
Example: page=1

1-based page number. Default 1.

Responses

Response samples

Content type
application/json
{
  • "history": {
    }
}

Last historical sample for each signal of a device

Authorizations:
bearerAuth
path Parameters
uid
required
integer
Example: 1

Resource UID

Responses

Response samples

Content type
application/json
{
  • "history": {
    }
}

Historical sample for all signals of a load

Authorizations:
bearerAuth
path Parameters
uid
required
integer
Example: 1

Resource UID

query Parameters
start
string
Example: start=1735689600000

Start of the time range — Unix timestamp in milliseconds.

end
string
Example: end=1735776000000

End of the time range — Unix timestamp in milliseconds.

limit
integer
Default: 1000
Example: limit=100

Maximum number of records to return. Default 1000.

page
integer
Default: 1
Example: page=1

1-based page number. Default 1.

Responses

Response samples

Content type
application/json
{
  • "history": {
    }
}

Last historical sample for each signal of a load

Authorizations:
bearerAuth
path Parameters
uid
required
integer
Example: 1

Resource UID

Responses

Response samples

Content type
application/json
{
  • "history": {
    }
}