Skip to main content

Query Devices

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

Routes

MethodURISummary
GET/v1.0/admin/thingsGet list of all devices
GET/v1.0/admin/things/countGet count of all devices
GET/v1.0/admin/things/{thing_id}Get one device
GET/v1.0/admin/things/{thing_id}/latestGet latest readings
GET/v1.0/admin/things/{thing_id}/readingsGet device readings by Thing Id and time frame
GET/v1.0/admin/things/{hardware_id}/statusGet device by hardware Id
POST/v1.0/admin/thingsCreate a device
POST/v1.0/admin/things/{thing_id}/cmdSend 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
PUT/v1.1/organizations/{organization_id}/applications/{application_id}/locations/{location_id}/things/moveMove devices to another location

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

NameSourceTypeValues
application_idquerystring
limitquerynumber
pagequerynumberpage number starts from 0
location_idquerynumber
statusquerynumber0 Activated 1 Deactivated
user_idquerystring
thing_typequerystringdevices or gateways
external_idquerystring

Response Body

NameSourceTypeDescription
countbodynumberTotal number of devices
limitbodynumberNumber of devices returned per page
pagebodynumberCurrent page of results
rowsbodyarrayArray of device objects

Device Object

NameSourceTypeDescription
idDevicenumberInternal Id
location_idDevicenumberLocation Id
company_idDevicenumberCompany Id
parent_idDevicenumberParent Id
cayenne_idDevicestringDevice Id
hardware_idDevicestringEUI or Hardware Id
sensor_use_idDevicenumberSensor Use Id
sensor_useDevicestringSensor Use String
sensor_typeDevicestringSensor Type
thing_nameDevicestringDevice Name
thing_typeDevicenumberDevice Template
marker_alertDevicestringMarker Alert
propertiesDevicestringProperties
device_type_idDevicestringDevice Type/Template Id
enabledDevicenumberEnabled
user_idDevicestringUser Id
application_idDevicestringApplication Id
statusDevicenumber0 Activated 1 Deactivated
created_atDevicestringCreated At
updated_atDevicestringUpdated 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.mydevices.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:

alt text Note how we filter by a specific user_id.

curl --request GET --url https://api.mydevices.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

NameSourceTypeDescription
start_tsquerynumberStart timestamp in milliseconds
end_tsquerynumberEnd timestamp in milliseconds
limitquerynumber(optional) Limit numner of returned readings
cursorquerystring(optional) String value to paginate readings
unitsquerystring(optional) String value for units

Response Body

NameSourceTypeDescription
count_tookbodynumberTime to process query
tookbodynumberTime to process query
transferbodynumbernumber of bytes transferred
unitsbodyarrayArray of sensor units
readingsbodyarrayArray of readings
timestampbodystringIf present, this value will be set to cursor to get next more readings

The readings array contains objects with the following properties:

NameSourceTypeDescription
tsbodynumberTimestamp of reading
correlation_idbodystringEvent correlation id of the device reading
sensorsbodyarrayActual 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://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:

timestampchanneltypevalue
168765022182010motion0
1687650221820100signal-65
16876502218205battery100

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.mydevices.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.mydevices.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.mydevices.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.mydevices.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.mydevices.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.mydevices.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.mydevices.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
}
}
]
}

Move devices to another location

Example Request

curl --request PUT
--url https://api.mydevices.com/v1.1/organizations/{organization_id}/applications/{application_id}/locations/{location_id}/things/move
--header 'authorization: Bearer YourAuthToken'
--data '{"to_location_id": 10116, "device_ids": ["74258810-8562-11ee-9e77-c5a9b0faa4fc","11121090-c531-11ee-a181-29008449e9a8"]}'

Example Response

{
"success": true
}