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

  1. 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

    idUnsigned IntUnique identifier
    labelStringUser defined label
    last-ipUnsigned Int/NullEncoded local IP address
    last-seenUNIX TimestampWhen the device was last online
    macStringEthernet MAC address of the device
    meterFloatkWh metered by this device. Value can only increase during the lifetime of the unit. Updated once a minute while the device is online
    onlineBooleanWhether the device is connected to the NitroRigs servers and sending data
    serialStringSerial number of the device (may contain letters in the future!)
    settingsDictionaryThe latest auto-restart settings on the device. See below
    tagsStringUser defined custom tags

    Settings Dictionary Keys

    graceful-interval-after-bootUnsigned IntDelay after device boots (e.g. after power loss) before applying any auto-restart rules
    graceful-interval-after-resetUnsigned IntDelay after load restart before applying auto-restart rules
    load-disabledBooleanIf set to True will turn off the load indefinitely
    max-loadUnsigned IntMax Watts allowed for the load
    min-loadUnsigned IntMin Watts allowed for the load
    monitor-loadBooleanIf set to True will apply the min/max load power consumption rules and auto-restart it
    reset-intervalUnsigned IntTime interval (in seconds) to keep the load off during restart
    max-restartsUnsigned IntMaximum number of consecutive auto restarts without reaching the defined load consumption rules
    seconds-load-outside-rangeUnsigned IntMinimum 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.

  2. 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.

  3. 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

    startUNIX TimestampMetering interval start
    endUNIX TimestampMetering interval end
    consumedFloatConsumed 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.

  4. 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.

  5. 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_timestampUNIX timestampTimestamp when the device generated the event
    server_timestampUNIX timestampTimestamp when the server received the event
    typeUnsigned IntIdentifies the type of event (see values below)
    descriptionStringDescription of the event, can be presented to the end user
    reasonUnsigned IntOnly for events of type 1 - reason for load restart (see below)
    attemptsUnsigned IntOnly for events of type 1 - attempts to restart (see below)
    loss_timestampUNIX timestampOnly for events of type 2 - when power was lost

    Event Types

    1Load restarted
    3Resetter power lost
    4Automatic restart algorithm gave up
    10Configuration changed
    11Load powered off (not for restart)
    12Load 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:

    2Power consumption was out of range
    4User requested (via UI, API method etc)
    5Fuse 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.

  6. 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

    vFloatPower input voltage (in volts)
    wFloatLoad power (in watts)
    aFloatLoad current (in amperes)
    fFloatLoad power factor (in percentage)
    caFloatActive energy all-time metered by the unit (energy meter, in kWh)
    rsIntegerResetter 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:

    1In "graceful-interval-after-boot" delay
    2Standing by, may apply auto-restart rules if configured
    3Restarting the load (between powering it off and on)
    4In "graceful-interval-after-restart" delay
    5Gave 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