What is the relayr Cloud?

The relayr Cloud is a computing platform designed for industrial IoT. It is a managed multi-tenant environment available on one of relayr's infrastructure partners.

The different endpoints offered by the relayr Cloud can be used to build your own solutions or to integrate the relayr Cloud with your existing solutions or other relayr technology products (Dashboards, Analytics and Gateway solutions). This website lists all of the Cloud endpoints and explains how to use them.

Architecture

The relayr Cloud architecture revolves around devices, which are the most basic elements of the platform. Devices are entities that can transmit and receive data to and from the Cloud. They represent a machine, or any other industrial asset connected to the Cloud.

The data sent and received to and from the Cloud is then represented as measurement and alert values you can leverage according to your use case, using the different Cloud endpoints. User services also allow you to control who can access the Cloud services used in your solution. Browse the left navigation panel of this website to get a complete overview of the Cloud features.

Versioning

The relayr API is usually updated at each release and follows the below rules:

• No breaking change is ever introduced.
• New endpoints may be added.
• Deprecated endpoints are removed on a specified date.

Errors

The relayr API uses standard HTTP status codes to indicate the success or failure of a call. The body of the response is a JSON in the following format:

{
  "error": {
    "id": "e75ec4f4772ebdcc5c73f50cda9a8a78",
    "message": "Old password is not valid",
    "details": "More about what a valid password looks like",
    "code": "PASSWORD_MALFORMED"
  }
}

The error fields code and details are optional and not always present.

Rate limits

The numbers in the table below indicate the number of requests you can send to the Cloud per second per IP.

NOTE: If you try to login and fail 5 times in a row within an hour, your account gets blocked for 5 mins even if you haven’t reached 50 requests.

Requirements

Authorization

• Relayr credentials:
  • User name
  • Password
  • Organization
• Access token or API key. More information on how to acquire an access token or create an API key is available under Cloud Access in the left navigation panel.

Tools

• curl
• jq

NOTE: The request URL for these endpoints is: https://login.relayr.io/.

The relayr Cloud uses OAuth 2.0 as its main authorization protocol. Your relayr credentials (user name, password and organization) are required to acquire the following tokens:

• Access tokens, valid for 100 minutes
• Refresh tokens, valid for 15 years

Tokens are used in the authorization header when sending API calls to the Cloud, as follows: Authorization: Bearer <token>. The endpoints presented in this section allow you to acquire and manage access and refresh tokens for the Cloud and/or your websites connected to the Cloud.

The relayr Cloud lets you create API keys as an alternative way to access the Cloud. API keys are used in the following header when making calls to the Cloud: X-Api-Key: <api-key>. The endpoints presented in this section allow you to create and manage API keys.

As there is no concept of Api-key permissions in the relayr cloud. When using Api-key caller will get exactly the same permissions as the user that has created the Api-key. Permissions will be resolved at the moment of the call. This means that if the role of the user that created the key gets updated or changed, a caller that uses api-key will get an updated list of permissions.

NOTE: The request URL for these endpoints is: https://login.relayr.io/.

The relayr Cloud provides endpoints to create website pages for user authorization. Pages can be branded according to your use case. The endpoints presented in this section allow you to create website pages where logged in users can send invitations to a website to other users, users can accept invitations to different platforms and create and reset their passwords.

The relayr Cloud supports the MQTT protocol for a variety of purposes. The endpoints presented in this section allow you to create and delete MQTT credentials for devices.

For more information on the MQTT topics available on the relayr MQTT broker, please go to our MQTT documentation website.

The relayr Cloud supports the MQTT protocol for a variety of purposes. The endpoints presented in this section allow you to create and delete MQTT credentials for device groups.

For more information on the MQTT topics available on the relayr MQTT broker, please go to our MQTT documentation website.

Device models are entities which enable the relayr Cloud to make sense of the data received and transmitted by your devices. They essentially provide the semantics of the data to display.

A device model has a name and a description, while the actual information on the data a device can send/receive is defined in a version of a device model. Creating a device model and a device model version is hence your first step to create a device.

The endpoints presented in this section let you create and manage device models and their versions.

Devices constitute the most basic element of the relayr platform. Devices are entities that can transmit and receive data to and from the Cloud. They represent any piece of virtual or physical equipment capable of connecting to the relayr Cloud as defined below:

• Physical equipment: piece of physical hardware, such as a single-board computer (e.g., the Raspberry Pi), a sensor or an actuator.
• Virtual equipment: program running locally on a computer that sends and receives data to and from the relayr Cloud.

The data sent and received to and from the Cloud is then represented as measurement and alert values. The endpoints presented in this section let you create and manage devices.

NOTE: Before creating a device, you must create a device model and at least one device model version. Go to Device Models in the left navigation panel for more information on device models and their versions.