Query Devices

Query for devices in a number of ways using available filters.

Routes

Method	URI	Summary
GET	/v1.0/admin/things	Get list of all devices
GET	/v1.0/admin/things/count	Get count of all devices
GET	/v1.0/admin/things/{thing_id}	Get one device
GET	/v1.0/admin/things/{thing_id}/latest	Get latest readings
GET	/v1.0/admin/things/{thing_id}/readings	Get device readings by Thing Id and time frame
GET	/v1.0/admin/things/{hardware_id}/status	Get device by hardware Id
POST	/v1.0/admin/things	Create a device
POST	/v1.0/admin/things/{thing_id}/cmd	Send a command to a device
PUT	/v1.0/admin/things/{thing_id}	Update a device
DELETE	/v1.0/admin/things/{thing_id}	Delete a device

info

The parameter {thing_id} is in UUID format, e.g. 6df450e0-91f0-11ed-9d8f-f9c593f1db51 not the hardware id. See how to get thing_id from hardware_id below.

Find all Devices

Query Parameters

Name	Source	Type	Values
application_id	query	string
limit	query	number
page	query	number
location_id	query	number
status	query	number	0 Activated 1 Deactivated
user_id	query	string
thing_type	query	string	devices or gateways
external_id	query	string

Response Body

Name	Source	Type	Description
count	body	number	Total number of devices
limit	body	number	Number of devices returned per page
page	body	number	Current page of results
rows	body	array	Array of device objects

Device Object

Name	Source	Type	Description
id	Device	number	Internal Id
location_id	Device	number	Location Id
company_id	Device	number	Company Id
parent_id	Device	number	Parent Id
cayenne_id	Device	string	Device Id
hardware_id	Device	string	EUI or Hardware Id
sensor_use_id	Device	number	Sensor Use Id
sensor_use	Device	string	Sensor Use String
sensor_type	Device	string	Sensor Type
thing_name	Device	string	Device Name
thing_type	Device	number	Device Template
marker_alert	Device	string	Marker Alert
properties	Device	string	Properties
device_type_id	Device	string	Device Type/Template Id
enabled	Device	number	Enabled
user_id	Device	string	User Id
application_id	Device	string	Application Id
status	Device	number	0 Activated 1 Deactivated
created_at	Device	string	Created At
updated_at	Device	string	Updated At

Get single device by Hardware id

Note we are passing hardware_id and status. If status parameter is not include, it will return previous deactivated devices as well. Here we use the id as thing_id in other requests.

```shell
curl --request GET --url https://api.iotinabox.com/v1.0/admin/things?hardware_id=abcde123456?status=0 \
--header 'authorization: Bearer MyAuthTokenHere' \
--header 'content-type: application/json'

Get devices for an User

Example call to query devices for a user (e.g. one of our two users pulled in the previous example). In this case we'll query against robcan...@yopmail.com, user 99e86f3f-87f4-4d7e-9e87-529e16f27438:

Note how we filter by a specific user_id.

curl --request GET --url https://api.iotinabox.com/v1.0/admin/things?page=0&limit=50&user_id=99e86f3f-87f4-4d7e-9e87-529e16f27438 \
--header 'authorization: Bearer MyAuthTokenHere' \
--header 'content-type: application/json'

Example Response (robcan...@yopmail.com's devices):

{
  "count": 2,
  "limit": 50,
  "page": 0,
  "rows": [
    {
      "id": "75722a70-711c-11e9-9fd4-e73c33d2d42c",
      "sensor_type": null,
      "created_at": "2019-05-07T23:04:25.000Z",
      "sensor_use": null,
      "thing_type": 0,
      "thing_name": "Gateway",
      "properties": "{\"codec\":\"lorawan.gateway.iotb\"}",
      "company_id": 937,
      "hardware_id": "eui-00001c497bb44...",
      "device_type_id": "36c52526-e689-11e7-80c1-9a214cf093ce",
      "application_id": "iot-solutions-canada",
      "sensor_use_id": null,
      "location_id": 890,
      "id": 70006075,
      "enabled": 1,
      "status": 0,
      "user_id": "99e86f3f-87f4-4d7e-9e87-529e16f27438",
      "parent_id": null,
      "updated_at": "2019-05-07T23:04:25.000Z",
      "cayenne_id": "75722a70-711c-11e9-9fd4-e73c33d2d42c"
    },
    {
      "id": "815f4c00-711c-11e9-9fd4-e73c33d2d42c",
      "company_id": 937,
      "hardware_id": "00137a1000000...",
      "device_type_id": "121f6268-e52b-11e7-80c1-9a214cf093ae",
      "sensor_type": "Open/Close",
      "created_at": "2019-05-07T23:04:45.000Z",
      "thing_type": 1,
      "sensor_use": "Door",
      "thing_name": "OCRPP",
      "properties": "{}",
      "application_id": "iot-solutions-canada",
      "id": 70006076,
      "enabled": 1,
      "sensor_use_id": null,
      "location_id": 890,
      "cayenne_id": "815f4c00-711c-11e9-9fd4-e73c33d2d42c",
      "updated_at": "2019-05-09T17:00:11.000Z",
      "user_id": "99e86f3f-87f4-4d7e-9e87-529e16f27438",
      "status": 1,
      "parent_id": null
    }
  ]
}

Get Latest Readings

GET - /v1.0/admin/things/{thing_id}/latest

This endpoint will return the latest device sensor readings. In order to properly parse the readings array, you must know the channel mapping for the device. This can be found by querying the /v1.0/things/types/{device_type_id} endpoint.

Example Response

[
    {
        "ts": 1701362627000,
        "type": "value",
        "channel": "100",
        "name": "Voltage",
        "thing_id": "1234567-a248-11ed-a734-c705cd0fd51c",
        "event": "uplink",
        "v": 4028
    },
    {
        "ts": 1701362627000,
        "type": "value",
        "channel": "123",
        "name": "Temp",
        "thing_id": "1234567-a248-11ed-a734-c705cd0fd51c",
        "event": "uplink",
        "v": 4595
    },
    ... // truncated

Get Device Readings

GET - /v1.0/admin/things/{thing_id}/readings

This endpoint will return device sensor readings by providing a start and end unix timestamp in milliseconds. The readings are returned in descending order by timestamp. In order to properly parse the readings array, you must know the channel mapping for the device. This can be found by querying the /v1.0/things/types/{device_type_id} endpoint. See the example below.

Query Parameters

Name	Source	Type	Description
start_ts	query	number	Start timestamp in milliseconds
end_ts	query	number	End timestamp in milliseconds
limit	query	number	(optional) Limit numner of returned readings
cursor	query	string	(optional) String value to paginate readings
units	query	string	(optional) String value for units

Response Body

Name	Source	Type	Description
count_took	body	number	Time to process query
took	body	number	Time to process query
transfer	body	number	number of bytes transferred
units	body	array	Array of sensor units
readings	body	array	Array of readings
timestamp	body	string	If present, this value will be set to cursor to get next more readings

The readings array contains objects with the following properties:

Name	Source	Type	Description
ts	body	number	Timestamp of reading
correlation_id	body	string	Event correlation id of the device reading
sensors	body	array	Actual readings are returned in this array { "v": 0, "channel": "10" }

  {
    "ts": 1687650221820,
    "correlation_id": "24856f3a-404f-4b94-adab-72e8a5fc8db9",
    "sensors": [
      {
        "v": 0,
        "channel": "10"
      },
      {
        "v": -64,
        "channel": "100"
      },
      {
        "v": 100,
        "channel": "5"
      }
    ]
  }

Each object will contain an array of sensor values at the set interval. This indicate that at the given timestamp, the sensor values were as follows:

• channel 10: 0
• channel 100: -64
• channel 5: 100

To get a channel mapping for a device, use the /v1.0/things/types/{device_type_id} endpoint. https://iotinabox-api.mydevices.com/v1.0/things/types/{device_type_id} The returned payload from this Device Types endpoint will contain a channels array describing the channel mapping for the device. For example:

"channels": [
    {
      "data": null,
      "id": 70,
      "name": "battery",
      "datatype": "BATTERY",
      "data_types_id": 11,
      "channel": "5",
      "ipso": null,
      "order": 1,
      "device_type_id": "121f6268-e52b-11e7-80c1-9a214cf093ae"
    },
    {
      "data": null,
      "id": 71,
      "name": "motion",
      "datatype": "INTRUSION",
      "data_types_id": 39,
      "channel": "10",
      "ipso": null,
      "order": 1,
      "device_type_id": "121f6268-e52b-11e7-80c1-9a214cf093ae"
    },
    {
      "data": null,
      "id": 79,
      "name": "signal",
      "datatype": "RSSI",
      "data_types_id": 8,
      "channel": "100",
      "ipso": null,
      "order": 1,
      "device_type_id": "121f6268-e52b-11e7-80c1-9a214cf093ae"
    }
  ],

Putting it all together, we can see that the above example reading:

timestamp	channel	type	value
1687650221820	10	motion	0
1687650221820	100	signal	-65
1687650221820	5	battery	100

Entire Example Response

{
    "count_took": 2,
    "took": 70,
    "transfer": 986,
    "units": [
        {
            "sensor_id": "47b6a550-cf57-11ed-aaaa-292d59ac7b6c",
            "channel": "5",
            "from": "p"
        },
        {
            "sensor_id": "47b65730-cf57-11ed-aaaa-292d59ac7b6c",
            "channel": "10",
            "from": "d"
        },
        {
            "sensor_id": "47b67e40-cf57-11ed-aaaa-292d59ac7b6c",
            "channel": "100",
            "from": "dbm"
        }
    ],
    "readings": [
        {
            "ts": 1687650221820,
            "correlation_id": "24856f3a-404f-4b94-adab-72e8a5fc8db9",
            "sensors": [
                {
                    "v": 0,
                    "channel": "10"
                },
                {
                    "v": -64,
                    "channel": "100"
                },
                {
                    "v": 100,
                    "channel": "5"
                }
            ]
        },
        {
            "ts": 1687643022290,
            "correlation_id": "8ea092b2-7320-448f-bce4-3f094ca16605",
            "sensors": [
                {
                    "v": 0,
                    "channel": "10"
                },
                {
                    "v": -66,
                    "channel": "100"
                },
                {
                    "v": 100,
                    "channel": "5"
                }
            ]
        }
    ]
}

Example Requeust

curl --request GET --url https://api.iotinabox.com/v1.0/admin/things/thing_id/readings?start_ts=0&end_ts=0&units=f,p,dbm \
--header 'authorization: Bearer MyAuthTokenHere' \
--header 'content-type: application/json'

Create a Device

Create a Device

curl --request POST --url https://api.iotinabox.com/v1.0/admin/things \
--header 'authorization: Bearer MyAuthTokenHere' \
--header 'content-type: application/json'
--data \
'{
    "user_id": "0dfb9c58-5a0b-40eb-9e8c-36c0b1ff883b",
    "application_id": "iotinabox",
    "company_id": 464,
    "location_id": 445,
    "device": {
        "hardware_id": "a130000000000ff",
        "name": "thing_name_5",
        "sensor_use": "use5",
        "sensor_type": "Ethernet Gateway",
        "device_category": "module",
        "external_id": "my_external_id_4"
    }
}'

Example Response:

{
  "id": 1405,
  "location_id": 445,
  "company_id": 464,
  "parent_id": null,
  "cayenne_id": "d3fd3d80-6446-11ec-a762-a52e6bb2c8ed",
  "hardware_id": "a130000000000ff",
  "sensor_use_id": null,
  "sensor_use": "use6",
  "sensor_type": "Ethernet Gateway",
  "thing_name": "thing_name_5",
  "thing_type": 1,
  "marker_alert": "animate",
  "properties": "{\"codec\":\"lorawan.gateway.iotb\",\"deveui\":\"a130000000000ff\",\"network\":\"iotinabox\",\"activation\":\"activated\",\"device_registry_id\":\"4b918ff0-641e-11ec-a762-a52e6bb2c8ed\",\"codec.vol_unit\":\"m3\",\"codec.prox_unit\":\"m\"}",
  "device_type_id": "1e563f10-cc0d-11e8-9c69-e9c14d851ba4",
  "enabled": 1,
  "user_id": "0dfb9c58-5a0b-40eb-9e8c-36c0b1ff883b",
  "application_id": "iotinabox",
  "status": 0,
  "created_at": "2021-12-23T23:19:53.000Z",
  "updated_at": "2022-01-03T17:27:41.000Z",
  "external_id": "my_external_id_4",
  "createdAt": "2021-12-23T23:19:53.000Z",
  "updatedAt": "2022-01-03T17:27:41.000Z"
}

Update Device

Update a Device

curl --request PUT --url https://api.iotinabox.com/v1.0/admin/things/d3fd3d80-6446-11ec-a762-a52e6bb2c8ed \
--header 'authorization: Bearer MyAuthTokenHere' \
--header 'content-type: application/json'
--data \
'{
    "user_id": "0dfb9c58-5a0b-40eb-9e8c-36c0b1ff883b",
    "application_id": "iotinabox",
    "sensor_use": "use6",
    "name": "thing_name_6",
    "external_id": "my_external_id_5",
    "company_id": 464,
    "location_id": 445
}'

Example Response:

{
  "id": 1405,
  "location_id": 445,
  "company_id": 464,
  "parent_id": null,
  "cayenne_id": "d3fd3d80-6446-11ec-a762-a52e6bb2c8ed",
  "hardware_id": "a130000000000ff",
  "sensor_use_id": null,
  "sensor_use": "use6",
  "sensor_type": "Ethernet Gateway",
  "thing_name": "thing_name_6",
  "thing_type": 1,
  "marker_alert": "animate",
  "properties": "{\"codec\":\"lorawan.gateway.iotb\",\"deveui\":\"a130000000000ff\",\"network\":\"iotinabox\",\"activation\":\"activated\",\"device_registry_id\":\"4b918ff0-641e-11ec-a762-a52e6bb2c8ed\",\"codec.vol_unit\":\"m3\",\"codec.prox_unit\":\"m\"}",
  "device_type_id": "1e563f10-cc0d-11e8-9c69-e9c14d851ba4",
  "enabled": 1,
  "user_id": "0dfb9c58-5a0b-40eb-9e8c-36c0b1ff883b",
  "application_id": "iotinabox",
  "status": 0,
  "created_at": "2021-12-23T23:19:53.000Z",
  "updated_at": "2022-01-03T17:27:41.000Z",
  "external_id": "my_external_id_5",
  "createdAt": "2021-12-23T23:19:53.000Z",
  "updatedAt": "2022-01-03T17:27:41.000Z"
}

Remove Device

Delete a Device

curl --request DELETE --url https://api.iotinabox.com/v1.0/admin/things/d3fd3d80-6446-11ec-a762-a52e6bb2c8ed \
--header 'authorization: Bearer MyAuthTokenHere' \
--header 'content-type: application/json'
--data \
'{
    "user_id": "0dfb9c58-5a0b-40eb-9e8c-36c0b1ff883b"
}'

Example Response:

{
  "success": true
}

Get Device by External Id

Get a Device by External Id

curl -- request GET \
-- url https://api.iotinabox.com/v1.0/admin/things?external_id=1234 \
-- header 'Authorization: Bearer YourAuthToken' \
-- header 'Content-Type: application/json'

Send Device Command

Send Device Commands

curl --request POST \
  --url http://api.iotinabox.com/v1.0/admin/things/6df450e0-91f0-11ed-9d8f-f9c593f1db51/cmd \
  --header 'Authorization: Bearer >>your token here<<' \
  --header 'Content-Type: application/json' \
  --data '{
        "channel": "57",
        "value": 1
}'

In the above example the channel must be one of the device capabilities found under device templates. The value depends on the type of capability. Here we have a stop alert downlink and the value must be equal to 1.

Get device information

GET - /v1.0/admin/things/{thing_id}

This request returns the information about a device. Optionally, the include query parameter can be used to include the alert field, the readings and the sensor details, i.e., ?include=alert,state,sensors.

Example Request

curl --request GET \
  --url http://api.iotinabox.com/v1.0/admin/things/4793db10-cf57-11ed-aaaa-292d59ac7b6c?include=alert,state,sensors \
  --header 'Authorization: Bearer >>your token here<<' \
  --header 'Content-Type: application/json'

Example Response

  "id": 70170389,
  "location_id": 6648,
  "company_id": 4130,
  "parent_id": null,
  "cayenne_id": "4793db10-cf57-11ed-aaaa-292d59ac7b6c",
  "hardware_id": "00137a1000000f1f",
  "sensor_use_id": null,
  "sensor_use": "Door",
  "sensor_type": "Open/Close",
  "thing_name": "Door2",
  "thing_type": 1,
  "marker_alert": "animate",
  "properties": "{\"codec\":\"lorawan.netvox.door\",\"deveui\":\"00137a1000000f1f\",\"network\":\"iotinabox\",\"activation\":\"activated\",\"device_registry_id\":\"98f0d298-8092-11e8-85a1-3fab6fd5f783\",\"marker_type\":\"pin\",\"marker_style\":\"style1\",\"marker_channels\":[],\"codec.vol_unit\":\"m3\",\"codec.prox_unit\":\"m\",\"url\":\"https://v2.app.staging.mydevices.com/v2/h/3PRK\",\"use_url\":true,\"public\":true,\"dashboard_url\":\"https://v2.app.staging.mydevices.com/v2/s/3IycHrLNuD6dDG4de7YIT5yKbUauHAn5q3ks4xTo-LGCFFRAKviY9mRDaNdXWt83KfvnoSl28oy9XHfOAAg7vQ/d/d7285582-a342-430b-8a91-3e7d96ec9257\"}",
  "device_type_id": "121f6268-e52b-11e7-80c1-9a214cf093ae",
  "enabled": 1,
  "user_id": "5a86666b-3af2-47ac-9a4e-ac5965d24bdf",
  "application_id": "iotinabox",
  "status": 0,
  "created_at": "2023-03-31T00:02:09.000Z",
  "updated_at": "2023-10-05T17:35:47.000Z",
  "external_id": null,
  "createdAt": "2023-03-31T00:02:09.000Z",
  "updatedAt": "2023-10-05T17:35:47.000Z",
  "alert": 0,
  "state": [
    {
      "thing_id": "4793db10-cf57-11ed-aaaa-292d59ac7b6c",
      "sensors": [
        {
          "ts": 1713454182740,
          "type": "batt",
          "channel": "5",
          "sensor_id": "47b6a550-cf57-11ed-aaaa-292d59ac7b6c",
          "name": "Battery",
          "thing_id": "4793db10-cf57-11ed-aaaa-292d59ac7b6c",
          "cached": true,
          "event": "uplink",
          "v": 100,
          "unit": "p"
        },
        {
          "ts": 1713454182740,
          "type": "digital_sensor",
          "channel": "10",
          "sensor_id": "47b65730-cf57-11ed-aaaa-292d59ac7b6c",
          "name": "Contact Switch",
          "thing_id": "4793db10-cf57-11ed-aaaa-292d59ac7b6c",
          "cached": true,
          "event": "uplink",
          "v": 0,
          "unit": "d"
        },
        {
          "ts": 1713454182740,
          "type": "rssi",
          "channel": "100",
          "sensor_id": "47b67e40-cf57-11ed-aaaa-292d59ac7b6c",
          "name": "RSSI",
          "thing_id": "4793db10-cf57-11ed-aaaa-292d59ac7b6c",
          "cached": true,
          "event": "uplink",
          "v": -73,
          "unit": "dbm"
        },
        {
          "ts": 1713454182740,
          "type": "snr",
          "channel": "101",
          "name": "SNR",
          "thing_id": "4793db10-cf57-11ed-aaaa-292d59ac7b6c",
          "cached": true,
          "event": "uplink",
          "v": 11.8
        }
      ]
    }
  ],
  "sensors": [
    {
      "enabled": 1,
      "sensor_id": "47b65730-cf57-11ed-aaaa-292d59ac7b6c",
      "properties": {
        "channel": 10
      }
    },
    {
      "enabled": 1,
      "sensor_id": "47b6a550-cf57-11ed-aaaa-292d59ac7b6c",
      "properties": {
        "channel": 5
      }
    },
    {
      "enabled": 1,
      "sensor_id": "47b67e40-cf57-11ed-aaaa-292d59ac7b6c",
      "properties": {
        "channel": 100
      }
    }
  ]
}```