Skip to content
Open AIQ

Upload a sensor reading

POST
/data
curl --request POST \
  --url https://localhost:8080/api/v1/data \
  --header 'Content-Type: application/json' \
  --header 'X-Device-ID: example' \
  --header 'X-Device-Key: example' \
  --data '{ "aqi": 57, "location": { "lat": 24.8607, "lon": 67.0011, "provider": "mobile" }, "pms_data": { "pm1_0": 5.2, "pm2_5": 12.1, "pm10_0": 18.3, "provider": "pms5003" }, "temperature_data": { "heat_index": 36.8, "humidity": 64.5, "provider": "dht22", "temperature": 31.2 } }'

Stores one full sensor reading (particulate matter, AQI, temperature, optional location). The device authenticates with its X-Device-ID and X-Device-Key headers.

Parameters

Section titled “Parameters”

Header Parameters

Section titled “Header Parameters”
X-Device-ID
required
string

Public device id (dev_…)

X-Device-Key
required
string

Secret device key (sk_…)

Request Body

Section titled “Request Body”

Sensor reading

Media typeapplication/json
object
aqi
required
integer
Example
57
location

Location is optional: the device may have no paired mobile at upload time.

object
lat
required
number
>= -90 <= 90
Example
24.8607
lon
required
number
>= -180 <= 180
Example
67.0011
provider
required
string
<= 50 characters
Example
mobile
pms_data
required
object
pm1_0
required
number
Example
5.2
pm2_5
required
number
Example
12.1
pm10_0
required
number
Example
18.3
provider
required
string
<= 50 characters
Example
pms5003
temperature_data
required
object
heat_index
required
number
Example
36.8
humidity
required
number
<= 100
Example
64.5
provider
required
string
<= 50 characters
Example
dht22
temperature
required
number
Example
31.2

Responses

Section titled “Responses”

201

Section titled “201”

Created

Media typeapplication/json
object
data
object
created_at
string
id
integer
Examplegenerated
{
  "data": {
    "created_at": "example",
    "id": 1
  }
}

400

Section titled “400”

Bad Request

Media typeapplication/json
object
detail
string
errors
Array<object>
object
code
string
detail
string
in
string
Allowed values: body query path
name
string
instance
string
status
integer
title
string
type
string
Example
{
  "detail": "One or more request values are invalid.",
  "errors": [
    {
      "code": "required",
      "detail": "name is required",
      "in": "body",
      "name": "name"
    }
  ],
  "instance": "/api/v1/devices",
  "status": 422,
  "title": "Request validation failed",
  "type": "https://docs.air-iq.net/reference/errors/#validation-error"
}

401

Section titled “401”

Unauthorized

Media typeapplication/json
object
detail
string
errors
Array<object>
object
code
string
detail
string
in
string
Allowed values: body query path
name
string
instance
string
status
integer
title
string
type
string
Example
{
  "detail": "One or more request values are invalid.",
  "errors": [
    {
      "code": "required",
      "detail": "name is required",
      "in": "body",
      "name": "name"
    }
  ],
  "instance": "/api/v1/devices",
  "status": 422,
  "title": "Request validation failed",
  "type": "https://docs.air-iq.net/reference/errors/#validation-error"
}

413

Section titled “413”

Request Entity Too Large

Media typeapplication/json
object
detail
string
errors
Array<object>
object
code
string
detail
string
in
string
Allowed values: body query path
name
string
instance
string
status
integer
title
string
type
string
Example
{
  "detail": "One or more request values are invalid.",
  "errors": [
    {
      "code": "required",
      "detail": "name is required",
      "in": "body",
      "name": "name"
    }
  ],
  "instance": "/api/v1/devices",
  "status": 422,
  "title": "Request validation failed",
  "type": "https://docs.air-iq.net/reference/errors/#validation-error"
}

415

Section titled “415”

Unsupported Media Type

Media typeapplication/json
object
detail
string
errors
Array<object>
object
code
string
detail
string
in
string
Allowed values: body query path
name
string
instance
string
status
integer
title
string
type
string
Example
{
  "detail": "One or more request values are invalid.",
  "errors": [
    {
      "code": "required",
      "detail": "name is required",
      "in": "body",
      "name": "name"
    }
  ],
  "instance": "/api/v1/devices",
  "status": 422,
  "title": "Request validation failed",
  "type": "https://docs.air-iq.net/reference/errors/#validation-error"
}

422

Section titled “422”

Unprocessable Entity

Media typeapplication/json
object
detail
string
errors
Array<object>
object
code
string
detail
string
in
string
Allowed values: body query path
name
string
instance
string
status
integer
title
string
type
string
Example
{
  "detail": "One or more request values are invalid.",
  "errors": [
    {
      "code": "required",
      "detail": "name is required",
      "in": "body",
      "name": "name"
    }
  ],
  "instance": "/api/v1/devices",
  "status": 422,
  "title": "Request validation failed",
  "type": "https://docs.air-iq.net/reference/errors/#validation-error"
}

500

Section titled “500”

Internal Server Error

Media typeapplication/json
object
detail
string
errors
Array<object>
object
code
string
detail
string
in
string
Allowed values: body query path
name
string
instance
string
status
integer
title
string
type
string
Example
{
  "detail": "One or more request values are invalid.",
  "errors": [
    {
      "code": "required",
      "detail": "name is required",
      "in": "body",
      "name": "name"
    }
  ],
  "instance": "/api/v1/devices",
  "status": 422,
  "title": "Request validation failed",
  "type": "https://docs.air-iq.net/reference/errors/#validation-error"
}