Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/diarpicu2022-commits/backend-AgroPulse/llms.txt

Use this file to discover all available pages before exploring further.

The Sensors API is the central registry for every physical sensor connected to an AgroPulse greenhouse. Each record describes a single measurement point — its type, hardware address, communication protocol, and which greenhouse it belongs to. Clients such as ESP32 edge nodes and the dashboard frontend use this API to discover active sensors before submitting readings.

​
Endpoints

MethodPathDescription
GET/api/sensorsList all sensors, optionally filtered by greenhouse
POST/api/sensorsCreate a sensor (or update an existing one via upsert)
GET/api/sensors/{id}Retrieve a single sensor by ID
PUT/api/sensors/{id}Update a sensor by ID
DELETE/api/sensors/{id}Remove a sensor by ID

​
GET /api/sensors

Returns all registered sensors. Pass greenhouseId to scope the result to a single greenhouse.

​
Query parameters

​
greenhouseId
number
When provided, only sensors belonging to this greenhouse are returned.

​
Response

{
  "sensors": [
    {
      "id": 1,
      "name": "Roof DHT22",
      "type": "TEMPERATURE",
      "location": "North wing, ceiling",
      "greenhouseId": 3,
      "lastValue": 24.5,
      "active": true,
      "gpioPin": 4,
      "protocol": "DHT22",
      "deviceSource": "esp32-node-01"
    }
  ]
}

​
curl example

# All sensors
curl http://localhost:8080/api/sensors

# Filtered by greenhouse
curl "http://localhost:8080/api/sensors?greenhouseId=3"

​
POST /api/sensors

Creates a new sensor. If the combination of deviceSource, type, and gpioPin matches an existing record, the API performs an update instead of inserting a duplicate. This upsert behavior is designed for ESP32 nodes that re-register their sensors on boot.
Upsert matching requires all three fields — deviceSource, type, and gpioPin — to be present and non-blank. When any of the three is missing, a new record is always created.

​
Body parameters

​
name
string
required
Human-readable label for the sensor, e.g. "Roof DHT22".
​
type
string
required
Measurement category. Must be one of the SensorType enum values listed below.
​
greenhouseId
number
required
ID of the greenhouse this sensor belongs to.
​
location
string
Physical location description, e.g. "North wing, ceiling".
​
lastValue
number
default:"0"
Most recent measurement value. Updated by the readings pipeline automatically.
​
active
boolean
default:"true"
Whether the sensor should be included in monitoring and anomaly detection.
​
gpioPin
number
GPIO pin number on the microcontroller board. Required for upsert matching.
​
protocol
string
Communication protocol. Common values: DHT22, DHT11, ADC, I2C, DIGITAL.
​
deviceSource
string
Identifier of the ESP32 or other device that registered this sensor (e.g. "esp32-node-01"). Required for upsert matching.

​
SensorType values

ValueUnitDescription
TEMPERATURE°CGeneral-purpose temperature
HUMIDITY%Relative air humidity
SOIL_MOISTURE%Soil moisture level
LIGHTluxAmbient light intensity
CO2ppmCarbon dioxide concentration
PHpHSoil or solution pH
WIND_SPEEDm/sWind speed (outdoor sensors)
TEMPERATURE_INTERNAL°CTemperature inside the greenhouse structure
TEMPERATURE_EXTERNAL°CTemperature outside the greenhouse structure

​
curl example

curl -X POST http://localhost:8080/api/sensors \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Roof DHT22",
    "type": "TEMPERATURE",
    "location": "North wing, ceiling",
    "greenhouseId": 3,
    "gpioPin": 4,
    "protocol": "DHT22",
    "deviceSource": "esp32-node-01",
    "active": true
  }'

​
GET /api/sensors/

Returns a single sensor record.

​
Path parameters

​
id
number
required
The sensor ID.

​
Response

​
id
number
Auto-generated sensor identifier.
​
name
string
Human-readable label.
​
type
string
SensorType enum value.
​
location
string
Physical location description.
​
greenhouseId
number
ID of the owning greenhouse.
​
lastValue
number
Most recent measurement value stored for this sensor.
​
active
boolean
Whether the sensor is currently monitored.
​
gpioPin
number
GPIO pin number on the connected microcontroller.
​
protocol
string
Communication protocol (e.g. DHT22, I2C).
​
deviceSource
string
Identifier of the originating ESP32 device.

​
curl example

curl http://localhost:8080/api/sensors/1

​
PUT /api/sensors/

Updates an existing sensor. Only the fields included in the request body are changed; omitted fields retain their current values.
This endpoint checks ownership via OwnershipService. Requests that fail the ownership check receive a 403 Forbidden response with an error message.

​
Path parameters

​
id
number
required
The sensor ID to update.

​
Body parameters

All body fields are optional. Provide only the fields you want to change.
​
name
string
Updated sensor label.
​
type
string
Updated SensorType enum value.
​
location
string
Updated physical location.
​
greenhouseId
number
Reassign to a different greenhouse.
​
lastValue
number
Override the last recorded value.
​
active
boolean
Enable or disable monitoring for this sensor.
​
gpioPin
number
Updated GPIO pin number.
​
protocol
string
Updated communication protocol.
​
deviceSource
string
Updated device source identifier.

​
curl example

curl -X PUT http://localhost:8080/api/sensors/1 \
  -H "Content-Type: application/json" \
  -d '{
    "active": false,
    "location": "South wing, floor"
  }'

​
DELETE /api/sensors/

Permanently removes a sensor record.
This endpoint also enforces ownership. A 403 Forbidden is returned if the caller is not the sensor owner. Deletion is permanent and cannot be undone.

​
Path parameters

​
id
number
required
The sensor ID to delete.

​
Response

{ "deleted": true }

​
curl example

curl -X DELETE http://localhost:8080/api/sensors/1

Build docs developers (and LLMs) love

Get started for freeTalk to us