{"openapi":"3.1.0","info":{"title":"Things Device Group API","description":"This specification describes the Device Group API of the KPN Things Platform.","contact":{"name":"KPN Things Support","url":"https://portal.kpnthings.com/support","email":"iot-developer@kpn.com"},"version":"0.9.0"},"servers":[{"url":"https://api.kpnthings.com","description":"Things API Environment"}],"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","example":null},"example":"Parking sensors device group"},{"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","example":null},"example":"79658ca8-f1ba-4c25-b824-93813e9fba76"},{"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","example":null},"example":"0c86079d-9bf4-41be-9f38-d6c877a27d8c"},{"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","example":null},"example":"2025-05-01T10:00:00.000Z"},{"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","example":null},"example":"2025-05-01T10:00:00.000Z"},{"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","example":null},"example":"2025-05-01T10:00:00.000Z"},{"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","example":null},"example":"2025-05-01T10:00:00.000Z"}],"responses":{"200":{"description":"A list of device groups matching the search criteria.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PageOfDeviceGroups","example":null}}}}},"security":[{"BearerAuth":["device-group.read"]}]},"post":{"summary":"Create a new device group","operationId":"createDeviceGroup","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeviceGroup","example":null}}},"required":true},"responses":{"201":{"description":"Device group has been created successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeviceGroup","example":null}}}}},"security":[{"BearerAuth":["device-group.write"]}]}},"/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","example":null},"example":"0c86079d-9bf4-41be-9f38-d6c877a27d8c"}],"responses":{"200":{"description":"The requested device group.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeviceGroup","example":null}}}}},"security":[{"BearerAuth":["device-group.read"]}]},"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","example":null},"example":"0c86079d-9bf4-41be-9f38-d6c877a27d8c"}],"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","example":null}}}}},"security":[{"BearerAuth":["device-group.write"]}]},"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","example":null},"example":"0c86079d-9bf4-41be-9f38-d6c877a27d8c"}],"responses":{"204":{"description":"Device group has been deleted successfully."}},"security":[{"BearerAuth":["device-group.delete"]}]}},"/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","example":null},"example":"0c86079d-9bf4-41be-9f38-d6c877a27d8c"},{"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","example":null},"example":"2025-05-01T10:00:00.000Z"},{"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","example":null},"example":"2025-05-01T10:00:00.000Z"},{"name":"embed","in":"query","description":"results to embed in the response","style":"form","explode":true,"schema":{"type":"array","items":{"type":"string","enum":["device","deviceGroup"]},"example":null},"example":"device"},{"$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","example":null}}}}},"security":[{"BearerAuth":["device-group.read"]}]},"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","example":null},"example":"0c86079d-9bf4-41be-9f38-d6c877a27d8c"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeviceGroupDeviceLink","example":null}}},"required":true},"responses":{"200":{"description":"Device has been linked to the device group successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeviceGroupDeviceLink","example":null}}}}},"security":[{"BearerAuth":["device-group.write"]}]}},"/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","example":null},"example":"0c86079d-9bf4-41be-9f38-d6c877a27d8c"},{"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","example":null},"example":"f330fd70-5b05-4ae4-8b75-68d819b111ff"}],"responses":{"204":{"description":"Device has been unlinked from the device group successfully."}},"security":[{"BearerAuth":["device-group.delete"]}]}}},"components":{"schemas":{"Page":{"type":"object","description":"Page of items","properties":{"items":{"type":"array","items":{},"example":null},"next":{"type":"string","format":"uri","description":"Pagination link pointing to the next page. Only provided when not at the last page.","example":null},"prev":{"type":"string","format":"uri","description":"Pagination link pointing to the previous page. Only provided when not at the first page.","example":null}},"required":["items"],"title":"Page","example":null},"DeviceGroup":{"type":"object","description":"A group of devices.","properties":{"id":{"type":"string","format":"uuid","description":"The unique identifier of the device group.","example":"36e75427-4c6e-438c-89b5-0cbdb0d4068c","readOnly":true},"name":{"type":"string","description":"The name of the device group.","example":"Parking sensors device group","maxLength":255,"minLength":1},"description":{"type":"string","description":"A description of the device group.","example":"This is a group of devices containing parking sensor devices.","maxLength":255},"projectId":{"type":"string","format":"uuid","description":"The project identifier to which this device group belongs.","example":"12345678-1234-1234-1234-123456789012"},"createdAt":{"type":"string","format":"date-time","description":"The timestamp when the device group is created in the system.","example":"2025-07-01T23:00:00.000Z","readOnly":true},"createdBy":{"type":"string","description":"The user who created the device group.","example":"principal/9ebbb3b1-1b6b-46e7-8d58-bb8fe7ae24d4","readOnly":true},"modifiedAt":{"type":"string","format":"date-time","description":"The timestamp when the device group is last modified in the system.","example":"2025-07-01T23:00:00.000Z","readOnly":true},"modifiedBy":{"type":"string","description":"The user who last modified the device group.","example":"principal/9ebbb3b1-1b6b-46e7-8d58-bb8fe7ae24d4","readOnly":true}},"required":["name","projectId"],"title":"DeviceGroup","example":null},"PageOfDeviceGroups":{"type":"object","allOf":[{"$ref":"#/components/schemas/Page","example":null},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/DeviceGroup"},"example":null}},"example":null}],"description":"A paginated list of device groups","title":"PageOfDeviceGroups","example":null},"DeviceId-uuid":{"type":"string","format":"uuid","description":"Things Device UUID","example":"478a82d4-128f-47a6-aa61-2eac3f2a23ad","title":"UuidDeviceId"},"DeviceId-imei":{"type":"string","description":"IMEI-based device ID","example":"imei:350266800610993","pattern":"(?i)^imei:[0-9]{15,16}$","title":"ImeiDeviceId"},"DeviceId-deveui":{"type":"string","description":"LoRaWAN DevEUI device ID","example":"deveui:ea8fa35e2cf3489f","pattern":"(?i)^deveui:[a-f0-9]{16}$","title":"DevEuiDeviceId"},"DeviceId-dvnuuid":{"type":"string","description":"DVNUUID-based device ID","example":"dvnuuid:ed8b73ac-f48f-4457-8ccc-9926cf28979f","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","example":"urn:dev:imei:350266800610993","pattern":"(?i)^urn:dev:imei:[0-9]{15,16}:?$","title":"ImeiDeviceUrn"},"DeviceUrn-deveui":{"type":"string","description":"LoRaWAN DevEUI device URN","example":"urn:dev:deveui:ea8fa35e2cf3489f","pattern":"(?i)^urn:dev:deveui:[a-f0-9]{16}:?$","title":"DevEuiDeviceUrn"},"DeviceUrn-dvnuuid":{"type":"string","description":"DVNUUID-based device URN","example":"urn:dev:dvnuuid:ed8b73ac-f48f-4457-8ccc-9926cf28979f","pattern":"(?i)^urn:dev:dvnuuid:[a-f0-9]{8}(-[a-f0-9]{4}){3}-[a-f0-9]{12}:?$","title":"DvnUuidDeviceUrn"},"DeviceId":{"type":"string","format":"device-id","description":"A device identifier in one of several supported formats.","oneOf":[{"$ref":"#/components/schemas/DeviceId-uuid","example":null},{"$ref":"#/components/schemas/DeviceId-imei","example":null},{"$ref":"#/components/schemas/DeviceId-deveui","example":null},{"$ref":"#/components/schemas/DeviceId-dvnuuid","example":null},{"$ref":"#/components/schemas/DeviceUrn-imei","example":null},{"$ref":"#/components/schemas/DeviceUrn-deveui","example":null},{"$ref":"#/components/schemas/DeviceUrn-dvnuuid","example":null}],"title":"DeviceId","example":null},"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.","example":"aacaf415-a800-4adb-9258-3e3b671d6492","readOnly":true},"deviceId":{"$ref":"#/components/schemas/DeviceId","example":null},"createdAt":{"type":"string","format":"date-time","description":"The timestamp when the device link was created in the system.","example":"2025-07-01T23:00:00.000Z","readOnly":true},"createdBy":{"type":"string","description":"The user who created the device link.","example":"principal/fe288bc5-8652-4ecc-806b-7cf0c7db085e","readOnly":true}},"title":"DeviceGroupDeviceLink","example":null},"DeviceStatus":{"type":"string","description":"Status of the device. Known values include: ACTIVE and INACTIVE","example":"ACTIVE"},"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","example":"d2118182-1f9b-489f-b734-f964b0355d91","readOnly":true},"type":{"type":"string","description":"The type of network adapter; must be 'cellular' for CellularNetworkAdapter","example":"cellular"},"createdAt":{"type":"string","format":"date-time","description":"The timestamp when the network adapter is created in the system.","example":"2025-09-01T23:00:00.000Z","readOnly":true},"createdBy":{"type":"string","description":"The user who created the network adapter.","example":"principal/9ebbb3b1-1b6b-46e7-8d58-bb8fe7ae24d4","readOnly":true},"modifiedAt":{"type":"string","format":"date-time","description":"The timestamp when the network adapter is last modified in the system.","example":"2025-09-01T23:00:00.000Z","readOnly":true},"modifiedBy":{"type":"string","description":"The user who last modified the network adapter.","example":"principal/9ebbb3b1-1b6b-46e7-8d58-bb8fe7ae24d4","readOnly":true},"imei":{"type":"string","description":"The International Mobile Equipment Identity (IMEI) that identifies the cellular adapter","example":"357292748642776","maxLength":16,"minLength":15},"iccId":{"type":"string","description":"The Integrated Circuit Card Identifier (ICCID) that identifies the SIM chip","example":"89204698812790186735","maxLength":22,"minLength":18},"urn":{"type":"string","description":"The URN for this network adapter","example":"urn:dev:IMEI:357292748642776:","readOnly":true}},"required":["imei","type"],"title":"CellularNetworkAdapter","example":null},"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","example":"d0efdb7e-ac07-4bc5-890c-eb879bbf9540","readOnly":true},"type":{"type":"string","description":"The type of network adapter; must be 'generic' for GenericNetworkAdapter","example":"generic"},"createdAt":{"type":"string","format":"date-time","description":"The timestamp when the network adapter is created in the system.","example":"2025-09-01T23:00:00.000Z","readOnly":true},"createdBy":{"type":"string","description":"The user who created the network adapter.","example":"principal/9ebbb3b1-1b6b-46e7-8d58-bb8fe7ae24d4","readOnly":true},"modifiedAt":{"type":"string","format":"date-time","description":"The timestamp when the network adapter is last modified in the system.","example":"2025-09-01T23:00:00.000Z","readOnly":true},"modifiedBy":{"type":"string","description":"The user who last modified the network adapter.","example":"principal/9ebbb3b1-1b6b-46e7-8d58-bb8fe7ae24d4","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","example":"4dd797de-357f-4ad2-8caa-4c45f74eaad8"},"urn":{"type":"string","description":"The URN for this network adapter","example":"urn:dev:DVNUUID:4dd797de-357f-4ad2-8caa-4c45f74eaad8:","readOnly":true}},"required":["dvnUuid","type"],"title":"GenericNetworkAdapter","example":null},"LoraNetworkAdapter":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The id of the network adapter","example":"eecdc728-d3a8-4cda-b468-6004a7179ddb","readOnly":true},"type":{"type":"string","description":"The type of network adapter; must be 'lora' for LoraNetworkAdapter","example":"lora"},"createdAt":{"type":"string","format":"date-time","description":"The timestamp when the network adapter is created in the system.","example":"2025-09-01T23:00:00.000Z","readOnly":true},"createdBy":{"type":"string","description":"The user who created the network adapter.","example":"principal/9ebbb3b1-1b6b-46e7-8d58-bb8fe7ae24d4","readOnly":true},"modifiedAt":{"type":"string","format":"date-time","description":"The timestamp when the network adapter is last modified in the system.","example":"2025-09-01T23:00:00.000Z","readOnly":true},"modifiedBy":{"type":"string","description":"The user who last modified the network adapter.","example":"principal/9ebbb3b1-1b6b-46e7-8d58-bb8fe7ae24d4","readOnly":true},"devEui":{"type":"string","description":"The Device Extended Unique Identifier (DevEUI) that identifies the LoRa node","example":"EA8FA35E2CF3489F","maxLength":16},"urn":{"type":"string","description":"The URN for this network adapter","example":"urn:dev:DEVEUI:EA8FA35E2CF3489F:","readOnly":true}},"required":["devEui","type"],"title":"LoraNetworkAdapter","example":null},"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","example":null},{"$ref":"#/components/schemas/GenericNetworkAdapter","example":null},{"$ref":"#/components/schemas/LoraNetworkAdapter","example":null}],"properties":{"type":{"type":"string","description":"The type of network adapter. Known values are: cellular, generic and lora","example":"cellular"},"urn":{"description":"The URN for this network adapter","example":"urn:dev:IMEI:357292748642776:","readOnly":true}},"required":["type","urn"],"title":"NetworkAdapter","example":null},"Device":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"The id of the device","example":"36e75427-4c6e-438c-89b5-0cbdb0d4068c","readOnly":true},"createdAt":{"type":"string","format":"date-time","description":"The timestamp when the device is created in the system.","example":"2024-12-31T23:00:00.000Z","readOnly":true},"createdBy":{"type":"string","description":"The user who created the device.","example":"principal/9ebbb3b1-1b6b-46e7-8d58-bb8fe7ae24d4","readOnly":true},"modifiedAt":{"type":"string","format":"date-time","description":"The timestamp when the device is last modified in the system.","example":"2024-12-31T23:00:00.000Z","readOnly":true},"modifiedBy":{"type":"string","description":"The user who last modified the device.","example":"principal/9ebbb3b1-1b6b-46e7-8d58-bb8fe7ae24d4","readOnly":true},"name":{"type":"string","description":"Name of this device","example":"My first device","maxLength":255,"minLength":1,"pattern":"^(?!\\s*$).+"},"status":{"$ref":"#/components/schemas/DeviceStatus","example":null},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"A JSON object containing key-value metadata","example":{"author":"John Doe","version":1.2}},"barcode":{"type":"string","description":"Barcode of the device","example":"123456789"},"description":{"type":"string","description":"Description of this device","example":"Device to explore KPN Things","maxLength":255},"clientId":{"type":"string","format":"uuid","description":"ID of owning client","example":"7098dc22-fed5-4d9e-8e68-6c6f853eac0c"},"projectId":{"type":"string","format":"uuid","description":"ID of the project the device belongs to","example":"b6a883a8-41f9-428e-a8a1-4597de54fec6"},"deviceSpecificationId":{"type":"string","format":"uuid","description":"ID of the device specification of the device","example":"9c359e94-ace1-448c-8ac9-443a7d3d963f"},"networkAdapters":{"type":"array","description":"List of network adapters attached to the device","items":{"$ref":"#/components/schemas/NetworkAdapter"},"example":null}},"required":["clientId","deviceSpecificationId","name","projectId"],"title":"Device","example":null},"DeviceGroupDeviceLinkResponse":{"type":"object","allOf":[{"$ref":"#/components/schemas/DeviceGroupDeviceLink","example":null},{"type":"object","description":"Embedded items for the device group - device link","properties":{"_embedded":{"type":"object","properties":{"deviceGroup":{"$ref":"#/components/schemas/DeviceGroup","example":null},"device":{"$ref":"#/components/schemas/Device","example":null}},"example":null}},"example":null}],"description":"DeviceGroupDeviceLink with optional embedded entities","title":"DeviceGroupDeviceLinkResponse","example":null},"PageOfDeviceGroupDeviceLinks":{"type":"object","allOf":[{"$ref":"#/components/schemas/Page","example":null},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/DeviceGroupDeviceLinkResponse"},"example":null}},"example":null}],"description":"A paginated list of device group to device links","title":"PageOfDeviceGroupDeviceLinks","example":null}},"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"},"example":"createdAt,-name"}},"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}}}}