Device API

Manage IoT devices. Devices are stored in the iot_objects collection with obj_type: 'devices'.

---

List Devices

Retrieves a paginated list of devices.

GET /api/devices

Query Parameters

Parameter	Type	Default	Description
page	number	1	Page number
limit	number	10	Items per page
name	string	—	Filter by name (case-insensitive)
date	string	—	Filter by creation date (YYYY-MM-DD)
groupId	string	—	Filter by group (24-character hex Object ID)
projectId	string	—	Filter by project (24-character hex Object ID)
attrName	string	—	Filter by attribute name (requires attrValue)
attrValue	string	—	Filter by attribute value (requires attrName)

Example

curl -H "Authorization: Bearer <key>" \
  "http://localhost:9001/api/devices?page=1&limit=10"

Example (with attribute filter)

curl -H "Authorization: Bearer <key>" \
  "http://localhost:9001/api/devices?attrName=firmware_version&attrValue=2.1.0"

Returns only devices that have an attribute named firmware_version with value 2.1.0.

Response

{
  "success": true,
  "data": [
    {
      "_id": "665a1b2c3d4e5f6a7b8c9d0e",
      "name": "Temperature Sensor",
      "label": "Warehouse A",
      "description": "Monitors ambient temperature",
      "obj_type": "devices",
      "status": false,
      "clientId": "664a1b2c3d4e5f6a7b8c9d0a",
      "owner": "664a1b2c3d4e5f6a7b8c9d0b",
      "group": null,
      "profile": null,
      "ruleChainId": null,
      "created_at": "2025-01-15T10:30:00.000Z",
      "updated_at": "2025-01-15T10:30:00.000Z",
      "attributes": [
        {
          "_id": "665a1b2c3d4e5f6a7b8c9d10",
          "name": "firmware_version",
          "type_data": "string",
          "value": "2.1.0"
        }
      ]
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 10
}

---

Get Device

Retrieves a single device by ID.

GET /api/devices?id=<device_id>

Query Parameters

Parameter	Type	Required	Description
id	string	yes	24-character hex Object ID

Example

curl -H "Authorization: Bearer <key>" \
  "http://localhost:9001/api/devices?id=665a1b2c3d4e5f6a7b8c9d0e"

Response

{
  "success": true,
  "data": {
    "_id": "665a1b2c3d4e5f6a7b8c9d0e",
    "name": "Temperature Sensor",
    "label": "Warehouse A",
    "description": "Monitors ambient temperature",
    "obj_type": "devices",
    "status": false,
    "clientId": "664a1b2c3d4e5f6a7b8c9d0a",
    "owner": "664a1b2c3d4e5f6a7b8c9d0b",
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-15T10:30:00.000Z"
  },
  "attributes": [
    {
      "_id": "665a1b2c3d4e5f6a7b8c9d10",
      "name": "firmware_version",
      "type_data": "string",
      "value": "2.1.0"
    },
    {
      "_id": "665a1b2c3d4e5f6a7b8c9d11",
      "name": "location",
      "type_data": "string",
      "value": "Warehouse A"
    }
  ]
}

Returns "data": null if the device is not found. The attributes array contains all attributes linked to the device from the iot_attributes collection.

---

Create Device

Creates a new device with full provisioning (HTTP token, MQTT credentials, Redis caching).

POST /api/devices?id=new
Content-Type: application/json

Request Body

Field	Type	Required	Description
name	string	yes	Device name
label	string	no	Display label
description	string	no	Description
owner	string	yes	User Object ID (24 hex)
group	string	no	Device group Object ID
profile	string	no	Device profile Object ID
ruleChainId	string	no	Rule chain Object ID
projectId	string	no	Project Object ID

Example

curl -X POST -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Temperature Sensor",
    "label": "Warehouse A",
    "description": "Monitors ambient temperature",
    "owner": "664a1b2c3d4e5f6a7b8c9d0b"
  }' \
  "http://localhost:9001/api/devices?id=new"

Response

{
  "success": true
}

Automatic Provisioning

On creation, the API automatically generates:

Resource	Description
HTTP Token	UUID used for telemetry/attribute ingestion (/t/:token/telemetry)
MQTT Client ID	Random client identifier
MQTT Username	Random username
MQTT Password	Random password
Redis Cache	Auth credentials cached in Redis for fast validation

---

Update Device

Updates an existing device.

POST /api/devices?id=<device_id>
Content-Type: application/json

Query Parameters

Parameter	Type	Required	Description
id	string	yes	24-character hex Object ID

Request Body

Field	Type	Required	Description
name	string	yes	Device name
label	string	no	Display label
description	string	no	Description
owner	string	no	User Object ID
group	string	—	Pass empty string to clear
profile	string	—	Pass empty string to clear
ruleChainId	string	—	Pass empty string to clear

Example

curl -X POST -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Temperature Sensor v2",
    "label": "Warehouse B",
    "description": "Updated description",
    "owner": "664a1b2c3d4e5f6a7b8c9d0b"
  }' \
  "http://localhost:9001/api/devices?id=665a1b2c3d4e5f6a7b8c9d0e"

Response

{
  "success": true
}

The API also re-caches the device's HTTP and MQTT credentials in Redis.

---

Delete Device

Deletes a device and its associated tokens.

DELETE /api/devices?id=<device_id>

Query Parameters

Parameter	Type	Required	Description
id	string	yes	24-character hex Object ID

Example

curl -X DELETE -H "Authorization: Bearer <key>" \
  "http://localhost:9001/api/devices?id=665a1b2c3d4e5f6a7b8c9d0e"

Response

{
  "success": true
}

Cleanup

Deletion removes:

• Device document from iot_objects
• Device tokens from device_tokens
• HTTP and MQTT auth entries from Redis
• Rule chain reference from Redis