# Device Groups

Download the [specification](https://api.kpnthings.com/openapi-specifications/device-groups).

Device Groups provide a way to organize and manage devices within a project. Each group represents a subset of the project’s registered devices, and a device may belong to multiple groups in the same project. Beyond simple grouping, a Device Group also defines the project’s “processing plan” for incoming device data—known as a *flow* in the Things Manager. A flow brings together four elements: the devices it applies to, the decoders used to interpret their uplinks, encoders used to encode downlinks, and the destinations where decoded messages are forwarded.

At present, the Device Groups API focuses on device membership, allowing you to add or remove devices from a group. Configuration of flows themselves—such as managing decoders, encoders, or destinations—remains available through the Things Manager web interface.

## Retrieve device groups filtered and sorted by specified search and sort criteria

> Retrieve all device groups that match the query parameters given. If a search parameter is provided, device groups whose name or description (partially) match are returned.

```json
{"openapi":"3.1.0","info":{"title":"Things Device Group API","version":"0.9.0"},"servers":[{"url":"https://api.kpnthings.com","description":"Things API Environment"}],"security":[{"BearerAuth":["device-group.read"]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"parameters":{"cursor":{"name":"cursor","in":"query","description":"String that encodes all necessary information to retrieve a page.","style":"form","explode":true,"schema":{"type":"string","format":"cursor"}},"limit":{"name":"limit","in":"query","description":"Limit the number of results (per page).","style":"form","explode":true,"schema":{"type":"integer","default":50}},"sort":{"name":"sort","in":"query","description":"Sorting fields separated by comma. Default order is Ascending (ASC), minus(-) should be used in front of field name for Descending (DESC) order.","style":"form","explode":true,"schema":{"type":"string"}}},"schemas":{"PageOfDeviceGroups":{"type":"object","allOf":[{"$ref":"#/components/schemas/Page"},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/DeviceGroup"}}}}],"description":"A paginated list of device groups","title":"PageOfDeviceGroups"},"Page":{"type":"object","description":"Page of items","properties":{"items":{"type":"array","items":{}},"next":{"type":"string","format":"uri","description":"Pagination link pointing to the next page. Only provided when not at the last page."},"prev":{"type":"string","format":"uri","description":"Pagination link pointing to the previous page. Only provided when not at the first page."}},"required":["items"],"title":"Page"},"DeviceGroup":{"type":"object","description":"A group of devices.","properties":{"id":{"type":"string","format":"uuid","description":"The unique identifier of the device group.","readOnly":true},"name":{"type":"string","description":"The name of the device group.","maxLength":255,"minLength":1},"description":{"type":"string","description":"A description of the device group.","maxLength":255},"projectId":{"type":"string","format":"uuid","description":"The project identifier to which this device group belongs."},"createdAt":{"type":"string","format":"date-time","description":"The timestamp when the device group is created in the system.","readOnly":true},"createdBy":{"type":"string","description":"The user who created the device group.","readOnly":true},"modifiedAt":{"type":"string","format":"date-time","description":"The timestamp when the device group is last modified in the system.","readOnly":true},"modifiedBy":{"type":"string","description":"The user who last modified the device group.","readOnly":true}},"required":["name","projectId"],"title":"DeviceGroup"}}},"paths":{"/device-groups":{"get":{"summary":"Retrieve device groups filtered and sorted by specified search and sort criteria","description":"Retrieve all device groups that match the query parameters given. If a search parameter is provided, device groups whose name or description (partially) match are returned.","operationId":"searchDeviceGroups","parameters":[{"$ref":"#/components/parameters/cursor"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/sort"},{"name":"q","in":"query","description":"Include only device groups whose names or descriptions contain the search term. Matching is done case-insensitively.","style":"form","explode":true,"schema":{"type":"string"}},{"name":"clientId","in":"query","description":"Include only device groups owned by the client with the provided clientId. If clientId is omitted, all device groups are included that are accessible to the caller.","style":"form","explode":true,"schema":{"type":"string","format":"uuid"}},{"name":"projectId","in":"query","description":"Include only device groups associated with the project with the provided projectId. If projectId is omitted, all device groups are included that are accessible to the caller.","style":"form","explode":true,"schema":{"type":"string","format":"uuid"}},{"name":"createdBefore","in":"query","description":"Include only device groups created before the provided date and time. The date-time must be in ISO 8601 format.","style":"form","explode":true,"schema":{"type":"string","format":"date-time"}},{"name":"createdSince","in":"query","description":"Include only device groups created at or after the provided date and time. The date-time must be in ISO 8601 format.","style":"form","explode":true,"schema":{"type":"string","format":"date-time"}},{"name":"modifiedBefore","in":"query","description":"Include only device groups modified before the provided date and time. The date-time must be in ISO 8601 format.","style":"form","explode":true,"schema":{"type":"string","format":"date-time"}},{"name":"modifiedSince","in":"query","description":"Include only device groups modified at or after the provided date and time. The date-time must be in ISO 8601 format.","style":"form","explode":true,"schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"A list of device groups matching the search criteria.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PageOfDeviceGroups"}}}}}}}}}
```

## POST /device-groups

> Create a new device group

```json
{"openapi":"3.1.0","info":{"title":"Things Device Group API","version":"0.9.0"},"servers":[{"url":"https://api.kpnthings.com","description":"Things API Environment"}],"security":[{"BearerAuth":["device-group.write"]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"DeviceGroup":{"type":"object","description":"A group of devices.","properties":{"id":{"type":"string","format":"uuid","description":"The unique identifier of the device group.","readOnly":true},"name":{"type":"string","description":"The name of the device group.","maxLength":255,"minLength":1},"description":{"type":"string","description":"A description of the device group.","maxLength":255},"projectId":{"type":"string","format":"uuid","description":"The project identifier to which this device group belongs."},"createdAt":{"type":"string","format":"date-time","description":"The timestamp when the device group is created in the system.","readOnly":true},"createdBy":{"type":"string","description":"The user who created the device group.","readOnly":true},"modifiedAt":{"type":"string","format":"date-time","description":"The timestamp when the device group is last modified in the system.","readOnly":true},"modifiedBy":{"type":"string","description":"The user who last modified the device group.","readOnly":true}},"required":["name","projectId"],"title":"DeviceGroup"}}},"paths":{"/device-groups":{"post":{"summary":"Create a new device group","operationId":"createDeviceGroup","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeviceGroup"}}},"required":true},"responses":{"201":{"description":"Device group has been created successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeviceGroup"}}}}}}}}}
```

## Retrieve a device group by its ID

> Retrieve a device group by its ID. The device group must be accessible to the caller.

```json
{"openapi":"3.1.0","info":{"title":"Things Device Group API","version":"0.9.0"},"servers":[{"url":"https://api.kpnthings.com","description":"Things API Environment"}],"security":[{"BearerAuth":["device-group.read"]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"DeviceGroup":{"type":"object","description":"A group of devices.","properties":{"id":{"type":"string","format":"uuid","description":"The unique identifier of the device group.","readOnly":true},"name":{"type":"string","description":"The name of the device group.","maxLength":255,"minLength":1},"description":{"type":"string","description":"A description of the device group.","maxLength":255},"projectId":{"type":"string","format":"uuid","description":"The project identifier to which this device group belongs."},"createdAt":{"type":"string","format":"date-time","description":"The timestamp when the device group is created in the system.","readOnly":true},"createdBy":{"type":"string","description":"The user who created the device group.","readOnly":true},"modifiedAt":{"type":"string","format":"date-time","description":"The timestamp when the device group is last modified in the system.","readOnly":true},"modifiedBy":{"type":"string","description":"The user who last modified the device group.","readOnly":true}},"required":["name","projectId"],"title":"DeviceGroup"}}},"paths":{"/device-groups/{deviceGroupId}":{"get":{"summary":"Retrieve a device group by its ID","description":"Retrieve a device group by its ID. The device group must be accessible to the caller.","operationId":"getDeviceGroup","parameters":[{"name":"deviceGroupId","in":"path","description":"The ID of the device group to retrieve.","required":true,"style":"simple","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The requested device group.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeviceGroup"}}}}}}}}}
```

## PUT /device-groups/{deviceGroupId}

> Update an existing device group

```json
{"openapi":"3.1.0","info":{"title":"Things Device Group API","version":"0.9.0"},"servers":[{"url":"https://api.kpnthings.com","description":"Things API Environment"}],"security":[{"BearerAuth":["device-group.write"]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"DeviceGroup":{"type":"object","description":"A group of devices.","properties":{"id":{"type":"string","format":"uuid","description":"The unique identifier of the device group.","readOnly":true},"name":{"type":"string","description":"The name of the device group.","maxLength":255,"minLength":1},"description":{"type":"string","description":"A description of the device group.","maxLength":255},"projectId":{"type":"string","format":"uuid","description":"The project identifier to which this device group belongs."},"createdAt":{"type":"string","format":"date-time","description":"The timestamp when the device group is created in the system.","readOnly":true},"createdBy":{"type":"string","description":"The user who created the device group.","readOnly":true},"modifiedAt":{"type":"string","format":"date-time","description":"The timestamp when the device group is last modified in the system.","readOnly":true},"modifiedBy":{"type":"string","description":"The user who last modified the device group.","readOnly":true}},"required":["name","projectId"],"title":"DeviceGroup"}}},"paths":{"/device-groups/{deviceGroupId}":{"put":{"summary":"Update an existing device group","operationId":"setDeviceGroup","parameters":[{"name":"deviceGroupId","in":"path","description":"The ID of the device group to update.","required":true,"style":"simple","schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeviceGroup"}}},"required":true},"responses":{"200":{"description":"Device group has been updated successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeviceGroup"}}}}}}}}}
```

## DELETE /device-groups/{deviceGroupId}

> Delete a device group by its ID

```json
{"openapi":"3.1.0","info":{"title":"Things Device Group API","version":"0.9.0"},"servers":[{"url":"https://api.kpnthings.com","description":"Things API Environment"}],"security":[{"BearerAuth":["device-group.delete"]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}}},"paths":{"/device-groups/{deviceGroupId}":{"delete":{"summary":"Delete a device group by its ID","operationId":"deleteDeviceGroup","parameters":[{"name":"deviceGroupId","in":"path","description":"The ID of the device group to delete.","required":true,"style":"simple","schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Device group has been deleted successfully."}}}}}}
```

## Retrieve the devices linked to a device group

> Retrieve all devices linked to a device group. The device group must be accessible to the caller.

```json
{"openapi":"3.1.0","info":{"title":"Things Device Group API","version":"0.9.0"},"servers":[{"url":"https://api.kpnthings.com","description":"Things API Environment"}],"security":[{"BearerAuth":["device-group.read"]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"parameters":{"cursor":{"name":"cursor","in":"query","description":"String that encodes all necessary information to retrieve a page.","style":"form","explode":true,"schema":{"type":"string","format":"cursor"}},"limit":{"name":"limit","in":"query","description":"Limit the number of results (per page).","style":"form","explode":true,"schema":{"type":"integer","default":50}},"sort":{"name":"sort","in":"query","description":"Sorting fields separated by comma. Default order is Ascending (ASC), minus(-) should be used in front of field name for Descending (DESC) order.","style":"form","explode":true,"schema":{"type":"string"}}},"schemas":{"PageOfDeviceGroupDeviceLinks":{"type":"object","allOf":[{"$ref":"#/components/schemas/Page"},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/DeviceGroupDeviceLinkResponse"}}}}],"description":"A paginated list of device group to device links","title":"PageOfDeviceGroupDeviceLinks"},"Page":{"type":"object","description":"Page of items","properties":{"items":{"type":"array","items":{}},"next":{"type":"string","format":"uri","description":"Pagination link pointing to the next page. Only provided when not at the last page."},"prev":{"type":"string","format":"uri","description":"Pagination link pointing to the previous page. Only provided when not at the first page."}},"required":["items"],"title":"Page"},"DeviceGroupDeviceLinkResponse":{"type":"object","allOf":[{"$ref":"#/components/schemas/DeviceGroupDeviceLink"},{"type":"object","description":"Embedded items for the device group - device link","properties":{"_embedded":{"type":"object","properties":{"deviceGroup":{"$ref":"#/components/schemas/DeviceGroup"},"device":{"$ref":"#/components/schemas/Device"}}}}}],"description":"DeviceGroupDeviceLink with optional embedded entities","title":"DeviceGroupDeviceLinkResponse"},"DeviceGroupDeviceLink":{"type":"object","description":"A link between a device group and a device.","properties":{"deviceGroupId":{"type":"string","format":"uuid","description":"The identifier of the device group.","readOnly":true},"deviceId":{"$ref":"#/components/schemas/DeviceId"},"createdAt":{"type":"string","format":"date-time","description":"The timestamp when the device link was created in the system.","readOnly":true},"createdBy":{"type":"string","description":"The user who created the device link.","readOnly":true}},"title":"DeviceGroupDeviceLink"},"DeviceId":{"type":"string","format":"device-id","description":"A device identifier in one of several supported formats.","oneOf":[{"$ref":"#/components/schemas/DeviceId-uuid"},{"$ref":"#/components/schemas/DeviceId-imei"},{"$ref":"#/components/schemas/DeviceId-deveui"},{"$ref":"#/components/schemas/DeviceId-dvnuuid"},{"$ref":"#/components/schemas/DeviceUrn-imei"},{"$ref":"#/components/schemas/DeviceUrn-deveui"},{"$ref":"#/components/schemas/DeviceUrn-dvnuuid"}],"title":"DeviceId"},"DeviceId-uuid":{"type":"string","format":"uuid","description":"Things Device UUID","title":"UuidDeviceId"},"DeviceId-imei":{"type":"string","description":"IMEI-based device ID","pattern":"(?i)^imei:[0-9]{15,16}$","title":"ImeiDeviceId"},"DeviceId-deveui":{"type":"string","description":"LoRaWAN DevEUI device ID","pattern":"(?i)^deveui:[a-f0-9]{16}$","title":"DevEuiDeviceId"},"DeviceId-dvnuuid":{"type":"string","description":"DVNUUID-based device ID","pattern":"(?i)^dvnuuid:[a-f0-9]{8}(-[a-f0-9]{4}){3}-[a-f0-9]{12}?$","title":"DvnUuidDeviceId"},"DeviceUrn-imei":{"type":"string","description":"IMEI-based device URN","pattern":"(?i)^urn:dev:imei:[0-9]{15,16}:?$","title":"ImeiDeviceUrn"},"DeviceUrn-deveui":{"type":"string","description":"LoRaWAN DevEUI device URN","pattern":"(?i)^urn:dev:deveui:[a-f0-9]{16}:?$","title":"DevEuiDeviceUrn"},"DeviceUrn-dvnuuid":{"type":"string","description":"DVNUUID-based device URN","pattern":"(?i)^urn:dev:dvnuuid:[a-f0-9]{8}(-[a-f0-9]{4}){3}-[a-f0-9]{12}:?$","title":"DvnUuidDeviceUrn"},"DeviceGroup":{"type":"object","description":"A group of devices.","properties":{"id":{"type":"string","format":"uuid","description":"The unique identifier of the device group.","readOnly":true},"name":{"type":"string","description":"The name of the device group.","maxLength":255,"minLength":1},"description":{"type":"string","description":"A description of the device group.","maxLength":255},"projectId":{"type":"string","format":"uuid","description":"The project identifier to which this device group belongs."},"createdAt":{"type":"string","format":"date-time","description":"The timestamp when the device group is created in the system.","readOnly":true},"createdBy":{"type":"string","description":"The user who created the device group.","readOnly":true},"modifiedAt":{"type":"string","format":"date-time","description":"The timestamp when the device group is last modified in the system.","readOnly":true},"modifiedBy":{"type":"string","description":"The user who last modified the device group.","readOnly":true}},"required":["name","projectId"],"title":"DeviceGroup"},"Device":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The id of the device","readOnly":true},"createdAt":{"type":"string","format":"date-time","description":"The timestamp when the device is created in the system.","readOnly":true},"createdBy":{"type":"string","description":"The user who created the device.","readOnly":true},"modifiedAt":{"type":"string","format":"date-time","description":"The timestamp when the device is last modified in the system.","readOnly":true},"modifiedBy":{"type":"string","description":"The user who last modified the device.","readOnly":true},"name":{"type":"string","description":"Name of this device","maxLength":255,"minLength":1,"pattern":"^(?!\\s*$).+"},"status":{"$ref":"#/components/schemas/DeviceStatus"},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"A JSON object containing key-value metadata"},"barcode":{"type":"string","description":"Barcode of the device"},"description":{"type":"string","description":"Description of this device","maxLength":255},"clientId":{"type":"string","format":"uuid","description":"ID of owning client"},"projectId":{"type":"string","format":"uuid","description":"ID of the project the device belongs to"},"deviceSpecificationId":{"type":"string","format":"uuid","description":"ID of the device specification of the device"},"networkAdapters":{"type":"array","description":"List of network adapters attached to the device","items":{"$ref":"#/components/schemas/NetworkAdapter"}}},"required":["clientId","deviceSpecificationId","name","projectId"],"title":"Device"},"DeviceStatus":{"type":"string","description":"Status of the device. Known values include: ACTIVE and INACTIVE"},"NetworkAdapter":{"type":"object","description":"A network adapter","discriminator":{"propertyName":"type","mapping":{"cellular":"#/components/schemas/CellularNetworkAdapter","generic":"#/components/schemas/GenericNetworkAdapter","lora":"#/components/schemas/LoraNetworkAdapter"}},"oneOf":[{"$ref":"#/components/schemas/CellularNetworkAdapter"},{"$ref":"#/components/schemas/GenericNetworkAdapter"},{"$ref":"#/components/schemas/LoraNetworkAdapter"}],"properties":{"type":{"type":"string","description":"The type of network adapter. Known values are: cellular, generic and lora"},"urn":{"description":"The URN for this network adapter","readOnly":true}},"required":["type","urn"],"title":"NetworkAdapter"},"CellularNetworkAdapter":{"type":"object","description":"Network adapter used to connect to cellular (mobile) networks","properties":{"id":{"type":"string","format":"uuid","description":"The id of the network adapter","readOnly":true},"type":{"type":"string","description":"The type of network adapter; must be 'cellular' for CellularNetworkAdapter"},"createdAt":{"type":"string","format":"date-time","description":"The timestamp when the network adapter is created in the system.","readOnly":true},"createdBy":{"type":"string","description":"The user who created the network adapter.","readOnly":true},"modifiedAt":{"type":"string","format":"date-time","description":"The timestamp when the network adapter is last modified in the system.","readOnly":true},"modifiedBy":{"type":"string","description":"The user who last modified the network adapter.","readOnly":true},"imei":{"type":"string","description":"The International Mobile Equipment Identity (IMEI) that identifies the cellular adapter","maxLength":16,"minLength":15},"iccId":{"type":"string","description":"The Integrated Circuit Card Identifier (ICCID) that identifies the SIM chip","maxLength":22,"minLength":18},"urn":{"type":"string","description":"The URN for this network adapter","readOnly":true}},"required":["imei","type"],"title":"CellularNetworkAdapter"},"GenericNetworkAdapter":{"type":"object","description":"Generic network adapter that provides access to the public Internet","properties":{"id":{"type":"string","format":"uuid","description":"The id of the network adapter","readOnly":true},"type":{"type":"string","description":"The type of network adapter; must be 'generic' for GenericNetworkAdapter"},"createdAt":{"type":"string","format":"date-time","description":"The timestamp when the network adapter is created in the system.","readOnly":true},"createdBy":{"type":"string","description":"The user who created the network adapter.","readOnly":true},"modifiedAt":{"type":"string","format":"date-time","description":"The timestamp when the network adapter is last modified in the system.","readOnly":true},"modifiedBy":{"type":"string","description":"The user who last modified the network adapter.","readOnly":true},"dvnUuid":{"type":"string","format":"uuid","description":"The unique identifier for this network adapter; defaults to the device ID, but may be set to a different value"},"urn":{"type":"string","description":"The URN for this network adapter","readOnly":true}},"required":["dvnUuid","type"],"title":"GenericNetworkAdapter"},"LoraNetworkAdapter":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The id of the network adapter","readOnly":true},"type":{"type":"string","description":"The type of network adapter; must be 'lora' for LoraNetworkAdapter"},"createdAt":{"type":"string","format":"date-time","description":"The timestamp when the network adapter is created in the system.","readOnly":true},"createdBy":{"type":"string","description":"The user who created the network adapter.","readOnly":true},"modifiedAt":{"type":"string","format":"date-time","description":"The timestamp when the network adapter is last modified in the system.","readOnly":true},"modifiedBy":{"type":"string","description":"The user who last modified the network adapter.","readOnly":true},"devEui":{"type":"string","description":"The Device Extended Unique Identifier (DevEUI) that identifies the LoRa node","maxLength":16},"urn":{"type":"string","description":"The URN for this network adapter","readOnly":true}},"required":["devEui","type"],"title":"LoraNetworkAdapter"}}},"paths":{"/device-groups/{deviceGroupId}/devices":{"get":{"summary":"Retrieve the devices linked to a device group","description":"Retrieve all devices linked to a device group. The device group must be accessible to the caller.","operationId":"listDevicesInDeviceGroup","parameters":[{"name":"deviceGroupId","in":"path","description":"The ID of the device group for which to retrieve linked devices.","required":true,"style":"simple","schema":{"type":"string","format":"uuid"}},{"name":"createdBefore","in":"query","description":"Include only links created before the provided date and time. The date-time must be in ISO 8601 format.","style":"form","explode":true,"schema":{"type":"string","format":"date-time"}},{"name":"createdSince","in":"query","description":"Include only links created at or after the provided date and time. The date-time must be in ISO 8601 format.","style":"form","explode":true,"schema":{"type":"string","format":"date-time"}},{"name":"embed","in":"query","description":"results to embed in the response","style":"form","explode":true,"schema":{"type":"array","items":{"type":"string","enum":["device","deviceGroup"]}}},{"$ref":"#/components/parameters/cursor"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/sort"}],"responses":{"200":{"description":"Page of devices linked to the specified device group.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PageOfDeviceGroupDeviceLinks"}}}}}}}}}
```

## POST /device-groups/{deviceGroupId}/devices

> Link a device to a device group

```json
{"openapi":"3.1.0","info":{"title":"Things Device Group API","version":"0.9.0"},"servers":[{"url":"https://api.kpnthings.com","description":"Things API Environment"}],"security":[{"BearerAuth":["device-group.write"]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"DeviceGroupDeviceLink":{"type":"object","description":"A link between a device group and a device.","properties":{"deviceGroupId":{"type":"string","format":"uuid","description":"The identifier of the device group.","readOnly":true},"deviceId":{"$ref":"#/components/schemas/DeviceId"},"createdAt":{"type":"string","format":"date-time","description":"The timestamp when the device link was created in the system.","readOnly":true},"createdBy":{"type":"string","description":"The user who created the device link.","readOnly":true}},"title":"DeviceGroupDeviceLink"},"DeviceId":{"type":"string","format":"device-id","description":"A device identifier in one of several supported formats.","oneOf":[{"$ref":"#/components/schemas/DeviceId-uuid"},{"$ref":"#/components/schemas/DeviceId-imei"},{"$ref":"#/components/schemas/DeviceId-deveui"},{"$ref":"#/components/schemas/DeviceId-dvnuuid"},{"$ref":"#/components/schemas/DeviceUrn-imei"},{"$ref":"#/components/schemas/DeviceUrn-deveui"},{"$ref":"#/components/schemas/DeviceUrn-dvnuuid"}],"title":"DeviceId"},"DeviceId-uuid":{"type":"string","format":"uuid","description":"Things Device UUID","title":"UuidDeviceId"},"DeviceId-imei":{"type":"string","description":"IMEI-based device ID","pattern":"(?i)^imei:[0-9]{15,16}$","title":"ImeiDeviceId"},"DeviceId-deveui":{"type":"string","description":"LoRaWAN DevEUI device ID","pattern":"(?i)^deveui:[a-f0-9]{16}$","title":"DevEuiDeviceId"},"DeviceId-dvnuuid":{"type":"string","description":"DVNUUID-based device ID","pattern":"(?i)^dvnuuid:[a-f0-9]{8}(-[a-f0-9]{4}){3}-[a-f0-9]{12}?$","title":"DvnUuidDeviceId"},"DeviceUrn-imei":{"type":"string","description":"IMEI-based device URN","pattern":"(?i)^urn:dev:imei:[0-9]{15,16}:?$","title":"ImeiDeviceUrn"},"DeviceUrn-deveui":{"type":"string","description":"LoRaWAN DevEUI device URN","pattern":"(?i)^urn:dev:deveui:[a-f0-9]{16}:?$","title":"DevEuiDeviceUrn"},"DeviceUrn-dvnuuid":{"type":"string","description":"DVNUUID-based device URN","pattern":"(?i)^urn:dev:dvnuuid:[a-f0-9]{8}(-[a-f0-9]{4}){3}-[a-f0-9]{12}:?$","title":"DvnUuidDeviceUrn"}}},"paths":{"/device-groups/{deviceGroupId}/devices":{"post":{"summary":"Link a device to a device group","operationId":"addDeviceToDeviceGroup","parameters":[{"name":"deviceGroupId","in":"path","description":"The ID of the device group for which to retrieve linked devices.","required":true,"style":"simple","schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeviceGroupDeviceLink"}}},"required":true},"responses":{"200":{"description":"Device has been linked to the device group successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeviceGroupDeviceLink"}}}}}}}}}
```

## DELETE /device-groups/{deviceGroupId}/devices/{deviceId}

> Unlink a device from a device group

```json
{"openapi":"3.1.0","info":{"title":"Things Device Group API","version":"0.9.0"},"servers":[{"url":"https://api.kpnthings.com","description":"Things API Environment"}],"security":[{"BearerAuth":["device-group.delete"]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"DeviceId":{"type":"string","format":"device-id","description":"A device identifier in one of several supported formats.","oneOf":[{"$ref":"#/components/schemas/DeviceId-uuid"},{"$ref":"#/components/schemas/DeviceId-imei"},{"$ref":"#/components/schemas/DeviceId-deveui"},{"$ref":"#/components/schemas/DeviceId-dvnuuid"},{"$ref":"#/components/schemas/DeviceUrn-imei"},{"$ref":"#/components/schemas/DeviceUrn-deveui"},{"$ref":"#/components/schemas/DeviceUrn-dvnuuid"}],"title":"DeviceId"},"DeviceId-uuid":{"type":"string","format":"uuid","description":"Things Device UUID","title":"UuidDeviceId"},"DeviceId-imei":{"type":"string","description":"IMEI-based device ID","pattern":"(?i)^imei:[0-9]{15,16}$","title":"ImeiDeviceId"},"DeviceId-deveui":{"type":"string","description":"LoRaWAN DevEUI device ID","pattern":"(?i)^deveui:[a-f0-9]{16}$","title":"DevEuiDeviceId"},"DeviceId-dvnuuid":{"type":"string","description":"DVNUUID-based device ID","pattern":"(?i)^dvnuuid:[a-f0-9]{8}(-[a-f0-9]{4}){3}-[a-f0-9]{12}?$","title":"DvnUuidDeviceId"},"DeviceUrn-imei":{"type":"string","description":"IMEI-based device URN","pattern":"(?i)^urn:dev:imei:[0-9]{15,16}:?$","title":"ImeiDeviceUrn"},"DeviceUrn-deveui":{"type":"string","description":"LoRaWAN DevEUI device URN","pattern":"(?i)^urn:dev:deveui:[a-f0-9]{16}:?$","title":"DevEuiDeviceUrn"},"DeviceUrn-dvnuuid":{"type":"string","description":"DVNUUID-based device URN","pattern":"(?i)^urn:dev:dvnuuid:[a-f0-9]{8}(-[a-f0-9]{4}){3}-[a-f0-9]{12}:?$","title":"DvnUuidDeviceUrn"}}},"paths":{"/device-groups/{deviceGroupId}/devices/{deviceId}":{"delete":{"summary":"Unlink a device from a device group","operationId":"removeDeviceFromDeviceGroup","parameters":[{"name":"deviceGroupId","in":"path","description":"The ID of the device group to unlink the device from.","required":true,"style":"simple","schema":{"type":"string","format":"uuid"}},{"name":"deviceId","in":"path","description":"The ID of the device to unlink from the device group.","required":true,"style":"simple","schema":{"$ref":"#/components/schemas/DeviceId"}}],"responses":{"204":{"description":"Device has been unlinked from the device group successfully."}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.kpnthings.com/kpn-things/general-functions/apis/device-groups.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.