Device Groups - Lamassu IoT

Device groups enable dynamic organization of devices using flexible filter criteria. Groups automatically populate based on device attributes like tags, status, DMS, and metadata. Groups can be organized hierarchically with parent-child relationships, where child groups inherit criteria from their ancestors.

List Device Groups

Retrieve all device groups with optional pagination, sorting, and filtering.

Query Parameters

page_size

integer

default:"25"

Number of results per page

bookmark

string

Pagination token from previous response

sort_by

string

Field name to sort by (e.g., name, created_at, updated_at)

sort_mode

string

Sort direction: asc or desc

filter

string

Filter expression. Supports:

id - Group identifier
name - Group name
parent_id - Parent group identifier
created_at - Creation timestamp
updated_at - Last update timestamp

Response

string

Bookmark for the next page

list

array

Array of device group objects

string

Group identifier (UUID)

name

string

Group name

description

string

Group description

parent_id

string

Parent group ID (null for root groups)

criteria

array

Filter criteria defined for this group

field

string

Device field to filter (id, dms_owner, status, tags, creation_timestamp, metadata)

operand

string

Filter operator (contains, eq, ne, etc.)

value

string

Filter value

inherited_criteria

array

Filters inherited from ancestor groups (composed root to parent)

created_at

string

ISO 8601 creation timestamp

updated_at

string

ISO 8601 last update timestamp

Example Request

curl -X GET "https://your-instance.com/api/devmanager/v1/device-groups" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Example Response

{
  "next": "",
  "list": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Production Devices",
      "description": "All production environment devices",
      "parent_id": null,
      "criteria": [
        {
          "field": "tags",
          "operand": "contains",
          "value": "production"
        }
      ],
      "inherited_criteria": [],
      "created_at": "2026-01-15T10:00:00Z",
      "updated_at": "2026-01-15T10:00:00Z"
    },
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "name": "Production Sensors",
      "description": "Production sensors only",
      "parent_id": "550e8400-e29b-41d4-a716-446655440000",
      "criteria": [
        {
          "field": "tags",
          "operand": "contains",
          "value": "sensor"
        }
      ],
      "inherited_criteria": [
        {
          "field": "tags",
          "operand": "contains",
          "value": "production"
        }
      ],
      "created_at": "2026-01-15T11:00:00Z",
      "updated_at": "2026-01-15T11:00:00Z"
    }
  ]
}

Create Device Group

Create a new device group with optional parent and filter criteria.

Request Body

string

required

Unique group identifier (UUID format)

name

string

required

Group name (1-255 characters)

description

string

Group description

parent_id

string

Parent group ID for hierarchical organization (null for root groups)

criteria

array

required

Filter criteria array. Each criterion includes:

field

string

required

Device field: id, dms_owner, status, tags, creation_timestamp, or metadata

operand

string

required

Filter operator. Supported operators by field type:String fields (id, dms_owner):

eq, equal - Exact match (case-sensitive)
eq_ic, equal_ignorecase - Exact match (case-insensitive)
ne, notequal - Not equal (case-sensitive)
ne_ic, notequal_ignorecase - Not equal (case-insensitive)
ct, contains - Contains substring (case-sensitive)
ct_ic, contains_ignorecase - Contains substring (case-insensitive)
nc, notcontains - Does not contain (case-sensitive)
nc_ic, notcontains_ignorecase - Does not contain (case-insensitive)

Array fields (tags):

contains - Array contains value (case-sensitive)
contains_ignorecase - Array contains value (case-insensitive)

Date fields (creation_timestamp):

eq, equal - Exact date match
bf, before - Before date
af, after - After date

Enum fields (status):

eq, equal - Exact match
ne, notequal - Not equal

JSON fields (metadata):

jsonpath - JSONPath expression

value

string

required

Value to compare against

Response

Returns the created device group object including:

criteria: The filters specified in the request
inherited_criteria: All filters from ancestor groups (parent, grandparent, etc.)

Example: Create Root Group

curl -X POST "https://your-instance.com/api/devmanager/v1/device-groups" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Production Devices",
    "description": "All production environment devices",
    "criteria": [
      {
        "field": "tags",
        "operand": "contains",
        "value": "production"
      }
    ]
  }'

Example: Create Nested Group

curl -X POST "https://your-instance.com/api/devmanager/v1/device-groups" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "name": "Active Production Sensors",
    "description": "Active sensors in production",
    "parent_id": "550e8400-e29b-41d4-a716-446655440000",
    "criteria": [
      {
        "field": "tags",
        "operand": "contains",
        "value": "sensor"
      },
      {
        "field": "status",
        "operand": "eq",
        "value": "ACTIVE"
      }
    ]
  }'

Get Device Group by ID

Retrieve a specific device group by identifier.

Path Parameters

string

required

Device group identifier (UUID)

Response

Returns the device group object including:

criteria: Filters defined for this group
inherited_criteria: Filters from ancestor groups

Example Request

curl -X GET "https://your-instance.com/api/devmanager/v1/device-groups/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Update Device Group

Update an existing device group’s name, description, parent, or criteria.

Path Parameters

string

required

Device group identifier (UUID)

Request Body

name

string

Updated group name (1-255 characters)

description

string

Updated description

parent_id

string

Updated parent group ID (validated for circular references)

criteria

array

Updated filter criteria (same format as create)

Response

Returns the updated device group with all filters from the hierarchy.

Example Request

curl -X PUT "https://your-instance.com/api/devmanager/v1/device-groups/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Devices (Updated)",
    "description": "Updated description",
    "criteria": [
      {
        "field": "tags",
        "operand": "contains",
        "value": "production"
      },
      {
        "field": "status",
        "operand": "eq",
        "value": "ACTIVE"
      }
    ]
  }'

Delete Device Group

Delete a device group. Child groups are not automatically deleted.

Path Parameters

string

required

Device group identifier (UUID)

Response

Returns 204 No Content on success.

Example Request

curl -X DELETE "https://your-instance.com/api/devmanager/v1/device-groups/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Get Devices in Group

Retrieve all devices matching the group’s filter criteria. Criteria are inherited and composed from parent groups in the hierarchy.

Path Parameters

string

required

Device group identifier (UUID)

Query Parameters

page_size

integer

default:"25"

Number of results per page

bookmark

string

Pagination token from previous response

sort_by

string

Field name to sort by

sort_mode

string

Sort direction: asc or desc

filter

string

Additional filter expressions (applied on top of group criteria)

Response

Returns the same structure as List Devices.

Example Request

curl -X GET "https://your-instance.com/api/devmanager/v1/device-groups/660e8400-e29b-41d4-a716-446655440001/devices?page_size=50" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Example Response

{
  "next": "",
  "list": [
    {
      "id": "dev-001",
      "tags": ["production", "sensor", "temperature"],
      "status": "ACTIVE",
      "icon": "thermometer",
      "icon_color": "#FF5733",
      "creation_timestamp": "2026-01-10T08:00:00Z",
      "metadata": {
        "location": "warehouse-a"
      },
      "dms_owner": "dms-prod"
    }
  ]
}

Get Device Group Statistics

Retrieve statistics for devices matching the group’s filter criteria, including total count and status distribution.

Path Parameters

string

required

Device group identifier (UUID)

Response

total_devices

integer

Total number of devices in the group

devices_status

object

Device count per status. Keys are status types:

NO_IDENTITY
ACTIVE
RENEWAL_WINDOW
ABOUT_TO_EXPIRE
EXPIRED
REVOKED
DECOMMISSIONED

Example Request

curl -X GET "https://your-instance.com/api/devmanager/v1/device-groups/660e8400-e29b-41d4-a716-446655440001/stats" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Example Response

{
  "total_devices": 150,
  "devices_status": {
    "NO_IDENTITY": 10,
    "ACTIVE": 100,
    "RENEWAL_WINDOW": 15,
    "ABOUT_TO_EXPIRE": 5,
    "EXPIRED": 8,
    "REVOKED": 7,
    "DECOMMISSIONED": 5
  }
}

Hierarchical Group Examples

Three-Level Hierarchy

Create a three-level group hierarchy:

# Level 1: Production devices (root)
curl -X POST "https://your-instance.com/api/devmanager/v1/device-groups" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "group-prod",
    "name": "Production",
    "criteria": [{"field": "tags", "operand": "contains", "value": "production"}]
  }'

# Level 2: Production sensors (child of Production)
curl -X POST "https://your-instance.com/api/devmanager/v1/device-groups" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "group-prod-sensors",
    "name": "Production Sensors",
    "parent_id": "group-prod",
    "criteria": [{"field": "tags", "operand": "contains", "value": "sensor"}]
  }'

# Level 3: Active production temperature sensors (child of Production Sensors)
curl -X POST "https://your-instance.com/api/devmanager/v1/device-groups" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "group-prod-temp-sensors",
    "name": "Active Production Temperature Sensors",
    "parent_id": "group-prod-sensors",
    "criteria": [
      {"field": "tags", "operand": "contains", "value": "temperature"},
      {"field": "status", "operand": "eq", "value": "ACTIVE"}
    ]
  }'

The bottom-level group will inherit criteria from both ancestors, effectively matching devices with:

Tag contains “production” (from grandparent)
Tag contains “sensor” (from parent)
Tag contains “temperature” (own criteria)
Status equals “ACTIVE” (own criteria)

Filter Root Groups

# Get all root groups (groups with no parent)
curl "https://your-instance.com/api/devmanager/v1/device-groups?filter=parent_id[is_null]:true" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

API Overview

Certificate Authority API

Device Manager API

DMS Manager API

Key Management API

Alerts API

Validation Authority API

​List Device Groups

​Query Parameters

​Response

​Example Request

​Example Response

​Create Device Group

​Request Body

​Response

​Example: Create Root Group

​Example: Create Nested Group

​Get Device Group by ID

​Path Parameters

​Response

​Example Request

​Update Device Group

​Path Parameters

​Request Body

​Response

​Example Request

​Delete Device Group

​Path Parameters

​Response

​Example Request

​Get Devices in Group

​Path Parameters

​Query Parameters

​Response

​Example Request

​Example Response

​Get Device Group Statistics

​Path Parameters

​Response

​Example Request

​Example Response

​Hierarchical Group Examples

​Three-Level Hierarchy

​Filter Root Groups

Build docs developers (and LLMs) love

List Device Groups

Query Parameters

Response

Example Request

Example Response

Create Device Group

Request Body

Response

Example: Create Root Group

Example: Create Nested Group

Get Device Group by ID

Path Parameters

Response

Example Request

Update Device Group

Path Parameters

Request Body

Response

Example Request

Delete Device Group

Path Parameters

Response

Example Request

Get Devices in Group

Path Parameters

Query Parameters

Response

Example Request

Example Response

Get Device Group Statistics

Path Parameters

Response

Example Request

Example Response

Hierarchical Group Examples

Three-Level Hierarchy

Filter Root Groups