Device Catalog - Invernaderos API

Overview

The Device Catalog provides centralized management for:

Device Categories: SENSOR or ACTUATOR classifications
Device Types: Specific sensor/actuator types (temperature, humidity, pumps, valves, etc.)
Actuator States: Operational states for actuators (ON, OFF, AUTO, MANUAL, ERROR)

This catalog enables dynamic device configuration and type-safe device management across greenhouses.

Device Categories

Get All Device Categories

curl -X GET "https://api.invernaderos.com/api/v1/catalog/device-categories" \
  -H "Authorization: Bearer YOUR_TOKEN"

Retrieves available device categories (SENSOR and ACTUATOR).

Response

[
  {
    "id": 1,
    "name": "SENSOR"
  },
  {
    "id": 2,
    "name": "ACTUATOR"
  }
]

System ConstantsDevice categories are system-defined:

ID 1 = SENSOR (devices that measure values)
ID 2 = ACTUATOR (devices that perform actions)

Device Types

Get All Device Types

curl -X GET "https://api.invernaderos.com/api/v1/catalog/device-types?categoryId=1&activeOnly=true" \
  -H "Authorization: Bearer YOUR_TOKEN"

Retrieves device types with optional filtering.

Query Parameters

categoryId

short

Filter by category: 1 = SENSOR, 2 = ACTUATOR

activeOnly

boolean

default:"true"

Return only active device types

Response

data

array

Array of device type objects

Show DeviceTypeResponse

short

required

Unique identifier

name

string

required

Device type name (e.g., “TEMPERATURE”, “HUMIDITY”, “PUMP”)

description

string

Description of the device type

categoryId

short

required

Category ID (1=SENSOR, 2=ACTUATOR)

categoryName

string

Category name (“SENSOR” or “ACTUATOR”)

defaultUnitId

short

Default measurement unit ID

defaultUnitSymbol

string

Default unit symbol (e.g., “°C”, ”%”, “hPa”)

dataType

string

Data type: DECIMAL, INTEGER, BOOLEAN, TEXT, JSON

minExpectedValue

number

Minimum expected physical value

maxExpectedValue

number

Maximum expected physical value

controlType

string

For actuators: BINARY (on/off), CONTINUOUS (0-100%), MULTI_STATE (predefined states)

isActive

boolean

required

Whether the device type is active

[
  {
    "id": 1,
    "name": "TEMPERATURE",
    "description": "Temperature sensor",
    "categoryId": 1,
    "categoryName": "SENSOR",
    "defaultUnitId": 1,
    "defaultUnitSymbol": "°C",
    "dataType": "DECIMAL",
    "minExpectedValue": -50.0,
    "maxExpectedValue": 100.0,
    "controlType": null,
    "isActive": true
  },
  {
    "id": 2,
    "name": "HUMIDITY",
    "description": "Relative humidity sensor",
    "categoryId": 1,
    "categoryName": "SENSOR",
    "defaultUnitId": 2,
    "defaultUnitSymbol": "%",
    "dataType": "DECIMAL",
    "minExpectedValue": 0.0,
    "maxExpectedValue": 100.0,
    "controlType": null,
    "isActive": true
  }
]

Get Sensor Types (Shortcut)

curl -X GET "https://api.invernaderos.com/api/v1/catalog/device-types/sensors" \
  -H "Authorization: Bearer YOUR_TOKEN"

Shortcut endpoint to retrieve only sensor types (equivalent to ?categoryId=1).

Get Actuator Types (Shortcut)

curl -X GET "https://api.invernaderos.com/api/v1/catalog/device-types/actuators" \
  -H "Authorization: Bearer YOUR_TOKEN"

Shortcut endpoint to retrieve only actuator types (equivalent to ?categoryId=2).

Get Device Type by ID

curl -X GET "https://api.invernaderos.com/api/v1/catalog/device-types/1" \
  -H "Authorization: Bearer YOUR_TOKEN"

Path Parameters

short

required

Device type ID

Response

{
  "id": 1,
  "name": "TEMPERATURE",
  "description": "Temperature sensor",
  "categoryId": 1,
  "categoryName": "SENSOR",
  "defaultUnitId": 1,
  "defaultUnitSymbol": "°C",
  "dataType": "DECIMAL",
  "minExpectedValue": -50.0,
  "maxExpectedValue": 100.0,
  "controlType": null,
  "isActive": true
}

Create Device Type

curl -X POST "https://api.invernaderos.com/api/v1/catalog/device-types" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "SOIL_MOISTURE",
    "description": "Soil moisture sensor",
    "categoryId": 1,
    "defaultUnitId": 2,
    "dataType": "DECIMAL",
    "minExpectedValue": 0.0,
    "maxExpectedValue": 100.0,
    "isActive": true
  }'

Request Body

name

string

required

Device type name (max 30 characters, must be unique)

description

string

Description of the device type

categoryId

short

required

Category ID: 1 = SENSOR, 2 = ACTUATOR

defaultUnitId

short

Default measurement unit ID (from Units catalog)

dataType

string

default:"DECIMAL"

Data type: DECIMAL, INTEGER, BOOLEAN, TEXT, JSON

minExpectedValue

number

Minimum expected physical value (for validation)

maxExpectedValue

number

Maximum expected physical value (for validation)

controlType

string

For actuators: BINARY (on/off), CONTINUOUS (0-100%), MULTI_STATE (predefined states)

isActive

boolean

default:"true"

Whether the device type is active

Response

{
  "id": 15,
  "name": "SOIL_MOISTURE",
  "description": "Soil moisture sensor",
  "categoryId": 1,
  "categoryName": "SENSOR",
  "defaultUnitId": 2,
  "defaultUnitSymbol": "%",
  "dataType": "DECIMAL",
  "minExpectedValue": 0.0,
  "maxExpectedValue": 100.0,
  "controlType": null,
  "isActive": true
}

Update Device Type

curl -X PUT "https://api.invernaderos.com/api/v1/catalog/device-types/15" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Soil moisture sensor with improved accuracy",
    "maxExpectedValue": 90.0
  }'

Path Parameters

short

required

Device type ID to update

Request Body

All fields are optional. Only provided fields will be updated.

name

string

New device type name (max 30 characters, must be unique)

description

string

New description

categoryId

short

New category ID

defaultUnitId

short

New default unit ID

dataType

string

New data type

minExpectedValue

number

New minimum expected value

maxExpectedValue

number

New maximum expected value

controlType

string

New control type (for actuators)

isActive

boolean

New active status

Response

Same structure as “Create Device Type” with updated values.

Activate/Deactivate Device Type

PATCH /api/v1/catalog/device-types/{id}/activate
curl -X PATCH "https://api.invernaderos.com/api/v1/catalog/device-types/15/activate" \
  -H "Authorization: Bearer YOUR_TOKEN"

Soft delete/restore device types without removing from database.

Path Parameters

short

required

Device type ID

Response

{
  "id": 15,
  "name": "SOIL_MOISTURE",
  "description": "Soil moisture sensor",
  "categoryId": 1,
  "categoryName": "SENSOR",
  "defaultUnitId": 2,
  "defaultUnitSymbol": "%",
  "dataType": "DECIMAL",
  "minExpectedValue": 0.0,
  "maxExpectedValue": 100.0,
  "controlType": null,
  "isActive": false  // Changed to false after deactivation
}

Delete Device Type

curl -X DELETE "https://api.invernaderos.com/api/v1/catalog/device-types/15" \
  -H "Authorization: Bearer YOUR_TOKEN"

Path Parameters

short

required

Device type ID to delete

Response

Device type deleted successfully (no body)

Deletion ConstraintsCannot delete device types that have associated devices (sensors or actuators). You must:

Remove or reassign all devices using this type, OR
Use deactivation (PATCH /deactivate) instead for soft delete

Actuator States Catalog

Get All Actuator States

curl -X GET "https://api.invernaderos.com/api/v1/catalog/actuator-states" \
  -H "Authorization: Bearer YOUR_TOKEN"

Retrieves all possible actuator states (ON, OFF, AUTO, MANUAL, ERROR, etc.).

Response

data

array

Array of actuator state objects

Show ActuatorStateResponse

short

required

Unique identifier

name

string

required

State name (e.g., “ON”, “OFF”, “AUTO”, “MANUAL”, “ERROR”)

description

string

Description of the state

isOperational

boolean

required

Whether the actuator is functioning in this state

displayOrder

short

required

Sort order for UI display

color

string

Hex color code for UI visualization (e.g., “#00FF00”)

[
  {
    "id": 1,
    "name": "ON",
    "description": "Actuator is running",
    "isOperational": true,
    "displayOrder": 1,
    "color": "#00FF00"
  },
  {
    "id": 2,
    "name": "OFF",
    "description": "Actuator is stopped",
    "isOperational": false,
    "displayOrder": 2,
    "color": "#808080"
  },
  {
    "id": 3,
    "name": "AUTO",
    "description": "Automatic mode based on sensors",
    "isOperational": true,
    "displayOrder": 3,
    "color": "#0066FF"
  },
  {
    "id": 4,
    "name": "MANUAL",
    "description": "Manual control mode",
    "isOperational": true,
    "displayOrder": 4,
    "color": "#FFAA00"
  },
  {
    "id": 5,
    "name": "ERROR",
    "description": "Actuator malfunction",
    "isOperational": false,
    "displayOrder": 10,
    "color": "#FF0000"
  }
]

Get Operational States Only

curl -X GET "https://api.invernaderos.com/api/v1/catalog/actuator-states/operational" \
  -H "Authorization: Bearer YOUR_TOKEN"

Retrieves only states where the actuator is functioning (isOperational = true).

Response

Same structure as “Get All Actuator States”, but filtered to operational states only (ON, AUTO, MANUAL, etc.).

Get Actuator State by ID

curl -X GET "https://api.invernaderos.com/api/v1/catalog/actuator-states/1" \
  -H "Authorization: Bearer YOUR_TOKEN"

Path Parameters

short

required

Actuator state ID

Response

{
  "id": 1,
  "name": "ON",
  "description": "Actuator is running",
  "isOperational": true,
  "displayOrder": 1,
  "color": "#00FF00"
}

Create Actuator State

curl -X POST "https://api.invernaderos.com/api/v1/catalog/actuator-states" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "WARMING_UP",
    "description": "Actuator is warming up before full operation",
    "isOperational": true,
    "displayOrder": 5,
    "color": "#FFA500"
  }'

Request Body

name

string

required

State name (max 20 characters, must be unique)

description

string

Description of the state

isOperational

boolean

default:"false"

Whether the actuator is functioning in this state

displayOrder

short

default:"0"

Sort order for UI display (minimum 0)

color

string

Hex color code (format: #RRGGBB, e.g., “#FFA500”)

Response

{
  "id": 6,
  "name": "WARMING_UP",
  "description": "Actuator is warming up before full operation",
  "isOperational": true,
  "displayOrder": 5,
  "color": "#FFA500"
}

Update Actuator State

curl -X PUT "https://api.invernaderos.com/api/v1/catalog/actuator-states/6" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Actuator warming up - full operation in 30 seconds",
    "displayOrder": 3
  }'

Path Parameters

short

required

Actuator state ID to update

Request Body

All fields are optional. Only provided fields will be updated.

name

string

New state name (max 20 characters, must be unique)

description

string

New description

isOperational

boolean

New operational status

displayOrder

short

New display order (minimum 0)

color

string

New hex color code

Response

Same structure as “Create Actuator State” with updated values.

Delete Actuator State

curl -X DELETE "https://api.invernaderos.com/api/v1/catalog/actuator-states/6" \
  -H "Authorization: Bearer YOUR_TOKEN"

Path Parameters

short

required

Actuator state ID to delete

Response

Actuator state deleted successfully (no body)

Control Types Explained

BINARY Control

Use Case: Simple on/off actuatorsExamples:

Irrigation pumps (ON/OFF)
Grow lights (ON/OFF)
Heaters (ON/OFF)

Data Type: BOOLEANStates: ON, OFFImplementation:

{
  "name": "IRRIGATION_PUMP",
  "categoryId": 2,
  "controlType": "BINARY",
  "dataType": "BOOLEAN"
}

CONTINUOUS Control

Use Case: Variable speed/position actuatorsExamples:

Vent windows (0-100% open)
Variable speed fans (0-100% speed)
Dimmers (0-100% brightness)

Data Type: INTEGER or DECIMALRange: 0-100 (percentage)Implementation:

{
  "name": "VENT_WINDOW",
  "categoryId": 2,
  "controlType": "CONTINUOUS",
  "dataType": "INTEGER",
  "minExpectedValue": 0,
  "maxExpectedValue": 100,
  "defaultUnitId": 2  // % symbol
}

MULTI_STATE Control

Use Case: Actuators with predefined statesExamples:

Irrigation valves (CLOSED, ZONE_1, ZONE_2, ZONE_3)
Multi-speed fans (OFF, LOW, MEDIUM, HIGH)
Heating systems (OFF, ECO, COMFORT, BOOST)

Data Type: TEXT or INTEGER (state index)States: Defined in actuator_states catalogImplementation:

{
  "name": "IRRIGATION_VALVE",
  "categoryId": 2,
  "controlType": "MULTI_STATE",
  "dataType": "TEXT"
}

Integration Examples

// Generate device configuration form based on device type
const loadDeviceTypeConfig = async (deviceTypeId) => {
  const deviceType = await fetch(
    `https://api.invernaderos.com/api/v1/catalog/device-types/${deviceTypeId}`,
    { headers: { 'Authorization': `Bearer ${token}` } }
  ).then(res => res.json());
  
  // Generate UI based on control type
  switch (deviceType.controlType) {
    case 'BINARY':
      return {
        component: 'Toggle',
        props: {
          label: deviceType.name,
          states: ['ON', 'OFF']
        }
      };
    
    case 'CONTINUOUS':
      return {
        component: 'Slider',
        props: {
          label: deviceType.name,
          min: deviceType.minExpectedValue,
          max: deviceType.maxExpectedValue,
          unit: deviceType.defaultUnitSymbol,
          step: 1
        }
      };
    
    case 'MULTI_STATE':
      const states = await fetch(
        'https://api.invernaderos.com/api/v1/catalog/actuator-states',
        { headers: { 'Authorization': `Bearer ${token}` } }
      ).then(res => res.json());
      
      return {
        component: 'Dropdown',
        props: {
          label: deviceType.name,
          options: states.map(s => ({ value: s.id, label: s.name }))
        }
      };
    
    default:
      return { component: 'Input', props: { label: deviceType.name } };
  }
};

Error Codes

Status Code	Description	Resolution
200 OK	Request successful	-
201 Created	Resource created successfully	-
204 No Content	Resource deleted successfully	-
400 Bad Request	Invalid input (duplicate name, invalid category, invalid color format)	Check error message for details
404 Not Found	Resource not found with specified ID	Verify the ID exists
409 Conflict	Cannot delete resource due to dependencies (devices using type)	Remove dependencies or use deactivation

Best Practices

Sensor Types

When creating sensor types:

Set realistic value ranges (minExpectedValue, maxExpectedValue) for validation
Choose appropriate units from the Units catalog
Use DECIMAL data type for most measurements (temperature, humidity, pressure)
Document physical constraints in the description field

Example:

{
  "name": "SOIL_TEMPERATURE",
  "description": "Soil temperature at 10cm depth",
  "categoryId": 1,
  "defaultUnitId": 1,  // °C
  "dataType": "DECIMAL",
  "minExpectedValue": -10.0,
  "maxExpectedValue": 50.0
}

Actuator Types

When creating actuator types:

Choose correct control type (BINARY, CONTINUOUS, MULTI_STATE)
For CONTINUOUS, always set min/max values (typically 0-100)
For MULTI_STATE, define states in actuator_states catalog first
Document control behavior in the description

Example:

{
  "name": "NUTRIENT_PUMP",
  "description": "Variable speed nutrient injection pump (0-100% flow rate)",
  "categoryId": 2,
  "defaultUnitId": 2,  // %
  "controlType": "CONTINUOUS",
  "dataType": "INTEGER",
  "minExpectedValue": 0,
  "maxExpectedValue": 100
}

Actuator States

When defining actuator states:

Use consistent naming (uppercase: ON, OFF, AUTO, MANUAL)
Set isOperational correctly (true = actuator functioning, false = error/stopped)
Choose intuitive colors: Green (operational), Red (error), Gray (off), Orange (transitional)
Order by priority: Critical states (ERROR) should have high displayOrder

Example:

{
  "name": "STARTING",
  "description": "Actuator is starting up",
  "isOperational": true,
  "displayOrder": 4,
  "color": "#FFA500"  // Orange for transitional state
}

Soft Deletes

Prefer deactivation over deletion to preserve historical device configurations
Only delete truly unused custom types with zero associated devices
Document deprecation in description before deactivating
Use activeOnly=true in queries to filter out deprecated types

Units Catalog

Units define measurement units for sensors (°C, %, lux, ppm, etc.).

Get All Units

GET /api/v1/catalog/units

Retrieves all available measurement units.

Response

integer

Unique unit identifier

name

string

Unit name (e.g., “Celsius”, “Percent”, “Lux”)

symbol

string

Unit symbol (e.g., “°C”, ”%”, “lux”)

isActive

boolean

Whether the unit is currently active

Example

cURL

curl -X GET "https://api.example.com/api/v1/catalog/units" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Get Unit by ID

GET /api/v1/catalog/units/{id}

integer

required

Unit ID

Create Unit

POST /api/v1/catalog/units

name

string

required

Unit name

symbol

string

required

Unit symbol

Update Unit

PUT /api/v1/catalog/units/{id}

Activate Unit

PUT /api/v1/catalog/units/{id}/activate

Activates a previously deactivated unit.

Deactivate Unit

PUT /api/v1/catalog/units/{id}/deactivate

Deactivated units cannot be deleted if they are referenced by devices or settings.

Periods Catalog

Periods define time intervals for alerts and automation rules.

Get All Periods

GET /api/v1/catalog/periods

Retrieves all available time periods.

Response

integer

Unique period identifier

name

string

Period name (e.g., “Morning”, “Afternoon”, “Night”)

description

string

Period description

Example

cURL

curl -X GET "https://api.example.com/api/v1/catalog/periods" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Get Period by ID

GET /api/v1/catalog/periods/{id}

integer

required

Period ID

Create Period

POST /api/v1/catalog/periods

name

string

required

Period name

description

string

Period description

Update Period

PUT /api/v1/catalog/periods/{id}

Delete Period

DELETE /api/v1/catalog/periods/{id}

Cannot delete periods that are referenced by active automation rules or alerts.

Authentication

Tenant Management

Sensor Data

MQTT

Catalogs

Additional Endpoints

​Overview

​Device Categories

​Get All Device Categories

​Response

​Device Types

​Get All Device Types

​Query Parameters

​Response

​Get Sensor Types (Shortcut)

​Get Actuator Types (Shortcut)

​Get Device Type by ID

​Path Parameters

​Response

​Create Device Type

​Request Body

​Response

​Update Device Type

​Path Parameters

​Request Body

​Response

​Activate/Deactivate Device Type

​Path Parameters

​Response

​Delete Device Type

​Path Parameters

​Response

​Actuator States Catalog

​Get All Actuator States

​Response

​Get Operational States Only

​Response

​Get Actuator State by ID

​Path Parameters

​Response

​Create Actuator State

​Request Body

​Response

​Update Actuator State

​Path Parameters

​Request Body

​Response

​Delete Actuator State

​Path Parameters

​Response

​Control Types Explained

​Integration Examples

​Error Codes

​Best Practices

​Units Catalog

​Get All Units

​Response

​Example

​Get Unit by ID

​Create Unit

​Update Unit

​Activate Unit

​Deactivate Unit

​Periods Catalog

​Get All Periods

​Response

​Example

​Get Period by ID

​Create Period

​Update Period

​Delete Period

Build docs developers (and LLMs) love

Overview

Device Categories

Get All Device Categories

Response

Device Types

Get All Device Types

Query Parameters

Response

Get Sensor Types (Shortcut)

Get Actuator Types (Shortcut)

Get Device Type by ID

Path Parameters

Response

Create Device Type

Request Body

Response

Update Device Type

Path Parameters

Request Body

Response

Activate/Deactivate Device Type

Path Parameters

Response

Delete Device Type

Path Parameters

Response

Actuator States Catalog

Get All Actuator States

Response

Get Operational States Only

Response

Get Actuator State by ID

Path Parameters

Response

Create Actuator State

Request Body

Response

Update Actuator State

Path Parameters

Request Body

Response

Delete Actuator State

Path Parameters

Response

Control Types Explained

Integration Examples

Error Codes

Best Practices

Units Catalog

Get All Units

Response

Example

Get Unit by ID

Create Unit

Update Unit

Activate Unit

Deactivate Unit

Periods Catalog

Get All Periods

Response

Example

Get Period by ID

Create Period

Update Period

Delete Period