eGauge Meter API
License Common Documentation License 1.0
eGauge Meter API
The eGauge WebAPI is a JSON-based API that provides access to eGauge meters. It offers secure means to read device data, configure the device, and perform various control operations.
The WebAPI is intended to eventually replace the eGauge XML API. For new applications, developers are encouraged to use WebAPI rather than the legacy XML API.
The authentication service. Clients can use this to obtain and manage tokens that grant access to the other resources in this API.
The meter uses JSON Web Tokens (JWT or simply token) to restrict access to protected resources. Clients must include such tokens in requests via the HTTP Authorization header. This header must have the form:
Authorization: Bearer JWT
where JWT is a valid token.
Tokens are valid for a limited time; typically for about 10 minutes. However, a meter may revoke a token earlier, e.g., due to a reboot.
The service provides the ability to execute various operations for their side effects, such as rebooting the meter. Unless stated otherwise, the resources in this service are available only to users with the save right (see /auth/rights).
Activate a service with an external provider (web server).
This request returns a token which can then be used to monitor the status of the operation. See /sys/status/token/result for details.
The type of service to activate. This can be alert for the alert reporting service or push for the data-sharing service.
curl -i -X POST \ https://webapi.egauge.net/_mock/webapi/4.6/openapi/cmd/activate \ -H 'Authorization: Bearer <YOUR_JWT_HERE>' \ -H 'Content-Type: application/json' \ -d '{ "service": "alert", "provider": "Cloudly'\''s Alert Service" }'
Activation response.
A status token. This token is a hexadecimal string (typically 32 characters long) which can be used to check on the current status of a potentially long-running operation. The current status can be retrieved from URL /sys/status/token.
{ "token": "473c31462e62848b5352314dfc608669", "error": "Error message (present if an error occurred)." }
curl -i -X POST \ https://webapi.egauge.net/_mock/webapi/4.6/openapi/cmd/cancel \ -H 'Authorization: Bearer <YOUR_JWT_HERE>' \ -H 'Content-Type: application/json' \ -d '{ "token": "473c31462e62848b5352314dfc608669" }'
{ "status": "OK", "error": "Error message (present if an error occurred)." }
Clear data. The string in the request body identifies what data to clear:
excess: For register values that are read from a remote device, it is possible that the meter may not be able to reach the remote device at times (e.g., due to a networking problem). If the remote device provides cumulative values, this means that when the remote device becomes accessible again, the cumulative value may have increased significantly, which could then cause a spike in the graphed values for that register. To prevent such spikes, the meter will instead record the jump as an excess and then replay that excess gradually over time so that the meter can catch up to the true value without causing a spike. Executing this command clears to zero the excess of all registers. This will typically cause a spike in the graphed values for any remote registers which had a non-zero excess but, on the positive side, will then ensure that the cumulative values afterwards match those of the remote device(s).
Note If excess keeps accumulating, it may be better to use the spiky option for remote registers.
web_cache: Clears the web server cache of compressed files. Under normal circumstances, it is not necessary to clear this cache explicitly. However, this command can be used in case the cache gets corrupted, e.g., due to a power cycle while the meter is in the middle of writing a cache file.
curl -i -X POST \ https://webapi.egauge.net/_mock/webapi/4.6/openapi/cmd/clear \ -H 'Authorization: Bearer <YOUR_JWT_HERE>' \ -H 'Content-Type: application/json'
{ "status": "OK", "error": "Error message (present if an error occurred)." }
The action to perform. The possible values are:
restore: Restores data from a backup file to the device database.zero: Zeroes out one or more registers in the device database.split: Split the positive changes of a net register into a separate positive-only register.If specified, this limits the operation to data that is not older than the timestamp specified here.
If specified, this limits the operation to data that is not younger than the timestamp specified here.
If specified, the operation is limited to the registers whose database ids appear in this list.
This member is required for action restore. It contains the binary backup data to be restored, encoded in base64. A device may reject a restore request if this member is larger than 2 MiB. It may therefore be necessary to split up a large backup file into multiple smaller chunks that are then restored one after the other.
This is used only for restore operations. It indicates whether a the backup data has been split up into multiple chunks and the current chunk is to be follow by the next older, adjacent chunk. Setting this flag is not required, but doing so can greatly speed up a restore operation. On the other hand, setting this flag to true without following it up with the next older adjacent chunk can leave the database in a corrupted state, with large spikes at the beginning of the current chunk.
curl -i -X POST \ https://webapi.egauge.net/_mock/webapi/4.6/openapi/cmd/db \ -H 'Authorization: Bearer <YOUR_JWT_HERE>' \ -H 'Content-Type: application/json' \ -d '{ "action": "restore", "from": "1677523091.000900435", "to": "1677523091.000900435", "regs": [ 0 ], "data": "string", "more_chunks": true }'