NAV
shell javascript

Introduction

The Instathings API is organized around REST.

Our API has predictable resource-oriented URLs, accepts application/json request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Authentication

Authentication follows the OAuth client_credentials flow, so it's intented for machine to machine (M2M) authentication.

Instathings API need to be enabled to retrieve a clientId and clientSecret in the Settings section of your project.

Once you have obtained clientId and clientSecret, you can use them to request the JSON Web Token (JWT) needed to authenticate Instathings API requests.

Get Authentication token

curl -XPOST \
-H "Content-type: application/json" \
-d '{ "clientId":"yourClientId", "clientSecret": "yourClientSecret"}' \
'https://yourProjectName.instathings.io/authentication/v1/oauth/token'

The above command returns JSON structured like this:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
}

POST /authentication/v1/oauth/token

This endpoint retrieves the authentication token.

Body Parameters

Parameter Required
clientId true
clientSecret true

Device

Device REST API service allows you to perform operations on a device resource.

Other than usual CRUD operations you can:

Get all devices

curl "https://yourProjectName.instathings.io/device/v1/devices"
  -H "Authorization: Bearer abc.def.ghi"

The above command returns JSON structured like this:

[{
    "projectId": "77JTOK6B",
    "ts": 1579184185884,
    "isVirtual": true,
    "demoActive": false,
    "id": "iIrGFfgU",
    "isGateway": false,
    "name": "device1"
}, {
    "projectId": "77JTOK6B",
    "ts": 1579596302698,
    "subDevices": ["A1Owj4Eu"],
    "isVirtual": true,
    "demoActive": false,
  "id": "Wcganw3s",
    "isGateway": true,
    "name": "device2"
}, {
    "projectId": "77JTOK6B",
    "ts": 1579596309570,
    "isVirtual": true,
    "demoActive": false,
    "parentDevice": "Wcganw3s",
    "id": "A1Owj4Eu",
    "isGateway": false,
    "name": "doc"
}]

GET /device/v1/devices

This endpoint retrieve all the devices related to a project.

Get device by id

curl "https://yourProjectName.instathings.io/device/v1/devices/:deviceId"
  -H "Authorization: Bearer abc.def.ghi"

The above command returns JSON structured like this:

{
    "projectId": "77JTOK6B",
    "ts": 1579596302698,
    "isVirtual": true,
    "subDevices": [{
        "projectId": "77JTOK6B",
        "ts": 1579596309570,
        "isVirtual": true,
        "demoActive": false,
        "parentDevice": "Wcganw3s",
        "id": "A1Owj4Eu",
        "isGateway": false,
        "name": "doc"
    }],
    "demoActive": false,
    "id": "Wcganw3s",
    "isGateway": true,
    "name": "doctest"
}

GET /device/v1/devices/:deviceId

This endpoint retrieve the information related to a specific device.

Path Parameters

Parameter Required
deviceId true

Generate device certificate

curl "https://yourProjectName.instathings.io/devices/:deviceId/credentials/certificate"
  -H "Authorization: Bearer abc.def.ghi"

The above command returns an application/zip file if project is in live mode, application/json otherwise.

{
  "certificateId": "bce989d7b311d4ec5586de576143be60007f48763d6d93bd556daa37e8e66d46",
  "credentials": {
    "certificatePem": "-----BEGIN CERTIFICATE-----\ncontent\n-----END CERTIFICATE-----\n",
    "privateKey": "-----BEGIN RSA PRIVATE KEY-----\ncontent\n-----END RSA PRIVATE KEY-----\n",
    "publicKey": "-----BEGIN PUBLIC KEY-----\ncontent\n-----END PUBLIC KEY-----\n"
  },
  "demoActive": false,
  "env": "sandbox",
  "id": "q6NJl1-_",
  "isGateway": true,
  "name": "wrt5ery",
  "projectId": "9fpNZ42V",
  "protocols": [
    "IuYtREd0",
    "R2Jh6IhT",
    "vRy6GTde"
  ],
  "subDevices": [],
  "ts": 1581934276542,
  "type": "4023bd5d-9f88-4761-97c2-0e682ayf5437"
}

POST /devices/:deviceId/credentials/certificate

For projects in live environment this endpoint returns an application/zip content type with the config folder and a script to install the gate software.

For projects in sandbox environment an application/json content type is returned with credentials returned in the document.

Path Parameters

Parameter Required
deviceId true

Get data for a specific device

curl "https://yourProjectName.instathings.io/device/v1/devices/:deviceId/data"
  -H "Authorization: Bearer abc.def.ghi"

The above command returns JSON structured like this:

{
    "data": [
        {
            "ts": 1579597755184,
            "deviceId": "A1Owj4Eu",
            "data": {
                "value": 33,
                "isVirtualData": true
            },
            "ttl": 1579684155,
            "principal": "9a5e146441177cd658b7d96d7156c0564e1a141ef3dad396c6dea44284c68c86",
            "id": "99f85da2-aabf-4bcd-9c42-3804bde1cd61",
            "clientId": "N/A"
        },
        {
            "ts": 1579597694912,
            "deviceId": "A1Owj4Eu",
            "data": {
                "value": 88,
                "isVirtualData": true
            },
            "ttl": 1579684094,
            "principal": "9a5e146441177cd658b7d96d7156c0564e1a141ef3dad396c6dea44284c68c86",
            "id": "edc8d01e-0ad4-43ed-bd12-343719b297da",
            "clientId": "N/A"
        }
    ],
    "totalItems": 2
}

This endpoint retrieves ingested data sent by a specific device.

GET /device/v1/devices/:deviceId/data

Path Parameters

Parameter Required
deviceId true

Query Parameters

Parameter Required Description
start false date in ms, starting point from which retrieve data
end false date in ms, data sent after this moment are not returned in the response
page false A cursor for use in pagination. Use it with perPage, first page is page 1.
perPage false A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.

Get data for a specific device v2

curl "https://yourProjectName.instathings.io/device/v2/devices/:deviceId/data"
  -H "Authorization: Bearer abc.def.ghi"

The above command returns JSON structured like this:

{
    "data": [
        {
            "ts": 1579597755184,
            "deviceId": "A1Owj4Eu",
            "data": {
                "value": 33,
                "isVirtualData": true
            },
            "ttl": 1579684155,
            "principal": "9a5e146441177cd658b7d96d7156c0564e1a141ef3dad396c6dea44284c68c86",
            "id": "99f85da2-aabf-4bcd-9c42-3804bde1cd61",
            "clientId": "N/A"
        },
        {
            "ts": 1579597694912,
            "deviceId": "A1Owj4Eu",
            "data": {
                "value": 88,
                "isVirtualData": true
            },
            "ttl": 1579684094,
            "principal": "9a5e146441177cd658b7d96d7156c0564e1a141ef3dad396c6dea44284c68c86",
            "id": "edc8d01e-0ad4-43ed-bd12-343719b297da",
            "clientId": "N/A"
        }
    ],
    "lastEvaluatedKey": {
      "id": "something",
      "ts": 1681422509903,
      "deviceId": "something" 
    }
}

This endpoint retrieves ingested data sent by a specific device. If lastEvaluatedKey is in the response body it means that another page is available and to retrieve it a new request must be sent with the lastEvaluatedKey as stringified json (other than the other query parameters that were sent in the initial request).

GET /device/v2/devices/:deviceId/data

Path Parameters

Parameter Required
deviceId true

Query Parameters

Parameter Required Description
start false date in ms, starting point from which retrieve data
end false date in ms, data sent after this moment are not returned in the response
perPage false A limit on the number of objects to be returned. Range is between 1 and 1000, default to 10.
lastEvaluatedKey false A cursor for use in pagination, a stringified JSON to paginate through items. The value of this parameter is returned in the response body to get the next page
sort false Accepted values are -ts and ts. -ts will return device data from the most recent one to the oldest one, using ts will return results with the oldest first

Patch device by id

curl -XPATCH -H 'Authorization: Bearer abc.def.ghi' -H "Content-type: application/json" -d '{
    "name": "New name"
}' 'https://yourProjectName.instathings.io/device/v1/devices/:deviceId'

The above command returns JSON structured like this:

{}

PATCH /device/v1/devices/:deviceId

This endpoint allows you to partially update a specific device.

Path Parameters

Parameter Required
deviceId true

Body Parameters

Parameter Type Required Description
name string false Device name (max 20 char)
frequency integer false Frequency of virtual data generation in seconds (min 30)
demoActive boolean false Whether or not generate virtual data

Delete a device by id

curl -XDELETE -H 'Authorization: Bearer abc.def.ghi' 'https://yourProjectName.instathings.io/device/v1/devices/:deviceId'

The above command returns JSON structured like this:

{}

DELETE /device/v1/devices/:deviceId

This endpoint allows you to delete a specific device.

Path Parameters

Parameter Required
deviceId true

Delete a subdevice by id

curl -XDELETE -H 'Authorization: Bearer abc.def.ghi' 'https://yourProjectName.instathings.io/devices/:parentDeviceId/subDevice/subDevices/:deviceId'

The above command returns JSON structured like this:

{}

DELETE /device/v1/devices/:deviceId

This endpoint allows you to delete a specific subdevice.

Path Parameters

Parameter Required
parentDeviceId true
deviceId true

Control a device by id

curl -XPOST -H 'Authorization: Bearer abc.def.ghi' -H "Content-type: application/json" -d '{
    "state": "TOGGLE"
}' 'https://yourProjectName.instathings.io/device/v1/control/:deviceId/set'

The above command returns JSON structured like this:

{}

POST /device/v1/control/:deviceId/set

This endpoint allows you to publish payload to a specific device.

Header Parameters

Parameter Required
instathings-path true (only for HTTP devices)
instathings-method true (only for HTTP devices)

Path Parameters

Parameter Required
deviceId true

Query Parameters

HTTP devices will receive all query parameters that this endpoint has received.

Body Parameters

Body must be in json format and is forwarded to the device as is.

HTTP devices

While the endpoint is exactly the same for all protocols, to control an HTTP device you need to add:

Example:

To control a Shelly Plug S model and turn it on first check the Shelly API reference. To turn the plug on/off we need to call the /relay/0 endpoint with the turn query parameter.

Query parameters are forwarded as they are received from this endpoint so we just need to call this endpoint with ?turn=on.

To call the /relay/0 endpoint on the device we must add the following headers:

Get device status by id

curl -XPOST -H 'Authorization: Bearer abc.def.ghi' 'https://yourProjectName.instathings.io/device/v1/control/:deviceId/status'

The above command returns JSON structured like this:

{}

POST /device/v1/control/:deviceId/status

This endpoint allows you to retrieve the status of specific device.

Response status code will be a 202 status code with a Location header containing a url to poll.

Header Parameters

Parameter Required
instathings-path true (only for HTTP devices)
instathings-method true (only for HTTP devices)

Path Parameters

Parameter Required
deviceId true

Query Parameters

HTTP devices will receive all query parameters that this endpoint has received.

Body Parameters

HTTP devices will receive the body as this endpoint receives it.

HTTP devices

While the endpoint is exactly the same for all protocols, to control an HTTP device you need to add:

Retrieve operation by id

curl -XGET -H 'Authorization: Bearer abc.def.ghi' 'https://yourProjectName.instathings.io/device/v1/control/:requestId/fetch'

The above command returns JSON structured like this:

{
  "projectId": "jmdpqpZf",
  "response": {
      "state": "ON",
      "brightness": 254,
      "color": {
          "x": 0.3068,
          "y": 0.4143
      },
      "linkquality": 110,
      "color_temp": 155
  },
  "ttl": 1583243464,
  "deviceId": "BSQuiDVl",
  "id": "IVdtfGYi"
}

GET /device/v1/control/:requestId/fetch

This endpoint returns the reported device status based on the requestId.

In order to use this endpoint first call the Get device status by id which will return in the Location header poll.

Path Parameters

Parameter Required
requestId true

Get device logs

curl "https://yourProjectName.instathings.io/device/v1/devices/:deviceId/:containerId/logs"
  -H "Authorization: Bearer abc.def.ghi"

The above command returns JSON structured like this:


    [{
        "timestamp": 1586861375901,
        "type: "LOG", // type can be either LOG or ERR
        "message": "2020-04-14T10:49:35.884Z gate Connecting...\n",
        "ingestionTime": 1586861382077
    },
    {
        "timestamp": 1586861375901,
        "type: "LOG",
        "message": "2020-04-14T10:49:35.886Z gate Subscribing to staging-discover/qw9qxyV_U/staging-bErr2i6qv/device/post\n",
        "ingestionTime": 1586861382077
    }]

This endpoint retrieves the logs generated by a specific device.

GET /device/v1/devices/:deviceId/:containerId/logs

Path Parameters

Parameter Required
deviceId true
containerId true

Allowed values of containerId:

Query Parameters

Parameter Required Description
start false date in ms, starting point from which retrieve logs. It must be used with end
end false date in ms, logs generated after this moment are not returned in the response. It must be used with start

Errors

The Instathings API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your JWT token is wrong or expired.
403 Forbidden -- This endpoint restriced, authentication won't help.
404 Not Found -- The specified resource could not be found.
405 Method Not Allowed -- You tried to access an endpoint with an invalid method.
406 Not Acceptable -- You requested a format that isn't json.
429 Too Many Requests -- Too many requests! Slow down!
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- Service is down.

Protocol

Protocol REST API service allows you to perform reading operations on the protocol resource.

Get protocol by id

curl "http://yourProjectName.instathings.io/device/v1/protocols/:protocolId"
  -H "Authorization: Bearer abc.def.ghi"

The above command returns JSON structured like this:

{
  "id": "vRy6GTde",
  "name": "Zigbee",
  "slug": "zigbee"
}

GET /device/v1/protocols/:protocolId

This endpoint retrieve the information related to a specific protocol.

Path Parameters

Parameter Required
protocolId true

Type

Types REST API service allows you to perform reading operations on the type resource.

Get all types

curl "http://yourProjectName.instathings.io/device/v1/types"
  -H "Authorization: Bearer abc.def.ghi"

[{
  "addOn": "@instathings/gate-addon-zigbee",
  "description": "Hue white and color ambiance",
  "fakeSampleLabel": "onoff",
  "id": "4023br5d-9f88-4f31-97c2-0e682aef543f",
  "manufacturer": "Philips",
  "model": "9290012573A",
  "pairingMethods": [
    "touchlink"
  ],
  "physicalParameter": [],
  "protocols": [
    "vRy6GTde"
  ],
  "rooms": [
    "closed-office",
    "meeting-room",
    "toilet",
    "archive",
    "living-room",
    "bedroom",
    "kitchen",
    "open-space"
  ],
  "space": [
    "workspace",
    "home"
  ],
  "type": "sensor"
}, { ... }]

GET /device/v1/types

This endpoint retrieve all the device types available on your project.

Get type by id

curl "http://yourProjectName.instathings.io/device/v1/types/:typeId"
  -H "Authorization: Bearer abc.def.ghi"

The above command returns JSON structured like this:

{
  "addOn": "@instathings/gate-addon-zigbee",
  "description": "Hue white and color ambiance",
  "fakeSampleLabel": "onoff",
  "id": "4023br5d-9f88-4f31-97c2-0e682aef543f",
  "manufacturer": "Philips",
  "model": "9290012573A",
  "pairingMethods": [
    "touchlink"
  ],
  "physicalParameter": [

  ],
  "protocols": [
    "vRy6GTde"
  ],
  "rooms": [
    "closed-office",
    "meeting-room",
    "toilet",
    "archive",
    "living-room",
    "bedroom",
    "kitchen",
    "open-space"
  ],
  "space": [
    "workspace",
    "home"
  ],
  "type": "sensor"
}

GET /device/v1/types/:typeId

This endpoint retrieve the information related to a specific type.

Path Parameters

Parameter Required
typeId true

Websockets API

Websockets endpoint allows you to receive events notifications related to what happen in your Instathings projects.

Here are listed the event types you can receive.

Connect to websocket

The websocket connection url is wss://wss.instathings.io

Query Parameters

Parameter Required
project true
access_token true

 Message encoding

Each message sent and received via the Instathings's websocket channel is encoded in JSON format.

Every event's response consists in a JSON containing;

Parameter Description
action the event type
payload the message sent 
wscat -c 'wss://wss.instathings.io?project=YourProjectName&access_token=YourAccessToken'


const WebSocket = require('ws');

const token = 'TOKEN';
const projectId = 'PROJECTID';

const ws = new WebSocket(`wss://wss.instathings.io?project=${projectId}&access_token=${token}`);

ws.on('open', function open() {
  // connection is open
});

ws.on('message', function incoming(data) {
  // data received 
});

ws.on('error', function error(err) {
  // error
});

connected

This event is sent when a gateway connects to the Instathings Cloud.

The response payload contains the gateway device information.

{
  "action": "connected",
  "payload": {
    "projectId": "JtjYANUvs",
    "ts": 1588863421916,
    "stats": { "ingestion": 0 },
    "certificateId": "12345",
    "subDevices": [],
    "status": {
      "principalIdentifier": "1234567890",
      "clientId": "9IHOifUF4",
      "ipAddress": "84.220.143.221",
      "eventType": "connected",
      "sessionIdentifier": "2451fb42-e516-4c0e-9668-c160d199007f",
      "versionNumber": 0,
      "timestamp": 1588863680486
    },
    "protocols": ["IuYtREd0", "R2Jh6IhT"],
    "id": "9IHOifUF4",
    "env": "live",
    "isGateway": true,
    "name": "gateway",
    "type": "4023bd5d-9f88-4761-97c2-0e682aef5437"
  } 
}

disconnected

This event is sent when a gateway disconnects from the Instathings Cloud.

The response payload contains the gateway device information.

{
    "action": "disconnected",
    "payload": {
        "projectId": "ZLS75DhL",
        "ts": 1588581909753,
        "stats": {
            "dt_ingestion_notify": 1588693909492,
            "ingestion": 2373
        },
        "version": {
            "gate": "instathings/gate:1.7.1"
        },
        "certificateId": "0e8833aadad2ed060965b102ef40fc44c647c1bec9f5a51056beddab0efac57e",
        "status": {
            "disconnectReason": "CONNECTION_LOST",
            "principalIdentifier": "0e8833aadad2ed060965b102ef40fc44c647c1bec9f5a51056beddab0efac57e",
            "clientId": "3tjVYgQTw",
            "clientInitiatedDisconnect": false,
            "eventType": "disconnected",
            "sessionIdentifier": "4d45c44c-9572-4be7-b467-3701be717eae",
            "versionNumber": 0,
            "timestamp": 1588924123011
        },
        "plan": {
            "interval_count": 1,
            "amount": 600,
            "metadata": {
                "ingestion_limit": "5"
            },
            "product": "prod_GxpMPerafMhwEP",
            "tiers": null,
            "livemode": false,
            "created": 1584983290,
            "amount_decimal": "600",
            "transform_usage": null,
            "active": true,
            "aggregate_usage": null,
            "billing_scheme": "per_unit",
            "trial_period_days": 14,
            "tiers_mode": null,
            "usage_type": "licensed",
            "nickname": "Monthly",
            "currency": "usd",
            "interval": "month",
            "id": "plan_GxpPxBtYRJZ3W8",
            "object": "plan"
        },
        "protocols": ["IuYtREd0", "R2Jh6IhT", "knx"],
        "env": "live",
        "isGateway": true,
        "name": "gateway",
        "subDevices": ["YZOa21Loa"],
        "id": "3tjVYgQTw",
        "type": "4023bd5d-9f88-4761-97c2-0e682aef5437"
    }
}

installation_succeded

This event is sent when the installation of a new protocol succeded.

The response payload contains information about the installed protocol.

{
    "action": "installation_succeded",
    "payload": {
        "event": {
            "dt_install": 1588925322244,
            "protocol": "knx",
            "protocolId": "knx",
            "exitStatus": 0,
            "installationSuccess": true,
            "stdout": "4dd94eb26fcfc8b7eea6567c0a26965caf18978fccbc8612f5a0857c592c4338\n1.0.1: Pulling from instathings/knx2mqtt\nDigest: sha256:5a9ebffa1b1b000f22876758ed8bcebf9000d4838eb92df986b4892ce7d0670f\nStatus: Image is up to date for instathings/knx2mqtt:1.0.1\ndocker.io/instathings/knx2mqtt:1.0.1\n2469e618d57951b8478de3728952f7f62f9c9075177625609261ddbd928934a8\n",
            "stderr": "",
            "versions": {
                "instathings-knx2mqtt": "instathings/knx2mqtt:1.0.1",
                "eclipse-mosquitto": "eclipse-mosquitto:1.6.9",
                "gate": "instathings/gate:1.7.1"
            },
            "newContainers": ["instathings-knx2mqtt", "eclipse-mosquitto"],
            "projectId": "ZLS75DhL",
            "deviceId": "3tjVYgQTw"
        }
    }
}

installation_failed

This event is sent when the installation of a new protocol fails.

The response payload contains information about failing reasons.

{
    "action": "installation_failed",
    "payload": {
        "event": {
            "dt_install": 1588930345554,
            "protocol": "automations",
            "protocolId": "vRy7GTde",
            "exitStatus": 1,
            "installationSuccess": false,
            "stdout": "",
            "stderr": "",
            "versions": {
                "gate": "instathings/gate:1.7.1"
            },
            "newContainers": [],
            "projectId": "ZLS75DhL",
            "deviceId": "3tjVYgQTw"
        }
    }
}

discovering

This event is sent when the gateway is looking for new devices to pair.

The response payload contains the device information.

{
    "action": "discovering",
    "payload": {
        "projectId": "ZLS75DhL",
        "ts": 1588926931047,
        "status": {
            "eventType": "discovering"
        },
        "parentDevice": "3tjVYgQTw",
        "id": "ULfDD5dO4",
        "env": "live",
        "isGateway": false,
        "name": "sensor",
        "type": "01c2fd9f-fb3a-45cf-8be3-97e00b7510c6"
    }
}

paired

This event is sent when a new device has been successfully paired to the gateway.

The response payload contains the device information.

{
    "action": "paired",
    "payload": {
        "projectId": "ZLS75DhL",
        "ts": 1588925713401,
        "status": {
            "eventType": "paired"
        },
        "parentDevice": "3tjVYgQTw",
        "id": "f0xqzIBCt",
        "env": "live",
        "isGateway": false,
        "name": "sensor",
        "type": "01c2fd9f-fb3a-45cf-8be3-97e00b7510c6"
    }
}

not_paired

This event is sent when the pairing procedure of a new device has not succeded or when the device has been unpaired.

The response payload contains the device information.

{
    "action": "not_paired",
    "payload": {
        "projectId": "ZLS75DhL",
        "ts": 1588925713401,
        "status": {
            "eventType": "not_paired"
        },
        "parentDevice": "3tjVYgQTw",
        "id": "f0xqzIBCt",
        "env": "live",
        "isGateway": false,
        "name": "sensor",
        "type": "01c2fd9f-fb3a-45cf-8be3-97e00b7510c6"
    }
}

software_version

This event is sent every time the gateway connects to the Instathings Cloud.

The response payload contains the gateway device information.

{
    "action": "software_version",
    "payload": {
        "projectId": "JtjYANUvs",
        "ts": 1588863421916,
        "stats": {
            "ingestion": 0
        },
        "version": {
            "gate": "instathings/gate:1.7.1"
        },
        "certificateId": "e011d176b499c44e54fcd02143c9bfbf7c866ce7b2c4a2f2e58a21b658697aee",
        "status": {
            "principalIdentifier": "e011d176b499c44e54fcd02143c9bfbf7c866ce7b2c4a2f2e58a21b658697aee",
            "clientId": "9IHOifUF4",
            "ipAddress": "84.220.143.221",
            "eventType": "connected",
            "sessionIdentifier": "2451fb42-e516-4c0e-9668-c160d199007f",
            "versionNumber": 0,
            "timestamp": 1588863680486
        },
        "protocols": ["IuYtREd0", "R2Jh6IhT"],
        "env": "live",
        "isGateway": true,
        "name": "gateway",
        "subDevices": [],
        "id": "9IHOifUF4",
        "type": "4023bd5d-9f88-4761-97c2-0e682aef5437"
    }
}

data

This event is sent every time the Instathings Cloud receives a new data from one of your devices.

{
    "action": "data",
    "payload": {
        "id": "7dec7c01-949c-4615-9d09-7680e702080e",
        "clientId": "3tjVYgQTw",
        "principal": "0e8833aadad2ed060965b102ef40fc44c647c1bec9f5a51056beddab0efac57e",
        "ts": 1588925769193,
        "ttl": 1904285769,
        "deviceId": "f0xqzIBCt",
        "data": {
            "data": 81
        }
    }
}

status

This event is sent every time a device replies to the Get device status by id endpoint. 

{
    "action": "status",
    "payload": {
        "projectId": "JtjYANUvs",
        "response": {
            "type": "data",
            "message": {
                "data": {
                    "overtemperature": false,
                    "temperature": 37.35,
                    "fs_size": 233681,
                    "time": "16:54",
                    "fs_free": 168923
                }
            }
        },
        "ttl": 1589640897,
        "deviceId": "0_Rs0iIRW",
        "id": "B9z87nrYo"
    }
}

log

This event is sent every 5s if any of the software installed on your gateway generates a log.

The response payload contains an array of logs generated during the last 5s.

{
    "action": "log",
    "payload": {
        "logs": [{
                "message": "2020-05-07T15:01:20.563Z gate:log Connecting...",
                "type": "LOG",
                "timestamp": 1588863680585
            },
            {
                "message": "2020-05-07T15:01:20.566Z gate:log Subscribing to discover/JtjYANUvs/9IHOifUF4/device/post",
                "type": "LOG",
                "timestamp": 1588863680585
            },
        ],
        "deviceId": "9IHOifUF4",
        "containerName": "gate"
    }
}

shelly:on_status_change

This event is sent every time Instathings receives the event on_status_change from a Shelly device onboarded from the Shelly Integrator panel.

The Shelly device needs to be known on Instathings otherwise the Shelly Integrator panel will fail.

Data sent on the websocket varies based on the device type (Shelly names this deviceCode).

Shelly 3EM

Reference data sent from Shelly 3EM device (deviceCode: SHEM-3) 

{
    "action": "shelly:on_status_change",
    "payload": {
        "event": "Shelly:StatusOnChange",
        "deviceId": "decimalShellyDeviceId",
        "status": {
            "wifi_sta": {
                "connected": true,
                "ssid": "wifi-network",
                "ip": "192.168.1.1",
                "rssi": -38
            },
            "cloud": {
                "enabled": true,
                "connected": true
            },
            "mqtt": {
                "connected": false
            },
            "time": "00:01",
            "unixtime": 1683671234,
            "serial": 11111,
            "has_update": false,
            "mac": "FFFFFFFFFFFF",
            "cfg_changed_cnt": 0,
            "actions_stats": {
                "skipped": 0
            },
            "relays": [{
                "ison": false,
                "has_timer": false,
                "timer_started": 0,
                "timer_duration": 0,
                "timer_remaining": 0,
                "overpower": false,
                "is_valid": true,
                "source": "cloud"
            }],
            "emeters": [{
                "power": -1078.35,
                "pf": -1.08,
                "current": 3.96,
                "voltage": 243.92,
                "is_valid": true,
                "total": 137828.5,
                "total_returned": 1173710.1
            }, {
                "power": -1090.76,
                "pf": -1.08,
                "current": 4,
                "voltage": 245.08,
                "is_valid": true,
                "total": 57949.4,
                "total_returned": 1143685.9
            }, {
                "power": -1100.95,
                "pf": -1.08,
                "current": 4.04,
                "voltage": 245.54,
                "is_valid": true,
                "total": 132890.9,
                "total_returned": 1235307.4
            }],
            "total_power": -3270.06,
            "emeter_n": {
                "current": 0,
                "ixsum": 0.11,
                "mismatch": false,
                "is_valid": false
            },
            "fs_mounted": true,
            "v_data": 1,
            "ct_calst": 0,
            "update": {
                "status": "idle",
                "has_update": false,
                "new_version": "20230503-102100/v1.13.0-g9aed950",
                "old_version": "20230503-102100/v1.13.0-g9aed950"
            },
            "ram_total": 49920,
            "ram_free": 32752,
            "fs_size": 233681,
            "fs_free": 154616,
            "uptime": 55,
            "getinfo": {
                "fw_info": {
                    "device": "shellyem3-FFFFFFFFFFFF",
                    "fw": "20230503-102100/v1.13.0-g9aed950"
                }
            }
        }
    }
}

On-premise Websocket API

Real-time notifications are exposed via websocket even when you're working on-premise.

socket.io is used behind the scene, we suggest to use a socket.io client for maximum compatibility.

Here are listed the event types you can receive:

OP: Connect to websocket

wscat -c 'ws://localhost:1234/socket.io/?EIO=3&transport=websocket'

const io = require('socket.io-client');
const socket = io('http://localhost:1234');

socket.on('connect', function (socket) {
  console.log('Connected!');
});

The websocket connection url is your server base url.

For instance: http://localhost:1234

 OP: Message encoding

Each message sent and received via the websocket channel is encoded in JSON format.

OP: data

The data event is emitted every time a device send data to the Gateway.

By registering a listener on this event you will receive an event regardless of the deviceId.

The response message contains the information sent by the device

The data event returns a JSON like this:

 {
     "deviceId": "a1234",
     "payload": {
        "temperature": 30.82,
        },
   "ts" : "2020-05-20T12:19:44.395Z",
    }

OP: data_deviceId

The data_deviceId event is emitted every time a device send data to the Gateway.

By registering a listener on this event you will be notified only when the device with id equal to deviceId sent its data.

The response message contains the information sent by the device

The data_deviceId event returns a JSON like this:

 {
        "temperature": 30.82,
 }

OP: status

The status event is sent every time a device sends its status. A device sends its status when a response is received from a Get device status by id.

The response message contains the following keys: * deviceId: the id of the device * payload: the information sent by the device * ts: timestamp of the event

The status event returns a JSON like this:

{
  "payload": {
        "temperature": 30.82,
    },
  "deviceId": "9s9WdonY9",
  "ts" : "2020-05-20T12:19:44.395Z"
}

OP: status_deviceId

The event status_deviceId is sent every time a device sends its status. A device sends its status when a response is received from a Get device status by id.

If you register a listener on this event you will be notified only when the device with id equal to deviceId sent its status.

The response message contains the information sent by the device

The status_deviceId event returns a JSON like this:

 {
     "temperature": 30.82
 }

OP: deviceId

The deviceId event collects all the events related to a single device.

The response message contains the following keys:

The deviceId event returns a JSON like this:

{
    "action": "data",
    "payload": { "temperature": 20.4 },
    "ts" : "2020-05-20T12:19:44.395Z",
}

On-premise REST API

OP: Connection to HTTP web server

If the ON_PREMISE_ENABLED option is set to true a Web Server starts and you can send HTTP requests to its public API.

The base path of your server depends on the IP address of your gateway and the port the server is listening to

Example of base path for your server

http://localhost:1234

http://localhost:1234

OP: Get data for a specific device

curl "http://YourGatewayIpAddress:PORT/device/v1/devices/:deviceId/data?page=1&perPage=1&sort=-ts"

The above command returns JSON structured like this:

{
    "data": [{
        "_id": "5ec4ecdc11f6c352cf3f372e",
        "data": {
            "type": "data",
            "message": {
                "data": {
                    "relays": [{
                        "ison": false,
                        "has_timer": false,
                        "timer_remaining": 0,
                        "overpower": false
                    }],
                    "temperature": 30.82,
                    "overtemperature": false,
                    "ram_total": 50608,
                    "ram_free": 40304,
                    "fs_size": 233681,
                    "fs_free": 168923,
                    "uptime": 458
                }
            }
        },
        "deviceId": "9s9WdonY9",
        "ts": "2020-05-20T08:39:55.995Z"
    }],
    "totalItems": 14
}

This endpoint retrieves ingested data sent by a specific device.

GET /device/v1/devices/:deviceId/data

Path Parameters

Parameter Required
deviceId true

Query Parameters

Parameter Required Description
start false date in ms, starting point from which retrieve data
end false date in ms, data sent after this moment are not returned in the response
page false A cursor for use in pagination. Use it with perPage, first page is page 1.
perPage false A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
sort false value of the key you want to use to sort the results.\ You can specify it preceeded by + or -, based on the order you want to sort the results, ascending or descending.\By default results are sorted into time ascending order (default value: ts)
shell javascript