Skip to main content

How to use the innius API?

Updated

1. API Overview

The innius API is an interface that allows programmatic access to much of the data in the innius system. It provides predictable URLs for accessing resources, and uses built-in HTTP features to receive commands and return responses. This makes it easy to communicate with from a wide variety of environments, from command-line utilities to gadgets to the browser URL bar itself.

This article describes the contextual information of the innius API. The link to the technical innius API reference documentation can be found here.

 

REST API

The innius API is a REST API that is used to:

  • Request my company id
  • Request the collection of machines for my company
  • Request the collection of sensors for a specified machine at my company
  • Request sensor values for a single sensor for a specified machine at my company

The REST API accepts JSON content in requests and returns JSON content in all of its responses, including errors. Only the UTF-8 character encoding is supported for both requests and responses.

First you need to request my company id if not already known from the admin web app. Subsequently, corresponding resources such as machines, sensors, and sensor values can be requested.

 

Object Hierarchy

 

innius-api-graph.png

 

Pagination

Pagination is an important concept when working with the innius API. For example, the get sensor values query has paginated results.

When making a paginated request, the API will return a number of results as specified by the limit parameter. The next result set can be retrieved by specifying the offset query parameter start_key. If next_key is null or 0 there are no more pages available.

 

Responses

If the request was successful, the response body will contain a data field with the results.

In the event of an error, the response body will contain a message field providing more detail about the error that occurred.

 

Code Meaning Description
200 Success If data was requested, it will be available in the data field at the top level of the response body.
400 Bad Request This usually occurs because of a missing or malformed parameter. Check the documentation and the syntax of your request and try again.
401 Unauthorized A valid authentication token was not provided with the request, so the API could not associate a client with the request.
403 Forbidden The authentication and request syntax was valid but the server is refusing to complete the request. This can happen if you try to read or write to objects or properties that the client does not have access to.
404 Not Found Either the request method and path supplied do not specify a known action in the API, or the object specified by the request does not exist.
429 Too Many Requests You have exceeded one of the enforced limits in the API. See the API limitations for more details.
500 Internal Server Error There was a problem at innius's end.

 

2. API Getting Started

The goal is to setup a programmatic connection with the innius platform to obtain sensor data.

First, we need to create an innius account and a secret innius API key. Next, we try the connection and query the innius API.

 

Create an innius account

First, generate an account in innius. You can do this via the following link:

A new account gets a 30 day free trial period. 

 

Create an innius API key

Next, login to the innius Admin app using your innius account and create a secret innius API key.

In the following Knowledge Base article you can find how to do this:

Remember to keep your API key secret; treat it just like any password. Do not hardcode it into your programs. Opt to use it as an environment variable, or obtain this secret key from a secure repository during runtime.

 

Try out the innius API

  1. Browse to the technical innius API reference documentation page.
  2. Set the innius API key:
    • Select Authentication.
    • Fill in your secret innius API key in the x-api-key field.
    • Press set .
  3. Obtain my company id:
    • Go to Companies > Get my company info.
    • Press try.
    • The result should be Response Status: OK:200, with my company id in the data field.
  4. Obtain the list of machines:
    • Go to Machines > List machines. Fill in the company id obtained in the previous step.
    • Press try.
    • The result should be Response Status: OK:200, with a list of machines in the data field.

3. API Limitations

To protect the stability of the API and keep it available to all users, innius enforces two kinds of limiting: 1) rate limiting, and 2) limiting the data points that can be queried (see table below).

Requests that hit any of our rate limits will receive a 429 Too Many Requests response, which contains the standard Retry-After header indicating how many seconds the client should wait before retrying the request. Rate limits are allocated per API key. Note that an initial burst of requests is permitted in the first minute before the base rate limit kicks in.

 

Parameter Description Value

Maximum requests per hour

60

Maximum burst of requests

60

Maximum number of data points per page

1000

 

4. API Reference 

You can find the technical innius API reference documentation here:

 

5. Terms of Service

The use of this API is bound to the following terms:

 

Related articles