Skip to content

Introduction

The APIs can be used to fetch logged values and to list machines, controllers and tags. You first need to create an API key to be able to access the API. To authorize an API request, you need to create an API key as described in the Authorization section below.

Nodes

The system is organized in a hierarchy where every group, machine, and gateway is represented by a Node with a unique nodeId. This nodeId is central to the API and is used to scope queries and identify resources within the tree structure.

When filtering by nodeId, the context often determines the scope. For example, querying a group node will typically return results for all machines and subgroups beneath it in the hierarchy.

For more details on how to query nodes, see the Nodes documentation.

Authorization

To authorize an API request you first need to create an API key. As a system administrator you can create one in the portal using the API keys view. This view is accessible from the User Management menu in the left sidebar.

img

  1. Click New key and fill in the form.

  2. When created you will receive a key and a secret. Make sure you store these in a safe place, since the secret cannot be retrieved again.

    These fields need to be passed in the headers with each API request.

    "apikey": <key>, "apisecret": <secret>

  3. In order to use the API locally on the gateway, together with the new API key, the configuration must first be sent to the gateway.

  4. Fetching all machines using cURL can look like this.

    curl -H "apikey: <key>" -H "apisecret: <secret>" 'http://<GatewayIp>/api/v1/twins'

Local and cloud APIs

The APIs exist both locally on the gateway and in the cloud. It is preferred to access the APIs on the gateway, due to heavier throttling in the cloud.

Local API

The local API uses the HTTP scheme where the host name is the IP address of the gateway, e.g. 192.168.2.1. The local API is available on both network interfaces on the gateway.

http://<GatewayIp>/api/v1/machines

Cloud API

The cloud API uses the HTTPS scheme where the host name is portal.connectitude.com.

https://portal.connectitude.com/api/v1/machines