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:
Response:curl -H 'X-NRR-Api-Key: api-key-here' https://api.nitrorigs.com/latest/resetters
[ { "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:
Response:curl -H 'X-NRR-Api-Key: api-key-here' https://api.nitrorigs.com/latest/resetters/1000
{ "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
Response: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
{"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:
Response:curl -H 'X-NRR-Api-Key: api-key-here' \ https://api.nitrorigs.com/latest/resetters/1000/power-consumption-log
[ { "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:
Response:curl -H 'X-NRR-Api-Key: api-key-here' \ https://api.nitrorigs.com/latest/resetters/1000/power-consumption-log/monthly
[ { "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:
Response:curl -H 'X-NRR-Api-Key: your-api-key-goes-here' \ https://api.nitrorigs.com/latest/restters/1000/events-log?age=48&limit=20
[ { "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:
Response:curl -H 'X-NRR-Api-Key: api-key-here' \ https://api.nitrorigs.com/latest/resetters/data/1000,1001,1002,1003
[ { "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