Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/GaelCeballos/Smart_Enviro_Backend/llms.txt

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

The primary ingestion endpoint for ESP32 devices to submit sensor readings. The device authenticates with its device_token (not a Bearer token), the backend validates the sensor metric key, stores the reading, updates the device’s last-seen timestamp, and returns a device_control block with the current actuator command and automation settings.

​
Endpoint

POST /api/sensor-data Auth: device_token in request body (no Bearer token required)

​
Request Body

​
device_token
string
required
The 64-character secret token assigned to the ESP32 device. Used to authenticate the device and look up its record. The device must be active (is_active = true) in the database.
​
sensor_type_id
string
required
The metric_key of the sensor type to record (e.g. humedad_suelo, temp_amb). The backend resolves this string to the corresponding sensor_types database record. If metric_key is also provided in the payload, it takes precedence over this field.
​
value
number
required
The numeric sensor reading value to store. Stored as a DECIMAL(10,4) in the sensor_data table.
​
metric_key
string
Optional alias for sensor_type_id. If provided, this value takes precedence over sensor_type_id when resolving the sensor type. Both fields accept the same metric_key string format.

​
Example Request

curl -X POST http://localhost/api/sensor-data \
  -H "Content-Type: application/json" \
  -d '{
    "device_token": "YOUR_64_CHAR_TOKEN",
    "sensor_type_id": "humedad_suelo",
    "value": 73.5
  }'

​
Responses

​
201 Created

The reading was stored successfully. The response includes the saved record and the device_control block the ESP32 should use to update its actuator state. 
{
  "status": "success",
  "message": "Lectura guardada correctamente",
  "data": {
    "id": 42,
    "device_id": 3,
    "sensor_type_id": 2,
    "reading_value": 73.5,
    "recorded_at": "2024-01-15T10:30:00.000000Z"
  },
  "device_control": {
    "current_state": "STANDBY",
    "auto_water": false,
    "humidity_threshold": 60
  }
}
​
status
string
Always "success" on a 201 response.
​
message
string
Human-readable confirmation message ("Lectura guardada correctamente").
​
data
object
The newly created sensor_data record as persisted in the database.
​
device_control
object
Configuration block for the ESP32 to update its actuator state. Sourced from the device’s properties key-value store.

​
401 Unauthorized

The device_token does not match any active device (either the token is invalid or the device has is_active = false). 
{"status": "error", "message": "Dispositivo no autorizado o dado de baja"}

​
404 Not Found

The resolved metric_key (from sensor_type_id or metric_key) does not match any registered sensor_types record. 
{"status": "error", "message": "Tipo de sensor 'xyz' no está registrado"}

​
422 Unprocessable Entity

One or more required fields (device_token, sensor_type_id, value) are missing or fail Laravel’s validation rules.
The ESP32 should read device_control.current_state from every response to update its actuator state without requiring a separate sync call.
The sensor_type_id field accepts the metric_key string (not the database integer ID). The backend resolves the metric key to the corresponding sensor_types record. For example, pass "humedad_suelo" or "temp_amb", not 2 or 1.

Build docs developers (and LLMs) love

Get started for freeTalk to us