Skip to main content

​
Get All Devices

Retrieve all devices (sensors and actuators) for a specific tenant.

​
Path Parameters

​
tenantId
long
required
ID of the tenant

​
Response

​
id
long
Unique ID of the device (TSID - Time-Sorted ID)
​
code
string
Unique code per tenant (e.g., DEV-00001)
​
tenantId
long
ID of the tenant owning this device
​
sectorId
long
ID of the sector where the device is installed
​
sectorCode
string
Code of the sector
​
name
string
Human-readable name (e.g., “Temperature Sensor Greenhouse 1”)
​
categoryId
integer
Category ID (1=SENSOR, 2=ACTUATOR)
​
categoryName
string
Category name (SENSOR or ACTUATOR)
​
typeId
integer
Device type ID (e.g., 1=TEMPERATURE, 2=HUMIDITY, 3=VALVE)
​
typeName
string
Device type name
​
unitId
integer
Unit of measurement ID
​
unitSymbol
string
Unit symbol (°C, %, ppm, etc.)
​
isActive
boolean
Whether the device is active
​
createdAt
string
Creation timestamp (ISO 8601)
​
updatedAt
string
Last update timestamp (ISO 8601)

​
Example Request

curl -X GET "https://api.example.com/api/v1/tenants/123/devices" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Example Response

[
  {
    "id": 456789012345,
    "code": "DEV-00001",
    "tenantId": 123,
    "sectorId": 789,
    "sectorCode": "SEC-01",
    "name": "Temperature Sensor Greenhouse 1",
    "categoryId": 1,
    "categoryName": "SENSOR",
    "typeId": 1,
    "typeName": "TEMPERATURE",
    "unitId": 1,
    "unitSymbol": "°C",
    "isActive": true,
    "createdAt": "2025-03-01T10:00:00Z",
    "updatedAt": "2025-03-01T10:00:00Z"
  },
  {
    "id": 456789012346,
    "code": "DEV-00002",
    "tenantId": 123,
    "sectorId": 789,
    "sectorCode": "SEC-01",
    "name": "Humidity Sensor Greenhouse 1",
    "categoryId": 1,
    "categoryName": "SENSOR",
    "typeId": 2,
    "typeName": "HUMIDITY",
    "unitId": 2,
    "unitSymbol": "%",
    "isActive": true,
    "createdAt": "2025-03-01T10:05:00Z",
    "updatedAt": "2025-03-01T10:05:00Z"
  }
]

​
Get Device by ID

Retrieve a specific device by its ID.

​
Path Parameters

​
tenantId
long
required
ID of the tenant
​
deviceId
long
required
ID of the device

​
Response

Returns a single device object (same structure as “Get All Devices”).

​
Example Request

curl -X GET "https://api.example.com/api/v1/tenants/123/devices/456789012345" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Create Device

Create a new device for a tenant.

​
Path Parameters

​
tenantId
long
required
ID of the tenant

​
Request Body

​
sectorId
long
required
ID of the sector where the device will be installed
​
name
string
Human-readable name (max 100 characters)
​
categoryId
integer
Category ID (1=SENSOR, 2=ACTUATOR)
​
typeId
integer
Device type ID (e.g., 1=TEMPERATURE, 2=HUMIDITY)
​
unitId
integer
Unit of measurement ID
​
isActive
boolean
default:"true"
Whether the device is active

​
Response

Returns the created device object with status code 201 Created.

​
Example Request

curl -X POST "https://api.example.com/api/v1/tenants/123/devices" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "sectorId": 789,
    "name": "CO2 Sensor Greenhouse 2",
    "categoryId": 1,
    "typeId": 5,
    "unitId": 5,
    "isActive": true
  }'

​
Example Response

{
  "id": 456789012347,
  "code": "DEV-00003",
  "tenantId": 123,
  "sectorId": 789,
  "sectorCode": "SEC-02",
  "name": "CO2 Sensor Greenhouse 2",
  "categoryId": 1,
  "categoryName": "SENSOR",
  "typeId": 5,
  "typeName": "CO2",
  "unitId": 5,
  "unitSymbol": "ppm",
  "isActive": true,
  "createdAt": "2025-03-03T15:30:00Z",
  "updatedAt": "2025-03-03T15:30:00Z"
}

​
Update Device

Update an existing device.

​
Path Parameters

​
tenantId
long
required
ID of the tenant
​
deviceId
long
required
ID of the device to update

​
Request Body

All fields are optional. Only include fields you want to update.
​
sectorId
long
ID of the sector (must belong to the same tenant)
​
name
string
Human-readable name (max 100 characters)
​
categoryId
integer
Category ID (1=SENSOR, 2=ACTUATOR)
​
typeId
integer
Device type ID
​
unitId
integer
Unit of measurement ID
​
isActive
boolean
Whether the device is active

​
Response

Returns the updated device object.

​
Example Request

curl -X PUT "https://api.example.com/api/v1/tenants/123/devices/456789012347" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "name": "CO2 Sensor - Updated Name",
    "isActive": false
  }'

​
Delete Device

Delete a device from a tenant.

​
Path Parameters

​
tenantId
long
required
ID of the tenant
​
deviceId
long
required
ID of the device to delete

​
Response

Returns status code 204 No Content on success, or 404 Not Found if the device doesn’t exist.

​
Example Request

curl -X DELETE "https://api.example.com/api/v1/tenants/123/devices/456789012347" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Device Categories

Devices are categorized into two main types:

​
1. Sensors

  • Category ID: 1
  • Purpose: Collect environmental data
  • Types: Temperature, Humidity, CO2, Light, Soil Moisture, Atmospheric Pressure
  • Data Flow: Sensors → MQTT → API → Database

​
2. Actuators

  • Category ID: 2
  • Purpose: Control greenhouse systems
  • Types: Valves, Fans, Heaters, Lights, Vents
  • Data Flow: API → MQTT → Actuators
  • Control Modes: Manual, Automatic, Scheduled

​
Device Types

Common device types include:
Type IDType NameCategoryUnit
1TEMPERATURESensor°C
2HUMIDITYSensor%
3SOIL_MOISTURESensor%
4LIGHT_INTENSITYSensorlux
5CO2Sensorppm
6ATMOSPHERIC_PRESSURESensorhPa
7VALVEActuator-
8FANActuator-
9HEATERActuator-
10VENTActuator-

​
Device Hierarchy

Devices are organized in a hierarchical structure: 
Tenant
  └── Greenhouse
      └── Sector
          └── Device (Sensor or Actuator)
  • Tenant: The organization or customer
  • Greenhouse: Physical greenhouse location
  • Sector: Zone within a greenhouse (e.g., Zone A, Zone B)
  • Device: Individual sensor or actuator
Each device:
  • Has a unique code per tenant (e.g., DEV-00001)
  • Belongs to exactly one sector
  • Inherits tenant context from its sector
  • Can be activated/deactivated via the isActive flag

Build docs developers (and LLMs) love

Get started for freeTalk to us