VRM API v2 Documentation

This document provides an brief overview of available endpoints and their parameters. The API is a basic REST API. The API accepts JSON as request body (not form data, just plain JSON). Use something like Postman to fiddle around with it.


Table of contents


Introduction

To be able to authenticate to the Victron VRM API it is required you have an active account (the same account can be used as you would normally use for the VRM-dashboard). To login you need a valid email address and password. When the credentials are valid, a web-token will be generated which will then be required for subsequent calls to the api. If the token expires, an error message will be returned, which therefore means you have to request a new token with the original login-credentials.


Base URL

The base URL of the API is:

https://vrmapi.victronenergy.com


Design considerations

There are two use cases that you could have in mind when implementing a system that calls this API: 1) To build your own front-end; that uses our database & API as a backend. 2) To replicate the data into your own backend.

The API is not suitable for that last use case; and there is no support offered for such implementations by us either. One of the issues is that you can never know what data you have replicated, and what data not yet. Combined with the backlogging function in the Venus-devices this means that you'll have to continuously query quite far into the past in order to really make sure to have data replicated. We might some day design a proper replication function; but at the moment there are no such plans and also we will not offer support of such setups; unless the involved directly commercial value is extremely high.

If you really do want to host the data; we recommend to implement your own data transmission system on the Venus-device. Or change the URL of the existing data-transmission system on the Venus-device to your own URL. Note that this will (obviously) break all the advanced features such as Remote Firmware updates, Remote Support, Remote Console, and-so-forth.


Rate limiting and error 429

If you receive HTTP error 429 - Too many requests, it means that you have exceeded rate limiter limits.


Authentication endpoints

The authentication endpoints include the only endpoints in the API for which no authorization header is required to access them.


Login


Username and password

POST /v2/auth/login
{
    "username": "john@example.com",
    "password": "secret-passw0rd"
}

Or, if a SMS authentication token is required:

{
    "username": "john@example.com",
    "password": "secret-passw0rd",
    "sms_token": "12345678"
}

When logging in a token is issued which may be used to authorize further requests by including it in the "X-Authorization" request header as follows:

X-Authorization: Bearer {token}


Access token

When using personal access tokens (accesstokens), you have a token that can authenticate against the VRM API without the need of requesting a bearer token. Authentication with such an access token can be done as following:

X-Authorization: Token <your-personal-access-token>


Login as demo

GET /v2/auth/loginAsDemo
Issues an token for accessing the API as the VRM demo user (userid: 22). The demo user has limited access (not all endpoints work for the demo login, e.g. diagnostics is not working) to a few demo installations.


Logout

POST /v2/auth/logout
Accessing this endpoint with a token set in the Authorization header will blacklist the token at the server side for further use.