NitroRigs API

The NitroRigs Resetters API provides simple and powerful access to the devices on your account. Built following the industry standards (HTTP, REST, JSON, WebSocket) it allows integration from any programming language.

Please note the APIs are under construction and will be extended with new features soon.

Endpoints and Versioning

The current API version is 0.1 and is available at https://api.nitrorigs.com/v0.1/. There is also https://api.nitrorigs.com/latest/ endpoint that will be regularly updated to point to the latest version of the API.

Note that the API version will be bumped only if there are backward-incompatible changes. Adding new methods to the latest release will not be considered one. Also when adding keys to some responses we may or may not bump the version. Keep this in mind and ignore extra keys in the various dictionaries returned by the server until you implement handling them.

We will keep a log on this page with information about all changes to requests and responses.

Authentication and Security

With each API call you have to provide an API key via X-NRR-Api-Key header. You can obtain one from your account page.

Always connect to the servers via TLS1.2 only. Older encryptions allow various attacks and may result in stealing your API key.

Rate Limiting and Misuse

Every API key is limited to 100 HTTP requests per minute. If hit the response will be HTTP code 429 with body {"error":"Too many requests"}. Hitting the rate limits repeatedly may result in permanent ban on your API key, account and IP address, so beware.

The WebSocket server does not employ rate limiting for the time being but one may be introduced in the future.

Talking to the APIs

Almost all methods to access and retrieve data require sending standard HTTP requests. The only exception is reading real-time data from resetters, which is available over WebSocket. Request and response bodies (where applicable) must be in standard valid JSON format.

Upon success you will receive 200 OK response. Failure will be replied with appropriate codes - 404 if the request URI did not point to correct API method or object, 400 if the request was invalid and etc.

Some error responses will be accompanied with JSON dictionary with "error" key, pointing to a message describing the problem. These messages should not be presented to end user as they are intended only to aid the development process.

REST API Methods Reference

Method GET /resetters

Returns an array of the resetters on your account with relevant information. Only GET requests are allowed.

CURL example request:

curl -H 'X-NRR-Api-Key: api-key-here' https://api.nitrorigs.com/latest/resetters

Response:

[
  {
    "id": 1000,
    "label": "User Label",
    "last-ip": 3232235521,
    "last-seen": 1522930157,
    "mac": "AA:BB:CC:01:02:03",
    "meter": 1.2244,
    "online": true,
    "serial": "18270103",
    "tags": "",
    "settings": {
      "graceful-interval-after-boot": 30,
      "graceful-interval-after-reset": 30,
      "load-disabled": false,
      "max-load": 1600,
      "max-restarts": 5,
      "min-load": 300,
      "monitor-load": false,
      "reset-interval": 10,
      "seconds-load-outside-range": 600
    }
  },
  ...
]

Device Dictionary Keys

id	Unsigned Int	Unique identifier
label	String	User defined label
last-ip	Unsigned Int/Null	Encoded local IP address
last-seen	UNIX Timestamp	When the device was last online
mac	String	Ethernet MAC address of the device
meter	Float	kWh metered by this device. Value can only increase during the lifetime of the unit. Updated once a minute while the device is online
online	Boolean	Whether the device is connected to the NitroRigs servers and sending data
serial	String	Serial number of the device (may contain letters in the future!)
settings	Dictionary	The latest auto-restart settings on the device. See below
tags	String	User defined custom tags

Settings Dictionary Keys

graceful-interval-after-boot	Unsigned Int	Delay after device boots (e.g. after power loss) before applying any auto-restart rules
graceful-interval-after-reset	Unsigned Int	Delay after load restart before applying auto-restart rules
load-disabled	Boolean	If set to True will turn off the load indefinitely
max-load	Unsigned Int	Max Watts allowed for the load
min-load	Unsigned Int	Min Watts allowed for the load
monitor-load	Boolean	If set to True will apply the min/max load power consumption rules and auto-restart it
reset-interval	Unsigned Int	Time interval (in seconds) to keep the load off during restart
max-restarts	Unsigned Int	Maximum number of consecutive auto restarts without reaching the defined load consumption rules
seconds-load-outside-range	Unsigned Int	Minimum interval that the load must be outside the defined min/max power consumption for auto-restart to occur

Understanding the Auto-Restart Settings

There several parameters for the Auto-Restart-On-Load that work together. Monitor-Load enables that feature altogether – if set to false the values for the other parameters will be ignored.

The resetter monitors the load power consumption and compares it with the specified min-load and max-load values (in watts). If it goes outside that range and remains there for "seconds-load-outside-range" interval it will trigger automatic restart. The duration between turning it off and back on is defined in "reset-interval".

After a load is restarted the unit will not check if it meets the min/max-load range for "graceful-interval-after-reset" seconds to allow it to properly boot. Once this timer expires it will begin monitoring it again.

If the load doesn't reach the specified min/max consumption even after "max-restarts" attempts the unit will "give up restarting" and stop applying the rules. Only after manual restart (via the UI or API request) or after the load reaches its min/max range it will reset the state machine and begin applying the auto-restart rules again.

Method GET/POST /resetters/(id)

GET request returns a dictionary with information about a resetter, POST request updates user-defined information and settings.

Keys description is available in the /resetters method reference

CURL example request to get information about a resetter:

curl -H 'X-NRR-Api-Key: api-key-here' https://api.nitrorigs.com/latest/resetters/1000

Response:

{
  "id": 1000,
  "label": "User Label",
  "last-ip": 3232235521,
  "last-seen": 1522930157,
  "mac": "AA:BB:CC:01:02:03",
  "meter": 1.2244,
  "online": true,
  "serial": "18270103",
  "tags": "",
  "settings": {
    "graceful-interval-after-boot": 30,
    "graceful-interval-after-reset": 30,
    "load-disabled": false,
    "max-load": 1600,
    "max-restarts": 5,
    "min-load": 300,
    "monitor-load": false,
    "reset-interval": 10,
    "seconds-load-outside-range": 600
  }
}

CURL example request to modify a resetter

curl -X POST -H 'X-NRR-Api-Key: api-key-here' -H 'Content-Type: application/json' \
--data '{"label":"New User Label", "settings":{\
"monitor-load": true, "min-load":280, "max-load":1280, "max-restarts": 5, \
"load-disabled":false, "reset-interval": 40, "seconds-load-outside-range": 60, \
"graceful-interval-after-boot": 600, "graceful-interval-after-reset": 60}}' \
https://api.nitrorigs.com/latest/resetters/1000

Response:

{"ok": true}

If a key is missing from the request it will retain its previous value without change. For example sending a POST request with body {"settings":{"load-disabled":true}} can be used to turn off the load without modifications to any other settings.

Some fields are read-only and cannot be modified: id, last-ip, last-seen, mac, meter, online, serial.

Method GET /resetters/(id)/power-consumption-log
Returns a list of aggregated power consumption per day for the last 30 days. Alternative URI is /resetters/(id)/power-consumption-log/daily.

The method will not return data for dates before the pairing. Even if the device has been unpaired and paired to the same account again the readings will not be accessible.
CURL example request to get information about a resetter:
```
curl -H 'X-NRR-Api-Key: api-key-here' \
https://api.nitrorigs.com/latest/resetters/1000/power-consumption-log
```
Response:
```
[
  {
    "start":1522540800,
    "end":1525132799,
    "consumed":1.30901
  },
  {
    "start":1525132800,
    "end":1527811199,
    "consumed":2.450625779251
  },
  ...
]
```
Log Dictionary Keys

start UNIX Timestamp Metering interval start

end UNIX Timestamp Metering interval end

consumed Float Consumed power (kWh) for the interval

Note that handling gaps in readings is up to the client. They may occur if the device was not online at the time the servers generated the logs. In that case some power usage may get transferred to the next accounting date.
Method GET /resetters/(id)/power-consumption-log/monthly
Returns a list of aggregated power consumption per month for the last 12 months, similar to the daily log.

The method will not return data for dates before the pairing. Even if the device has been unpaired and paired to the same account again the readings will not be accessible.
CURL example request to get information about a resetter:
```
curl -H 'X-NRR-Api-Key: api-key-here' \
https://api.nitrorigs.com/latest/resetters/1000/power-consumption-log/monthly
```
Response:
```
[
  {
    "start":1514764800,
    "end":1514764799,
    "consumed":32.1231
  },
  {
    "start":1517443200,
    "end":1517443199,
    "consumed":65.1121
  },
  ...
]
```
Log Dictionary Keys

See method /resetters/(id)/power-consumption-log

Note that similar to the daily log handling of missing intervals is up to the client.

Method GET /resetters/(id)/events-log

Returns a list of events reported by the device. The method supports the following optional query parameters:

• age - how old the returned events can be in hours. By default is 24 hours, can be up to 168.

• limit - how many events can be returned. By default 10, maximum of 100. If there are more than the specified amount the oldest will be skipped

If you specify higher than the maximum values for age or limit the method will silently trim them to the appropriate values.

The method will not return entries for dates before the pairing. Even if the device has been unpaired and paired to the same account again the logs will not be accessible.

CURL example request to get latest 20 events, no older than 48 hours:

curl -H 'X-NRR-Api-Key: your-api-key-goes-here' \
https://api.nitrorigs.com/latest/restters/1000/events-log?age=48&limit=20

Response:

[
  {
    "device_timestamp":1541167469,
    "server_timestamp":1541405414,
    "type":3,
    "description":"MyRig lost power on 25 Oct 2018 13:30 for 8 days"
  },
  {
    "device_timestamp": 1541980800,
    "server_timestamp": 1541980801,
    "type": 1,
    "description": "MyRig restarted because load power consumption was out of range",
    "reason": 2,
    "attempts": 1
  },
  ...
]

Log Dictionary Keys

device_timestamp	UNIX timestamp	Timestamp when the device generated the event
server_timestamp	UNIX timestamp	Timestamp when the server received the event
type	Unsigned Int	Identifies the type of event (see values below)
description	String	Description of the event, can be presented to the end user
reason	Unsigned Int	Only for events of type 1 - reason for load restart (see below)
attempts	Unsigned Int	Only for events of type 1 - attempts to restart (see below)
loss_timestamp	UNIX timestamp	Only for events of type 2 - when power was lost

Event Types

1	Load restarted
3	Resetter power lost
4	Automatic restart algorithm gave up
10	Configuration changed
11	Load powered off (not for restart)
12	Load powered on (not after restart)

Note that new event types may be added without warning, including to released versions of the APIs.

Load Restarted Event Keys

For events of type 1 (Load restarted) two extra keys are available in the entry – reason and attempts, providing additional information.

•attempts - the consecutive index of automatic restart without rules getting back to the requested values. For example if the resetter keeps restarting its load and it does not reach its required consumption this will keep increasing with each restart until it reaches configuration’s max-restarts value. Then it will give up and event type 4 will be generated. If the load reaches its required parameters the attempts will be reset and the algorithm will start monitoring again.

•reason - indicates why the load was restarted. Possible values are:

2	Power consumption was out of range
4	User requested (via UI, API method etc)
5	Fuse overload – the power consumption was higher than the allowed by the device

Note that new reason values may be added without warning, including to released versions of the APIs.

Power Loss Event Keys

For events of type 2 (power loss) an extra key is added: loss_timestamp, indicating when the power went off. You can use the device_timestamp to determine when it came back on.

Method GET /resetters/data/(id1,id2,...)
Return measurement/metering data from one or more resetters. Provides simpler approach, compared to implementing WebSocket connection, but data returned is not guaranteed to be available and may be up to 5 seconds old.

The URI may contain up to 20 comma-separated resetter ids. If you request for more than that the API will ignore the rest. Make sure the URI does not become too long – it is recommended to keep it below 255 characters.

Resetters that are not online or for some reason we don't have fresh data for them will be omitted from the response.
CURL example request to get information about a resetter:
```
curl -H 'X-NRR-Api-Key: api-key-here' \
https://api.nitrorigs.com/latest/resetters/data/1000,1001,1002,1003
```
Response:
```
[
  {
    "id": 1000,
    "a": 1.644,
    "ca": 0.792705727,
    "f": 0.99,
    "v": 222.49,
    "w": 362,
    "rs": 2
  },
  {
    "id": 1001,
    "a": 1.244,
    "ca": 52.129,
    "f": 0.98,
    "v": 222.12,
    "w": 270,
    "rs": 2
  }
]
```
For explanation what the keys represent check the WebSocket API device real-time data. The "id" field is the resetter identifier as requested.

Access Real-Time data via WebSocket

To receive real-time data connect a WebSocket to ws://api.nitrorigs.com/resetters-data with the same api-key header as the REST methods. Once connection is established you will receive authentication confirmation. After that you can send messages to the server and register for real-time information updates.

All transmitted information uses JSON-encoded text messages.

Most messages sent by the server contain a "device" key that points to the unique integer identifier of the resetter they are related to.

Note that there may be messages sent by the server that are not yet documented here and should be ignored by the clients.

Authentication confirmation, sent by the server

Message: {"auth":true}

This message is sent first upon connection establishment to inform the client that the provided authentication header is correct. If authentication has failed usually the server will respond with {"auth": false} and close the connection immediately. This allows easy client-side confirmation of authentication.
Device registration, sent by the client
Message: {"reg":[1,2,3]}

This message is sent at any time by the client to register for real-time data from certain devices. The IDs of the devices can be obtained via the /resetters REST API method.

Note that sending this message multiple times does not replace previously requested devices but adds those that are not yet connected.

If there is even one invalid ID in the request it will be dropped.

Response from the server

The server will reply with another "reg" message to confirm the operation and begin pushing real-time information about the registered devices:
```
{
  "reg":[
    {"id":1, "online":true, "last_seen": 1522930157},
    ...
  ]
}
```
For each successfully registered device there will be an entry in the "reg" array, describing its current state. The id key is the unique identifier of the device, online indicates if the resetter is connected and sending data, last_seen is UNIX timestamp indicating when was the device last online.

Device real-time data, sent by the server

Message:

{
  "device": 1000,
  "data": {
    "v": 221.2, 
    "w": 452, 
    "a": 2.01, 
    "f": 0.98,
    "ca": 1237.05,
    "rs": 1
  }
}

This message is pushed by the server regularly (about once a second) for each device, registered via "reg" command. It contains energy readings and status from the individual unit.

Data Dictionary Keys

v	Float	Power input voltage (in volts)
w	Float	Load power (in watts)
a	Float	Load current (in amperes)
f	Float	Load power factor (in percentage)
ca	Float	Active energy all-time metered by the unit (energy meter, in kWh)
rs	Integer	Resetter state, optional

The "rs" field indicates the state of the auto-reset algorithm in the resetter. Some older models do not provide that information so it is marked as optional, but they are very rare. For those the field will be missing from the response. The possible values are:

1	In "graceful-interval-after-boot" delay
2	Standing by, may apply auto-restart rules if configured
3	Restarting the load (between powering it off and on)
4	In "graceful-interval-after-restart" delay
5	Gave up restarting – load is not coming back into regulation and will not be restarted until manual intervention

Device online status update, sent by the server

Message: {"device": 1000, "online": true}

Informs the client if a resetter has come online/went offline. Note that message about a device coming online may be skipped under some rare circumstances, so if the client receives data from a device that is offline it should assume it has come online.
Device configuration update notification, sent by the server

Message: {"device":1000, "cmd":"config_update"}

This is a special message to notify clients that there has been a change in the configuration of a device. It is triggered by the UI and the API. If the client caches configuration information for the resetters they should update it (e.g. via the HTTP /resetters/(id) REST API method) when this message is received.
Device event log entry notification, sent by the server

Message: {"device":1000, "new_log":true, "entry_id":(id)}

Notifies the client that a new event was logged by the resetter. When received you can use the /resetters/(id)/events-log REST API method to fetch the details.

The new_log key is always set to true - it is there only to allow easier identification of the message.
Keep-alive requests, sent by the client

Message: {"keep-alive":true}

Send this message regularly to the server to notify it that you are still connected and receiving data. Recommended interval is 5 seconds. You may reset this timeout upon sending other messages. The server must reply with the same {"keep-alive":true} message to confirm.

If the server does not receive any message from the client for 10 seconds it will drop the connection. If you don't receive a response to your keep-alive requests for 10 seconds you should consider the connection dead and reestablish it.

Alternatively you can send standard WebSocket Ping control frames (0x09) to the server and it will reply with the appropriate Pong (0x0A).

Having Trouble using the APIs?

Just drop us an email at support@nitrorigs.com or via the contact form

start	UNIX Timestamp	Metering interval start
end	UNIX Timestamp	Metering interval end
consumed	Float	Consumed power (kWh) for the interval

NitroRigs API

Endpoints and Versioning

Authentication and Security

Rate Limiting and Misuse

Talking to the APIs

REST API Methods Reference

Method GET /resetters

Device Dictionary Keys

Settings Dictionary Keys

Understanding the Auto-Restart Settings

Method GET/POST /resetters/(id)

Method GET /resetters/(id)/power-consumption-log

Log Dictionary Keys

Method GET /resetters/(id)/power-consumption-log/monthly

Log Dictionary Keys

Method GET /resetters/(id)/events-log

Log Dictionary Keys

Event Types

Load Restarted Event Keys

Power Loss Event Keys

Method GET /resetters/data/(id1,id2,...)

Access Real-Time data via WebSocket

Authentication confirmation, sent by the server

Device registration, sent by the client

Response from the server

Device real-time data, sent by the server

Data Dictionary Keys

Device online status update, sent by the server

Device configuration update notification, sent by the server

Device event log entry notification, sent by the server

Keep-alive requests, sent by the client

Having Trouble using the APIs?