Device group

Principle

A group enables to bring devices together. Groups can be used to :

  • ease browsing and sorting on Live Objects web portal.

  • using inventory explorer, count and aggregate your devices fleet, select a sub set (group) of your devices fleet by criterias to manage it.

  • apply different forwarding rules on the data collected from the devices (Cf. "Notifications" section).

  • apply different event processing and alarming rules (Cf. "IoT device and data alarming" chapter).

Groups behave mostly like directories in a filesystem (considering devices are files): a Group can include other groups and devices. For instance a device can only belong to one group at a time. There are however some exceptions to this analogy (see group deletion rules).

Each tenant has a default root group. A group, except root group, must have a parent group and can have subgroups. In the same tenant, the complete path of each group must be unique but several groups can have the same local identifier (pathNode). The complete path enables to have the tree view of your group.

Group object model:

JSON Params Description

id

group unique identifier

pathNode

Optional. local group id in path

path

complete group path

parentId

Optional. parent group identifier

description

Optional. detailed description of the group

created

creation date of the device

updated

last update date of the device

The group id is fixed, but the group path is calculated because he depends on both the pathNode and the location of the group in the tree. Moving a group in the tree logically leads to a modification of the group path.

Example:

{
    "id": "u1z1k8",
    "pathNode": "lyon",
    "path": "/france/lyon",
    "parentId": "P2112f",
    "description": "City of Lyon",
    "created": "2018-02-14T16:53:54.515Z",
    "updated": "2018-02-14T16:53:54.515Z"
}
/id:rootpath:/FranceItaliaParisLyonid:P2112fpathNode:Francepath:/FranceparentId:rootid:u1z1k8pathNode:Lyonpath:/France/LyonparentId:P2112f
Figure 1. Groups tree view

Create a new group

Request

Endpoint:

POST /api/v1/deviceMgt/groups

HTTP Headers:

X-API-Key: <your API key>
Content-Type: application/json
Accept: application/json

Body:

JSON Params Description

pathNode

group local identifier in path (unique for groups with the same parent)

parentId

Optional. reference to group parent (id). Root group by default.

description

Optional. detailed description of the group

Example:

POST /api/v1/deviceMgt/groups
{
    "pathNode":"lyon",
    "parentId":"P2112f",
    "description":"City of Lyon"
}
Response

HTTP Code:

201 CREATED

Body:

Cf. group object model

Error case:

HTTP Code Error code message

400

GENERIC_INVALID_PARAMETER_ERROR

The submitted parameter is invalid.

401

UNAUTHORIZED

Authentication failure.

403

GENERIC_ACTION_FORBIDDEN_ERROR

Request forbidden.

404

DM_GROUP_NOT_FOUND

Group not found

409

DM_GROUP_DUPLICATE

Conflict on group path

Example:

{
    "id": "u1z1k8",
    "pathNode": "lyon",
    "path": "/france/lyon",
    "parentId": "P2112f",
    "description": "City of Lyon",
    "created": "2018-02-14T16:53:54.515Z",
    "updated": "2018-02-14T16:53:54.515Z"
}

Update a group

The path change of a group does not change its content (Devices, Groups).

Request

Endpoint:

PUT /api/v1/deviceMgt/groups/<id>

HTTP Headers:

X-API-Key: <your API key>
Content-Type: application/json
Accept: application/json

Body:

JSON Params Description

pathNode

Optional. group local id in path (unique for groups with the same parent)

parentId

Optional. reference to group parent (id). Root group by default

description

Optional. detailed description of the group

Example:

PUT /api/v1/deviceMgt/groups/u1z1k8
{
    "pathNode":"paris",
    "parentId":"P2112f",
    "description":"City of Paris"
}
Response

HTTP Code:

200 OK

Body:

Cf. group object model

Error case:

HTTP Code Error code message

400

GENERIC_INVALID_PARAMETER_ERROR

The submitted parameter is invalid.

401

UNAUTHORIZED

Authentication failure.

403

GENERIC_ACTION_FORBIDDEN_ERROR

Request forbidden.

404

DM_GROUP_NOT_FOUND

Group not found

Example:

{
    "id": "u1z1k8",
    "pathNode": "paris",
    "path": "/france/paris",
    "parentId": "P2112f",
    "description": "City of Paris",
    "created": "2018-02-14T16:53:54.515Z",
    "updated": "2018-02-15T10:31:26.667Z"
}

List groups

Request

Endpoint:

GET /api/v1/deviceMgt/groups

Query parameters:

Name Description

limit

Optional. maximum number of groups in response. 20 by default.

offset

Optional. the number of entries to skip in the results list. 0 by default.

parentId

Optional. filter list by group’s parent. When a parent is set, only direct children are returned (one level).

groupPath

Optional. filter list by group’s path. When a full path is set, only nodes matching exactly this path are returned. In order to return nodes matching a path and all descendants, you must end the groupPath with /* (ex. /spain/*). In order to return direct children nodes -only- of a path, the groupPath must end with /*/ (ex. /spain/*/).

List Groups Query samples:

QueryParams Returned nodes

?groupPath=/france

/france

?groupPath=/*

/france, /france/lyon,/france/paris, /italia

?groupPath=/france/*

/france, /france/lyon,/france/paris

?groupPath=/france/*/

/france/lyon,/france/paris

?parentId=root

/france, /italia

?parentId=P2112f&groupPath=/*

/france/lyon,/france/paris

?parentId=P2112f&groupPath=/france/*

/france/lyon,/france/paris

?parentId=root&groupPath=/france/*

no result

HTTP Headers:

X-API-Key: <your API key>
Accept: application/json
X-Total-Count: <boolean>

For more info about X-Total-Count, see "API v1 paging" section.

Example:

GET /api/v1/deviceMgt/groups?limit=20&offset=0

Response

HTTP Code:

200 OK

Body:

List of group object model

Example:

[
    {
        "id": "root",
        "path": "/",
        "created": "2017-11-03T15:23:22.771Z",
        "updated": "2017-11-03T15:23:22.771Z"
    },
    {
        "id": "P2112f",
        "pathNode": "france",
        "path": "/france",
        "parentId": "root",
        "description": "",
        "created": "2018-02-14T16:47:37.318Z",
        "updated": "2018-02-14T16:47:37.318Z"
    },
    {
        "id": "u1z1k8",
        "pathNode": "paris",
        "path": "/france/paris",
        "parentId": "P2112f",
        "description": "City of Paris",
        "created": "2018-02-14T16:53:54.515Z",
        "updated": "2018-02-15T10:31:26.667Z"
    }
]

Get a group

Request

Endpoint:

GET /api/v1/deviceMgt/groups/<id>

HTTP Headers:

X-API-Key: <your API key>
Accept: application/json

Example:

GET /api/v1/deviceMgt/groups/u1z1k8
Response

HTTP Code:

200 OK

Body:

Cf. group object model

Error case:

HTTP Code Error code message

404

DM_GROUP_NOT_FOUND

Group not found

Example:

{
    "id": "u1z1k8",
    "pathNode": "paris",
    "path": "/france/paris",
    "parentId": "P2112f",
    "description": "City of Paris",
    "created": "2018-02-14T16:53:54.515Z",
    "updated": "2018-02-15T10:31:26.667Z"
}

Delete a group

You can’t delete a group which has devices.

Request

Endpoint:

DELETE /api/v1/deviceMgt/groups/<id>

HTTP Headers:

X-API-Key: <your API key>
Accept: application/json

Example:

DELETE /api/v1/deviceMgt/groups/u1z1k8

Response

HTTP Code:

204 NO CONTENT

Error case:

HTTP Code Error code message

400

GENERIC_INVALID_PARAMETER_ERROR

The submitted parameter is invalid.

401

UNAUTHORIZED

Authentication failure.

403

DM_GROUP_UNDELETABLE

Group can’t be deleted: contains devices or sub-groups

404

DM_GROUP_NOT_FOUND

Group not found
Version 2026.7.0 • Updated date 2026-08-11 12:37:29 UTC