Device Groups API

Manage device groups. Groups are stored in the iot_objects collection with obj_type: 'device_groups'.

---

List Groups

Retrieves a paginated list of device groups.

GET /api/device-groups

Query Parameters

Parameter	Type	Default	Description
page	number	1	Page number
limit	number	10	Items per page
name	string	—	Filter by name (case-insensitive)

Example

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

Response

{
  "success": true,
  "data": [
    {
      "_id": "663d1a8f1234567890abcdef",
      "name": "default",
      "label": "Default Group",
      "description": "Default device group",
      "obj_type": "device_groups",
      "clientId": "664a1b2c3d4e5f6a7b8c9d0a",
      "owner": "664a1b2c3d4e5f6a7b8c9d0b",
      "created_at": "2025-01-15T10:30:00.000Z",
      "updated_at": "2025-01-15T10:30:00.000Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 10
}

---

Get Group

Retrieves a single device group by ID.

GET /api/device-groups?id=<group_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/device-groups?id=663d1a8f1234567890abcdef"

Response

{
  "success": true,
  "data": {
    "_id": "663d1a8f1234567890abcdef",
    "name": "default",
    "label": "Default Group",
    "obj_type": "device_groups",
    "clientId": "664a1b2c3d4e5f6a7b8c9d0a",
    "owner": "664a1b2c3d4e5f6a7b8c9d0b",
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-15T10:30:00.000Z"
  }
}

---

Create Group

Creates a new device group.

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

Request Body

Field	Type	Required	Description
name	string	yes	Group name
label	string	no	Display label
description	string	no	Description
owner	string	yes	User Object ID (24 hex)

Example

curl -X POST -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Warehouse Sensors",
    "label": "Warehouse A",
    "description": "All sensors in Warehouse A",
    "owner": "664a1b2c3d4e5f6a7b8c9d0b"
  }' \
  "http://localhost:9001/api/device-groups?id=new"

Response

{
  "success": true
}

---

Update Group

Updates an existing device group.

POST /api/device-groups?id=<group_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	Group name
label	string	no	Display label
description	string	no	Description
owner	string	yes	User Object ID

Example

curl -X POST -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Warehouse Sensors",
    "label": "Warehouse B",
    "description": "Moved to Warehouse B",
    "owner": "664a1b2c3d4e5f6a7b8c9d0b"
  }' \
  "http://localhost:9001/api/device-groups?id=663d1a8f1234567890abcdef"

Response

{
  "success": true
}

---

Delete Group

Deletes a device group.

DELETE /api/device-groups?id=<group_id>

Query Parameters

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

Note: Deleting a group does not delete or unlink the devices that reference it.

Example

curl -X DELETE -H "Authorization: Bearer <key>" \
  "http://localhost:9001/api/device-groups?id=663d1a8f1234567890abcdef"

Response

{
  "success": true
}