Airthings for Business

What you can build

• Hold CO2 under your target in each room

  co2 samples per segment show which rooms climb through the afternoon. The operator proposes a ventilation change and records the reading before and after.

  With CO2 Ventilation

• Answer a stuffy-room complaint with data

  When a complaint names a room, the operator pulls that segment's latest temp, humidity, co2, and voc, and proposes a reply and a work order if a value is outside the range you set.

  With Comfort Complaint

• Watch radon where people sit all day

  hourlyRadon and radonShortTermAvg arrive by webhook. The operator proposes a notice to facilities when a location stays above your threshold for the period you choose.

  With Indoor Air

• Keep hubs and monitors reporting

  hub-meta-data-feed events list lastSeenDevices and rssi per hub. The operator proposes a site visit for any monitor a hub has stopped seeing.

  With Sensor Health

Requirements

• An Airthings for Business subscription; consumer accounts get a limited read-only consumer API
• An API client registered under Dashboard > Integrations > API integration
• The Account ID and Location IDs you want to read, both shown in the Dashboard
• For webhooks, an HTTPS endpoint; for the MQTT Publisher, a broker reachable from the Airthings cloud with username and password or certificates

Authentication

An OAuth 2.0 client credentials grant at https://accounts-api.airthings.com/v1/token with a client ID and secret created in the Airthings for Business Dashboard, requesting the read:device and write:device scopes.

Limits

• 5 000 requests per hour per API client, and 2 000 requests per 5 minutes per IP address; the IP limit cannot be raised
• Webhooks are fire and forget with no retry, so a missed delivery is filled in by a periodic API call
• At most 10 MQTT Publisher configurations per organization
• Devices typically report every 5 minutes, which sets the floor for how fresh a sample can be

Questions and answers

Which is better for near-real-time data, the API or webhooks?

Airthings recommends webhooks or the MQTT Publisher for immediate delivery, then a periodic API call to fill gaps, since webhooks are fire and forget with no retry. Polling individual devices counts against the 5 000 requests per hour client limit; locations/{locationId}/latest-samples returns every device in one call.

What does a webhook payload contain?

JSON following the CloudEvents standard. Samples are batched per serial number and carry recorded, sensor values such as temp, humidity, co2, tvoc, pressure, radonShortTermAvg, pm1, pm10, pm25, soundLevelA, light, and batteryPercentage, plus ratings and sensorUnits. Test events use the type sample-manually-triggered-test.

How is an MQTT Publisher secured?

It is configured in the Dashboard with a broker hostname and port. Plain MQTT allows only BASIC_AUTHENTICATION. MQTTS needs a username and password, certificates, or both. Topics follow a template with ${account_id}, ${location_id}, ${serial_number}, and ${message_type}, where message_type is sample or metadata.