API Specification

API v1.0

Complete reference for the ENVSENSOR.cloud REST API. Base URL: https://api.envsensor.cloud

🔐 Authentication

All API requests must include a valid API key in the Authorization header using the Bearer scheme:

Authorization: Bearer YOUR_API_KEY

API keys are generated from the ENVSENSOR dashboard. Keys can be scoped to read or read+write permissions. Unauthenticated requests receive a 401 Unauthorized response.

Sensor Object Schema

Field	Type	Description
`id`	`string`	Unique sensor identifier (e.g. `sns_t_00a1b2`)
`device_id`	`string`	ID of the parent ENVSENSOR device
`type`	`enum`	`temperature` \| `water_quality` \| `air_quality` \| `damp_leak`
`model`	`string`	Hardware model identifier
`label`	`string\|null`	User-assigned friendly name
`status`	`enum`	`online` \| `offline` \| `error`
`firmware_version`	`string`	Current firmware version of the sensor module
`parameters`	`string[]`	Measured parameters (e.g. `["pm25","pm10","co2","voc"]`)
`last_reading`	`object\|null`	Most recent reading snapshot (see Reading object)
`installed_at`	`ISO 8601`	Timestamp of sensor registration
`updated_at`	`ISO 8601`	Last metadata update

GET /v1/sensors

Enumerate all sensors across all devices on the authenticated account. Supports filtering by sensor type, device, and status.

Query Parameters

Param	Type	Default	Description
`type`	`string`	—	Filter by sensor type: `temperature`, `water_quality`, `air_quality`, `damp_leak`
`device_id`	`string`	—	Filter sensors belonging to a specific device
`status`	`string`	—	`online`, `offline`, or `error`
`page`	`integer`	`1`	Page number
`per_page`	`integer`	`25`	Results per page (max 100)

Example — List Temperature Sensors

GET /v1/sensors?type=temperature

{
  "meta": { "total": 4, "page": 1, "per_page": 25 },
  "data": [
    {
      "id": "sns_t_00a1b2",
      "device_id": "dev_8f3c01",
      "type": "temperature",
      "model": "ENV-T100",
      "label": "Server Room NW",
      "status": "online",
      "firmware_version": "2.4.1",
      "parameters": ["temperature"],
      "last_reading": {
        "value": 22.4,
        "unit": "°C",
        "recorded_at": "2026-03-08T10:42:17Z"
      },
      "installed_at": "2025-06-15T08:00:00Z",
      "updated_at": "2026-03-08T10:42:17Z"
    }
  ]
}

GET /v1/sensors/{sensor_id}

Retrieve the full object for a single sensor, including its latest reading and configuration metadata.

Path Parameters

Param	Type	Description
`sensor_id`	`string`	The unique sensor ID (e.g. `sns_t_00a1b2`)

Response

Returns a single Sensor Object (see schema above).

GET /v1/sensors/{sensor_id}/readings

Fetch historical time-series readings for a specific sensor. Returns an array of readings sorted newest-first.

Query Parameters

Param	Type	Default	Description
`from`	`ISO 8601`	24h ago	Start of time range
`to`	`ISO 8601`	now	End of time range
`interval`	`string`	`raw`	Aggregation: `raw`, `1m`, `5m`, `15m`, `1h`, `1d`
`parameter`	`string`	all	Filter to a specific parameter (e.g. `pm25`, `ph`)
`page`	`integer`	`1`	Page number
`per_page`	`integer`	`100`	Results per page (max 1000)

Example — Water Quality Sensor Readings

GET /v1/sensors/sns_w_0b93cf/readings?parameter=ph&interval=1h&from=2026-03-07T00:00:00Z

{
  "meta": { "total": 24, "page": 1, "per_page": 100 },
  "sensor_id": "sns_w_0b93cf",
  "parameter": "ph",
  "data": [
    { "value": 7.21, "unit": "pH", "recorded_at": "2026-03-07T23:00:00Z" },
    { "value": 7.18, "unit": "pH", "recorded_at": "2026-03-07T22:00:00Z" },
    ...
  ]
}

GET /v1/devices

List all ENVSENSOR hardware devices registered to the authenticated account.

Query Parameters

Param	Type	Default	Description
`status`	`string`	—	`online` \| `offline`
`page`	`integer`	`1`	Page number
`per_page`	`integer`	`25`	Results per page (max 100)

Device Object Schema

Field	Type	Description
`id`	`string`	Unique device identifier
`name`	`string`	User-assigned device name
`model`	`string`	Hardware model (e.g. `ENVSENSOR-G3`)
`firmware_version`	`string`	Device firmware version
`status`	`enum`	`online` \| `offline`
`sensor_count`	`integer`	Number of attached sensor modules
`location`	`object\|null`	`{ "lat": 51.509, "lon": -0.118, "label": "London HQ" }`
`last_seen_at`	`ISO 8601`	Last heartbeat timestamp
`registered_at`	`ISO 8601`	Device registration date

GET /v1/devices/{device_id}

Retrieve full details for a single ENVSENSOR device by its unique identifier.

Path Parameters

Param	Type	Description
`device_id`	`string`	The device ID (e.g. `dev_8f3c01`)

GET /v1/devices/{device_id}/sensors

Enumerate all sensor modules attached to a specific device. Returns the same sensor objects as /v1/sensors, scoped to the given device.

Query Parameters

Param	Type	Default	Description
`type`	`string`	—	Filter by sensor type

Example — Damp & Leak Sensors on a Device

GET /v1/devices/dev_8f3c01/sensors?type=damp_leak

{
  "meta": { "total": 2, "page": 1, "per_page": 25 },
  "data": [
    {
      "id": "sns_d_17fe44",
      "device_id": "dev_8f3c01",
      "type": "damp_leak",
      "model": "ENV-DL50",
      "label": "Basement NE Corner",
      "status": "online",
      "parameters": ["moisture_pct", "leak_detected"],
      "last_reading": {
        "moisture_pct": { "value": 12.3, "unit": "%" },
        "leak_detected": { "value": false },
        "recorded_at": "2026-03-08T10:40:02Z"
      }
    }
  ]
}

Sensor Type Reference

Type Enum	Models	Parameters	Units
`temperature`	ENV-T100, ENV-T200, ENV-T300	`temperature`	°C
`water_quality`	ENV-WQ100, ENV-WQ200	`ph`, `dissolved_oxygen`, `turbidity`, `tds`, `conductivity`, `water_temp`	pH, mg/L, NTU, ppm, µS/cm, °C
`air_quality`	ENV-AQ100, ENV-AQ200, ENV-AQ300	`pm25`, `pm10`, `co2`, `voc`, `no2`, `o3`, `temperature`, `humidity`, `aqi`	µg/m³, µg/m³, ppm, ppb, ppb, ppb, °C, %RH, index
`damp_leak`	ENV-DL50, ENV-DL100	`moisture_pct`, `leak_detected`	%, boolean

Error Codes

HTTP Code	Error Key	Description
`400`	`bad_request`	Malformed request or invalid query parameter
`401`	`unauthorized`	Missing or invalid API key
`403`	`forbidden`	API key lacks required scope
`404`	`not_found`	Resource does not exist
`429`	`rate_limited`	Too many requests (limit: 300 req/min)
`500`	`internal_error`	Unexpected server error

Error Response Format

{
  "error": {
    "code": "not_found",
    "message": "Sensor sns_x_000000 does not exist.",
    "status": 404
  }
}