✨ Improvements
There's a limit to the size of a response from our API, so to avoid breaking that limit, we've added pagination to the /devices endpoint.
The limit to number of devices returned from the request can be defined by using the limit parameter, with a maximum of 5 000 devices per page. If the parameter is not set, and there are more than 5 000 devices in the account, the API will provide a 400 Bad Request response and let you know that pagination should be used for the request.
The response from the /devices endpoint with pagination enabled will return the offset used to retrieve the next page, as well as the total amount of devices in the account.
Example response from GET /devices?limit=1&offset=50 :
{
"devices": [
{
"id": "2930000000",
"deviceType": "WAVE_PLUS",
"sensors": [
"radonShortTermAvg",
"temp",
"humidity",
"pressure",
"co2",
"voc",
"light",
"virusRisk"
],
"segment": {
"id": "00000000-0000-0000-0000-0000000000",
"name": "Device Name",
"started": "2021-07-09T14:00:06",
"active": true
},
"location": {
"id": "00000000-0000-0000-0000-0000000000",
"name": "Location Name"
}
}
],
"limit": 1,
"offset": 51,
"total": 554
}✨ Improvements
The response from the /devices and /segments endpoints can be used to identify when devices have been added or removed from accounts, but for accounts with a lot of registered devices, the response from these endpoints can become quite large. Parameters have been added to both these endpoints to help reduce the size of the response in case they are being used for this purpose.
segmentStartedAfter has been added as a parameter to the /devices and /segments endpoints, and will return all devices/segments registered/started after the specified time.
segmentEndedAfter has been added as a parameter to the /segment endpoint, and will return all segments ended after the specified time.
🚀 Feature release
Released the MQTT service as an integration option to complement our already existing RESTful API and Webhooks. Head over to the MQTT documentation to learn how you can get started setting up your MQTT client and subscribe to Airthings data.
✨ Improvements
Get location endpoint now returns more information.
GET /locations/{locationId}{
"id": "00000000-0000-0000-0000-0000000000",
"name": "Office",
"labels": {},
"devices": [
{
"id": "2920000000",
"deviceType": "WAVE_MINI",
"segment": {
"id": "00000000-0000-0000-0000-0000000000",
"name": "Mini",
"started": "2019-03-13T13:37:37",
"active": true
}
},
{
"id": "2920001111",
"deviceType": "WAVE_MINI",
"segment": {
"id": "00000000-0000-0000-0000-0000000001",
"name": "Mini reception",
"started": "2019-03-13T13:37:37",
"active": true
}
},
{
"id": "2820002222",
"deviceType": "HUB",
"segment": {
"id": "00000000-0000-0000-0000-0000000002",
"name": "TestHub",
"started": "2021-12-07T12:43:41",
"active": true
}
}
],
"address": "Oslo, Norway",
"countryCode": "NO",
"lat": 59.913868,
"lng": 10.752245,
"buildingType": "Office",
"buildingYear": 2000,
"ventilationType": "Balanced",
"timezone": "Europe/Oslo",
"usageHours": {
"friday": {
"closed": false,
"from": "07:00",
"to": "17:00"
},
"monday": {
"closed": false,
"from": "07:00",
"to": "17:00"
},
"saturday": {
"closed": true
},
"sunday": {
"closed": true
},
"thursday": {
"closed": false,
"from": "08:00",
"to": "17:00"
},
"tuesday": {
"closed": false,
"from": "07:00",
"to": "17:00"
},
"wednesday": {
"closed": false,
"from": "07:00",
"to": "20:00"
}
},
"buildingHeight": 5.0,
"buildingSize": 190.0,
"buildingVolume": 907986.0,
"floors": 2
}✨ Improvements
As part of our goal to deliver a better experience for API clients, sensorUnits is now available alongside measurementSystem in our Webhook endpoints.
Please note that we will start the process of adding sensorUnits to all endpoints that are currently using measurementSystem, and will start removing measurementSystem from our API endpoints shortly after. We will notify you before the removal process take place.
🚀 Feature Release
Locations included in a webhook can now be updated using the API. This new endpoint requires the access scope write:device.
The endpoint is created using the PATCH method, applying the concept from this RFC allowing the user to perform multiple operations on a resource.
The endpoint at this stage only takes the locations path.
Note that we do not allow adding an empty location to the webhook, therefore, a device must be added to a location before it can be added to the webhook.
To edit locations on a webhook, use the following endpoint with the example request body:
PATCH /webhooks/{webhookId}?organizationId={organizationId}{
"operations": [
// Add location to a webhook
{
"op": "ADD",
"path": "locations",
"value": [
"69cbabbf-74a3-47c9-8c23-0ec8b59e886b",
"1ddc4b5a-ca8c-4ac3-93a4-e7c6d418549c",
"0f6f41fb-42a1-4aaa-8337-fb642176e136",
"8e40dff9-98c3-4bf4-9aa8-dfe76c2652c6"
]
},
// Remove certain locations from a webhook
{
"op": "REMOVE",
"path": "locations",
"value": [
"337d2956-8ba4-45c1-9ae1-50a2a1a46f69",
"580c4513-20e4-4d4e-b842-79aa5c053442"
]
},
// Remove all locations from a webhook
{
"op": "REMOVE",
"path": "locations"
}
]
}