VoltStorage
Documentation Powered by ReDoc

VoltStorage API (1.22.0)

Download OpenAPI specification:Download

David Bauske: admin@voltstorage.com

REST-API for reading and/or manipulating data related to VoltStorage batteries

Authentication

BearerAuth

The bearer token needs to the sent with most requests. A token can be obtained through a login request to /rest/login/password. The token must be passed in the following format:

Authorization: Bearer <token>
Security Scheme Type HTTP
HTTP Authorization Scheme bearer
Bearer format "JWT"

QueryAuth

Fallback authentication scheme if bearer authorization is not possible due to some client requriements. Pass the authorization token in the query string using the key token:

...&token=<token>
Security Scheme Type API Key
Query parameter name: token

Password Login

Logs a user in by verifying their email/password combination. Returns a JWT (JSON WebToken, https://jwt.io/) used to authenticate the user to other endpoints.

Authorizations:
Request Body schema: application/json

Login credentials

email
required
string <email>

User E-Mail address. Case insensitive.

password
required
string <password>

The password to test. Will never be saved.

validity
number <int64> [ 0 .. 31622400‬ ]
Default: 86400

Duration of validity of the token in seconds. Defaults to one day. Maximum: One year

Responses

200

OK - Login successful

400

Bad request - missing parameters or invalid credentials

post /login/password
https://api.voltstorage.com/rest/login/password

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "email": "anybody@example.com",
  • "password": "Password123!",
  • "validity": 86400
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}

List Products

Fetches a list of products. Only products the authenticated user has access to will be returned.

Authorizations:
BearerAuthQueryAuth
query Parameters
count
integer >= 1

Maximum number of products to return. Useful for pagination.

page
integer >= 1

The page to displayed. The first page is 1. The page size is specified by count. Skips over count * page entries before returning data.

q
string

Free-text search. Filters the product list by several product attributes, such as the ID, the serial number, the type name, ...

groupId
integer

Filters the product list, only returning products belonging to the specified group

installationDate
boolean

Filters the product list by only returning installed products (true) or non-installed products (false)

ids
integer or Array of integers
ownerId
integer

Filters the product list by only returning products with a specified owner

sort
string

Comma-separated list of product fields to sort the output by. Defaults to ascending sort order, prepend a - (minus) sign to a field to sort in descending order. Example:

installationDate,-id

Sorts products by their installationDate (ascending). If two products have been installed on the same day, these products will be returned in descending ID order.

Responses

200

OK

400

Bad Request - Invalid parameters. The response body will contain a more detailed description of what went wrong.

401

Unauthorized - No authorization token was provided. Please send your login token with every request as described in BearerAuth.

403

Forbidden - You lack the appropriate permissions to perform this action or read this data.

get /products
https://api.voltstorage.com/rest/products

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    }
]

[WebSocket] Product Data Stream

Provides a read-only data stream that is notified whenever a product event occurs, such as when new data arrives. It is highly recommended to use this method of keeping up to date with a product's data. Compared to polling, this has massive advantages:

  • No unnecessary load for the server
  • Not subject to rate limiting
  • Faster data availability on the client side (the WebSocket message is broadcasted as soon as data is available, not just at regular intervals)
  • No need to maintain polling intervals on the client side, many client will find that WebSocket events are more natural way of handling incoming data

The response samples on the right-hand side provide examples of messages sent by the server via this WebSocket connection. No messages from the client will be accepted on this WebSocket.

Authorizations:
QueryAuth
path Parameters
productId
required
integer

ID of the product you'd like to connect to

query Parameters
token
required
string

Your API authentication token as obtained from a login endpoint

Responses

101

Switching protocols - WebSocket connection

400

Bad Request - Invalid parameters. The response body will contain a more detailed description of what went wrong.

401

Unauthorized - No authorization token was provided. Please send your login token with every request as described in BearerAuth.

403

Forbidden - You lack the appropriate permissions to perform this action or read this data.

get /products/{productId}/data
https://api.voltstorage.com/rest/products/{productId}/data

Response samples

Content type
application/json
Example
latest-data: One or more data values changed
Copy
 Expand all Collapse all
{
  • "type": "latest-data",
  • "time": 1575154800,
  • "data":
    {
    }
}

Product Latest Data

Returns the latest value of all data fields of a product.

Depending on the value of "includeTime", the response either contains the keys "time" and "data" or the product data fields directly as key-value pairs.

Authorizations:
BearerAuthQueryAuth
query Parameters
includeTime
boolean

Pass "true" to retrieve the timestamp when the data was last updated (slightly slower) or "false" if no timestamp is required (slightly faster).

Responses

200

OK

400

Bad Request - Invalid parameters. The response body will contain a more detailed description of what went wrong.

401

Unauthorized - No authorization token was provided. Please send your login token with every request as described in BearerAuth.

403

Forbidden - You lack the appropriate permissions to perform this action or read this data.

get /products/{productId}/data/latest
https://api.voltstorage.com/rest/products/{productId}/data/latest

Response samples

Content type
application/json
Example
With includeTime=true
Copy
 Expand all Collapse all
{
  • "time": 1575154800,
  • "data":
    {
    }
}

Product Statistics

Provides aggregated statistical data for a product

Authorizations:
BearerAuthQueryAuth
path Parameters
productId
required
integer

ID of the product to export data of

query Parameters
tstart
integer

Start of the time range to return statistics for

tend
integer

End of the time range to return statistics for

timespan
string
Enum: "month" "day" "hour" "year" "lifetime"

The time span for each object in the result set

Responses

200

OK

400

Bad Request - Invalid parameters. The response body will contain a more detailed description of what went wrong.

401

Unauthorized - No authorization token was provided. Please send your login token with every request as described in BearerAuth.

403

Forbidden - You lack the appropriate permissions to perform this action or read this data.

get /products/{productId}/stats
https://api.voltstorage.com/rest/products/{productId}/stats

Response samples

Content type
application/json
Copy
 Expand all Collapse all
[
  • {
    }
]

Data Export

Export product data to common data exchange formats - the omnipresent comma-separated values (CSV) format or JavaScript Object Notation (JSON)

Authorizations:
BearerAuthQueryAuth
path Parameters
format
required
string
Enum: "csv" "json"

Selects the data type for the export

query Parameters
productId
integer

Database ID of the product to export the data of. Must be provided if componentId is omitted.

componentId
integer

Database ID of the component to export the data of. Must be provided if productId is omitted.

from
required
number <double>

UNIX-Timestamp (seconds since 1970-01-01T00:00:00Z) of the first data point to return

to
number <double>
Default: "The current timestamp"

UNIX-Timestamp (seconds since 1970-01-01T00:00:00Z) of the last data point to return

fields
string

Comma-separated list of fields to include in the data export. All fields are returned if omitted.

tz
integer

UTC-offset in minutes for the exported date format

precision
integer
Default: 6

Number of significant digits for all numeric data in the export

tolerance
number <float>
Default: 0

Relative tolerance value for data pre-export data processing. Can be used to shrink the export size by omitting small changes in value for all fields. The Ramer-Douglas-Peucker algorithm is used for this simplification. Rule of thumb:

  • 0 - no compression
  • 2 - light compression (~33% data reduction)
  • 5 - normal compression (data still precise enough for most applications, ~45% data reduction)
  • 10 - high compression (~55% data reduction)
  • 20 - aggressive compression (~66% data reduction)
separator
string
Default: ","

Separation character(s) to use for the exported file. Only relevant for csv export format.

Responses

200

OK

400

Bad Request - Invalid parameters. The response body will contain a more detailed description of what went wrong.

401

Unauthorized - No authorization token was provided. Please send your login token with every request as described in BearerAuth.

403

Forbidden - You lack the appropriate permissions to perform this action or read this data.

get /data/export.{format}
https://api.voltstorage.com/rest/data/export.{format}

Response samples

Content type
text/csv
Copy
sep=,
Time,Power_Grid,Power_Household,inverterPower,Power_PV,Power_Power Electronics,SOC_State of Charge
2020-03-25T12:20:41.562+00:00,-49.8754,815.662,433.105,432.432,433.105,0.611868
2020-03-25T12:20:42.556+00:00,-71.7332,,,,,
2020-03-25T12:20:43.568+00:00,-55.5049,,395.02,,395.02,
2020-03-25T12:20:44.556+00:00,-115.449,,433.105,,433.105,
2020-03-25T12:20:45.556+00:00,-59.1815,,354.98,,354.98,
2020-03-25T12:20:46.556+00:00,-159.164,,433.105,,433.105,
2020-03-25T12:20:47.556+00:00,-63.8346,,315.918,,315.918,
2020-03-25T12:20:48.558+00:00,-43.7003,,273.926,,273.926,0.611709
2020-03-25T12:20:49.556+00:00,-107.55,,315.918,,315.918,0.611693
2020-03-25T12:20:50.556+00:00,-50.5506,,237.061,,237.061,
2020-03-25T12:20:51.556+00:00,-149.313,,313.965,,313.965,
2020-03-25T12:20:52.556+00:00,-53.2505,,196.045,,196.045,
2020-03-25T12:20:53.556+00:00,-152.989,,273.926,,273.926,
2020-03-25T12:20:54.556+00:00,99.0787,,0,,0,
2020-03-25T12:20:55.556+00:00,77.2209,,,,,0.611629
2020-03-25T12:20:56.558+00:00,,,,,,0.611628
2020-03-25T12:21:00.556+00:00,-32.068,404.35,,,,
2020-03-25T12:21:01.556+00:00,-32.3131,404.315,,,,
2020-03-25T12:21:17.556+00:00,-36.2353,,0,,0,
2020-03-25T12:21:18.558+00:00,-14.4772,,,,,
2020-03-25T12:21:19.556+00:00,9.2645,,-45.99,,-45.99,
2020-03-25T12:21:20.556+00:00,-36.9706,,0,,0,
2020-03-25T12:21:27.556+00:00,-38.6866,403.396,,,,
2020-03-25T12:21:28.556+00:00,-78.9317,363.361,,,,
2020-03-25T12:21:29.556+00:00,-79.1768,363.325,,,,
2020-03-25T12:25:06.564+00:00,-139.382,351.129,,490.511,,0.611472