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.
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.
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
0 there are no more pages available.
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.
|200||Success||If data was requested, it will be available in the
|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
- Browse to the technical innius API reference documentation page.
- Set the innius API key:
- Fill in your secret innius API key in the
- Obtain my company id:
- Go to
Get my company info.
- The result should be
Response Status: OK:200, with my company id in the
- Go to
- Obtain the list of machines:
- Go to
List machines. Fill in the company id obtained in the previous step.
- The result should be
Response Status: OK:200, with a list of machines in the
- Go to
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.
Maximum requests per hour
Maximum burst of requests
Maximum number of data points per page
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:
Note: The innius API is in beta. Do not use it in production yet.