Device Integration API

We support HTTP GET (URL parameters) for simple or legacy devices — but we prefer HTTPS POST with a JSON body. It is encrypted (TLS), supports batching to save device battery, and keeps data and tokens out of URLs and server logs. New integrations should use HTTPS + POST + JSON where possible.

Authentication

Every request must carry a per-device API token issued by MyAQI during onboarding. Send it as a Bearer token in the Authorization header:

Authorization: Bearer <apitoken>

The token is issued per device (or vendor fleet) and maps to the device’s imei.
Preferred: token in the Authorization header over HTTPS — never exposed in URLs or logs.
Legacy fallback: for devices that cannot set headers, pass ?apitoken=<apitoken> on a GET. Discouraged (tokens in URLs can leak into logs/proxies); HTTPS only.
Missing/invalid/revoked token → 401 Unauthorized. Token not matching the payload imei → 403 Forbidden.

Endpoints

Method	URL	Body	Use
POST preferred	`https://devices.myaqi.org/readings`	JSON	New integrations; single or batch
GET supported	`http(s)://devices.myaqi.org/readings?…`	query params	Simple / legacy devices; one reading

Success: 200 OK / 202 Accepted. Errors: 401 bad/missing token, 403 token/imei mismatch, 400 malformed or missing mandatory field.

Field reference

Field	Type	Unit	Req.	Notes
`imei`	string	—	Yes	Device id (<=30 chars); is a unique id for each device.
`lat`	number	degrees	Yes	Latitude, e.g. 18.55348.
`lon`	number	degrees	Yes	Longitude, e.g. 73.807503.
`timestamp`	string	ISO 8601	Yes	YYYY-MM-DDThh:mm:ss.sssZ (UTC, ms).
`pm1`	number	µg/m³	No	PM1.0.
`pm25`	number	µg/m³	No	PM2.5.
`pm10`	number	µg/m³	No	PM10.
`so2`	number	µg/m³	No	Sulphur dioxide.
`no2`	number	µg/m³	No	Nitrogen dioxide (NOx accepted in lieu).
`co`	number	ppm	No	Carbon monoxide.
`co2`	number	ppm	No	Carbon dioxide.
`hcho`	number	µg/m³	No	Formaldehyde.
`temp`	number	°C	No	Temperature (Celsius).
`humid`	number	g/m³	No	Humidity.
`alt`	number	m	No	Altitude (AGL).
`rssi_4g`	number	dBm	No	4G signal; negative (e.g. -75).
`rssi_5g`	number	dBm	No	5G signal; negative.
`bat`	number	%	No	Battery level, 0–100.

Measurement values are JSON numbers (e.g. 33.0, not "33.0"); only imei and timestamp are strings. Optional fields may be omitted (preferred) or sent as null — never as empty strings. New fields may be added over time; unknown fields are ignored.

Preferred — HTTPS POST + JSON recommended

Single reading

curl --location 'https://devices.myaqi.org/readings' \
  --header 'Authorization: Bearer <apitoken>' \
  --header 'Content-Type: application/json' \
  --data '{
    "imei": "E868E7C7CA23",
    "lat": 18.55348,
    "lon": 73.807503,
    "timestamp": "2026-05-06T14:01:00.000Z",
    "pm1": 21.0,
    "pm25": 33.0,
    "pm10": 43.0,
    "temp": 33.9,
    "humid": 28.1,
    "rssi_4g": -75,
    "bat": 85
  }'

Batch upload (recommended for low-power devices)

To conserve battery, cache readings and upload several at once (e.g. every 5–15 min). Send identity once and an array of time-stamped readings.

curl --location 'https://devices.myaqi.org/readings' \
  --header 'Authorization: Bearer <apitoken>' \
  --header 'Content-Type: application/json' \
  --data '{
    "imei": "E868E7C7CA23",
    "lat": 18.55348, "lon": 73.807503,
    "readings": [
      { "timestamp": "2026-05-06T14:01:00.000Z", "pm25": 33.0, "pm10": 43.0, "temp": 33.9, "humid": 28.1, "bat": 85 },
      { "timestamp": "2026-05-06T14:16:00.000Z", "pm25": 35.0, "pm10": 46.0, "temp": 34.1, "humid": 27.4, "bat": 84 }
    ]
  }'

imei required at top level. lat/lon once at top level (stationary device) or per reading. Each readings element needs a timestamp.

Supported — HTTP GET + URL legacy

For simple or legacy devices. Prefer HTTPS; prefer the Authorization header over the apitoken query parameter.

Token in header (preferred, over HTTPS)

curl --location --get 'https://devices.myaqi.org/readings' \
  --header 'Authorization: Bearer <apitoken>' \
  --data-urlencode 'imei=E868E7C7CA23' \
  --data-urlencode 'lat=18.55348' \
  --data-urlencode 'lon=73.807503' \
  --data-urlencode 'timestamp=2026-05-06T14:01:00.000Z' \
  --data-urlencode 'pm25=33.0' \
  --data-urlencode 'pm10=43.0' \
  --data-urlencode 'temp=33.9' \
  --data-urlencode 'humid=28.1' \
  --data-urlencode 'rssi_4g=-75' \
  --data-urlencode 'bat=85'

Token in URL (discouraged — only if headers are impossible, HTTPS only)

https://devices.myaqi.org/readings?apitoken=<apitoken>
  &imei=E868E7C7CA23&lat=18.55348&lon=73.807503
  &timestamp=2026-05-06T14%3A01%3A00.000Z
  &pm25=33.0&pm10=43.0&temp=33.9&humid=28.1&rssi_4g=-75&bat=85

Omit optional parameters entirely (don’t send empty so2=). Colons in the timestamp are percent-encoded (%3A) in a raw URL.

Rules & conventions

Authenticate every request — Authorization: Bearer <apitoken> preferred.
Mandatory: imei, lat, lon, timestamp (batch: timestamp per reading; identity at top level).
Timestamps UTC, full ISO 8601 with milliseconds and trailing Z.
Optional fields: omit (preferred) or null; never empty strings.
Numbers unquoted; rssi_4g/rssi_5g negative.
Transport: HTTPS strongly preferred; required if the token is in a URL.
Custom formats: we can build an adapter to your shape if the mandatory fields are derivable.

⬇ Download this spec (Markdown) Request an API token →

Device Data API