Energomonitor API is a standard RESTful API. This section discusses its technical aspects.
The current version of the API can be accessed via HTTPS using the following URL:
All resource URLs in the documentation are relative to this URL. Plain HTTP access is not supported.
All requests to the API must be authenticated with an access token, specified
Authorization HTTP header:
Authorization: Bearer mKKVFYdCjTgs74abyyTH4Mtt7Az4yJ
You can generate the token in the Energomonitor application or using the
/authorizations API endpoint (which doesn’t require token authentication
The token always authorizes access to a specific list of user’s resources (e.g. feeds). When the list of resources gets extended (e.g. the user installs new Homebase and a new feed is created), you’ll need to generate a new token.
The token has a fixed expiration time for security reasons. You’ll probably want to save the expiration time when a token is generated and generate a new token when the current one gets expired.
All client errors (such as malformed requests or validation errors) are
4xx HTTP status codes. The error response contains an
object with a
message property which describes the error.
The API uses the following error status codes:
||Invalid request (e.g. missing property or invalid property value).|
||Missing or invalid credentials, missing or invalid token, expired token, unauthorized access to a resource.|
||Attempt to create an authorization to a resource the user is not authorized to access.|
||Resource not found (e.g. wrong feed ID).|
||Attempt to go over the rate limit.|
There is currently a limit of 10 requests/s per IP address. When you go over
the limit, the responses get delayed. If you press further, the API will
start to return responses with
429 HTTP status code.
The API is versioned. The current version is 1, which is expressed as
/v1 in the API URL. In the future, we may release new versions of the API
which may not be backward-compatible. Within each API version, we will
perform only backward-compatible changes.
In general, changes that add functionality (e.g. adding a new resource, request parameter, or object property) are considered compatible. Changes that change, rename, or delete existing functionality are considered incompatible.