{"openapi":"3.1.0","info":{"title":"Things Firmware Management API","description":"This specification describes the Firmware Management API of the KPN Things Platform.\nThe Firmware Management API allows you to manage the firmware of your devices. \nPer device specification, one or more firmware modules can be created, and for each module \nit's possible to create firmware packages. Each firmware package has a version and contains a firmware file.\nThe firmware package can be set as the target firmware version for a module of a device.\n","contact":{"name":"KPN Things Support","url":"https://portal.kpnthings.com/support","email":"iot-developer@kpn.com"},"version":"0.0.2"},"servers":[{"url":"https://api.kpnthings.com","description":"Things API Environment"}],"paths":{"/firmware/modules":{"get":{"tags":["firmware-module"],"summary":"Retrieve firmware modules for device-specifications.","description":"Retrieve firmware modules filtered by specified search criteria.","operationId":"searchFirmwareModules","parameters":[{"name":"deviceSpecificationId","in":"query","description":"Device specification identifier.","style":"form","explode":true,"schema":{"type":"string","format":"uuid","examples":["12345678-1234-1234-1234-12345678abcd"],"example":null}},{"name":"clientId","in":"query","description":"Client identifier of the owner of the device specification to which this module belongs.","style":"form","explode":true,"schema":{"type":"string","format":"uuid","examples":["12345678-1234-1234-1234-12345678abcd"],"example":null}}],"responses":{"200":{"description":"A list of firmware modules.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListOfFirmwareModules","example":null}}}},"400":{"$ref":"#/components/responses/badRequest"}},"security":[{"BearerAuth":["specification.read"]}]},"post":{"tags":["firmware-module"],"summary":"Create a new firmware module.","description":"Create a new firmware module.","operationId":"createFirmwareModule","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FirmwareModule","example":null}}},"required":true},"responses":{"201":{"description":"The newly created module.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FirmwareModule","example":null}}}},"400":{"$ref":"#/components/responses/badRequest"}},"security":[{"BearerAuth":["specification.update"]}]}},"/firmware/modules/{moduleId}":{"get":{"tags":["firmware-module"],"summary":"Retrieve a firmware module by ID.","operationId":"getFirmwareModule","parameters":[{"name":"moduleId","in":"path","description":"Module identifier.","required":true,"style":"simple","schema":{"type":"string","format":"uuid","example":null}}],"responses":{"200":{"description":"The requested firmware module.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FirmwareModule","example":null}}}},"400":{"$ref":"#/components/responses/badRequest"}},"security":[{"BearerAuth":["specification.read"]}]},"put":{"tags":["firmware-module"],"summary":"Update a firmware module.","operationId":"setFirmwareModule","parameters":[{"name":"moduleId","in":"path","description":"Module identifier.","required":true,"style":"simple","schema":{"type":"string","format":"uuid","example":null}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FirmwareModule"}}},"required":true},"responses":{"200":{"description":"The updated module.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FirmwareModule","example":null}}}}},"security":[{"BearerAuth":["specification.update"]}]},"delete":{"tags":["firmware-module"],"summary":"Delete a firmware module.","operationId":"deleteFirmwareModule","parameters":[{"name":"moduleId","in":"path","description":"Module identifier.","required":true,"style":"simple","schema":{"type":"string","format":"uuid","example":null}}],"responses":{"204":{"description":"Module has been deleted successfully."}},"security":[{"BearerAuth":["specification.update"]}]}},"/firmware/packages":{"get":{"tags":["firmware-package"],"summary":"Retrieve firmware packages","description":"Retrieve firmware packages by client, device specification and / or module.","operationId":"searchFirmwarePackages","parameters":[{"$ref":"#/components/parameters/cursor"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/sort"},{"name":"deviceSpecificationId","in":"query","description":"Device specification identifier.","style":"form","explode":true,"schema":{"type":"string","format":"uuid","examples":["12345678-1234-1234-1234-12345678abcd"],"example":null}},{"name":"moduleId","in":"query","description":"Firmware Module identifier.","style":"form","explode":true,"schema":{"type":"string","format":"uuid","examples":["12341234-1234-1234-1234-12345678abcd"],"example":null}},{"name":"clientId","in":"query","description":"Client identifier of the owner of the packages.","style":"form","explode":true,"schema":{"type":"string","format":"uuid","examples":["12341234-1234-1234-1234-12345678abcd"],"example":null}},{"name":"embed","in":"query","description":"Results to embed in the response.","style":"form","explode":true,"schema":{"type":"array","examples":[["module"]],"items":{"type":"string","enum":["module","deviceSpecification"]},"example":null}}],"responses":{"200":{"description":"Page of firmware packages.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PageOfFirmwarePackages","example":null}}}},"400":{"$ref":"#/components/responses/badRequest"}},"security":[{"BearerAuth":["firmware.read"]}]},"post":{"tags":["firmware-package"],"summary":"Create a firmware package for one of the modules of a device specification.","operationId":"createFirmwarePackage","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FirmwarePackage","example":null}}},"required":true},"responses":{"201":{"description":"The newly created firmware.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FirmwarePackage","example":null}}}},"400":{"$ref":"#/components/responses/badRequest"}},"security":[{"BearerAuth":["firmware.create"]}]}},"/firmware/packages/{firmwarePackageId}":{"get":{"tags":["firmware-package"],"summary":"Retrieve a firmware package by ID.","operationId":"getFirmwarePackage","parameters":[{"name":"firmwarePackageId","in":"path","description":"Firmware package identifier.","required":true,"style":"simple","schema":{"type":"string","format":"uuid","examples":["12345678-1234-1234-1234-12345678abcd"],"example":null}},{"name":"embed","in":"query","description":"Results to embed in the response.","style":"form","explode":true,"schema":{"type":"array","examples":[["module"]],"items":{"type":"string","enum":["module","deviceSpecification"]},"example":null}}],"responses":{"200":{"description":"The requested firmware package.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FirmwarePackage","example":null}}}},"400":{"$ref":"#/components/responses/badRequest"}},"security":[{"BearerAuth":["firmware.read"]}]},"put":{"tags":["firmware-package"],"summary":"Update a firmware package.","description":"Update the description of a firmware package. Note that the firmwareVersion, deviceSpecificationId and moduleId can not be modified.\n","operationId":"setFirmwarePackage","parameters":[{"name":"firmwarePackageId","in":"path","description":"Firmware identifier.","required":true,"style":"simple","schema":{"type":"string","format":"uuid","examples":["12345678-1234-1234-1234-12345678abcd"],"example":null}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FirmwarePackage"}}},"required":true},"responses":{"201":{"description":"The updated firmware.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FirmwarePackage","example":null}}}},"400":{"$ref":"#/components/responses/badRequest"}},"security":[{"BearerAuth":["firmware.update"]}]},"delete":{"tags":["firmware-package"],"summary":"Delete a firmware package by ID.","operationId":"deleteFirmwarePackage","parameters":[{"name":"firmwarePackageId","in":"path","description":"Firmware package identifier.","required":true,"style":"simple","schema":{"type":"string","format":"uuid","examples":["12345678-1234-1234-1234-12345678abcd"],"example":null}}],"responses":{"204":{"description":"Firmware package has been deleted successfully."}},"security":[{"BearerAuth":["firmware.delete"]}]}},"/firmware/packages/{firmwarePackageId}/firmware-file":{"get":{"tags":["firmware-package"],"summary":"Download the firmware file of a firmware package.","description":"Download the  firmware file of a firmware package. Only one file can be downloaded per request, \nso the firmwarePackageId query parameter is required.\n","operationId":"downloadFirmwareFile","parameters":[{"name":"firmwarePackageId","in":"path","description":"Firmware identifier.","required":true,"style":"simple","schema":{"type":"string","format":"uuid","examples":["12345678-1234-1234-1234-12345678abcd"],"example":null}}],"responses":{"200":{"description":"The requested file in binary format.","content":{"application/json":{"schema":{"type":"string","format":"binary","example":null}}}},"400":{"$ref":"#/components/responses/badRequest"}},"security":[{"BearerAuth":["firmware.read"]}]},"post":{"tags":["firmware-package"],"summary":"Upload a firmware file for a firmware package.\n","description":"Upload a firmware or release notes file and add it to a specific firmware package.\nNote that a firmware file can only be posted once per firmware package, and that it can not be deleted.\n","operationId":"uploadFirmwareFile","parameters":[{"name":"firmwarePackageId","in":"path","description":"Firmware identifier.","required":true,"style":"simple","schema":{"type":"string","format":"uuid","examples":["12345678-1234-1234-1234-12345678abcd"],"example":null}}],"requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/FirmwareFileUpload"}}},"required":true},"responses":{"200":{"description":"The information about the uploaded file for a device specification.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileAttributes","example":null}}}},"400":{"$ref":"#/components/responses/badRequest"}},"security":[{"BearerAuth":["firmware.write"]}]}},"/firmware/packages/{firmwarePackageId}/release-notes-file":{"get":{"tags":["firmware-package"],"summary":"Download the release notes file of a firmware package.","description":"Download the most recent release notes file of a firmware package. Only one file can be downloaded per request, \nso the firmwarePackageId query parameter is required.\n","operationId":"downloadReleaseNotesFile","parameters":[{"name":"firmwarePackageId","in":"path","description":"Firmware identifier.","required":true,"style":"simple","schema":{"type":"string","format":"uuid","examples":["12345678-1234-1234-1234-12345678abcd"],"example":null}}],"responses":{"200":{"description":"The requested file in binary format.","content":{"application/json":{"schema":{"type":"string","format":"binary","example":null}}}},"400":{"$ref":"#/components/responses/badRequest"}},"security":[{"BearerAuth":["firmware.read"]}]},"post":{"tags":["firmware-package"],"summary":"Upload a release notes file for a firmware package.\n","description":"Upload a release notes file and add it to a specific firmware package.\nThe release notes file can be posted multiple times per firmware package, this will overwrite the previous release notes file if it already \nexists for that firmware package.\n","operationId":"uploadReleaseNotesFile","parameters":[{"name":"firmwarePackageId","in":"path","description":"Firmware identifier.","required":true,"style":"simple","schema":{"type":"string","format":"uuid","examples":["12345678-1234-1234-1234-12345678abcd"],"example":null}}],"requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/FirmwareFileUpload"}}},"required":true},"responses":{"200":{"description":"The information about the uploaded file.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileAttributes","example":null}}}},"400":{"$ref":"#/components/responses/badRequest"}},"security":[{"BearerAuth":["firmware.write"]}]},"delete":{"tags":["firmware-package"],"summary":"Delete the release notes file of a firmware package.","operationId":"deleteReleaseNotesFile","parameters":[{"name":"firmwarePackageId","in":"path","description":"Firmware package identifier.","required":true,"style":"simple","schema":{"type":"string","format":"uuid","examples":["12345678-1234-1234-1234-12345678abcd"],"example":null}}],"responses":{"204":{"description":"Deleted the release notes file."},"400":{"$ref":"#/components/responses/badRequest"}},"security":[{"BearerAuth":["firmware.delete"]}]}},"/firmware/states":{"get":{"tags":["firmware-state"],"summary":"Retrieve firmware states.","description":"Retrieve firmware states for devices filtered by specified search criteria","operationId":"searchFirmwareStates","parameters":[{"$ref":"#/components/parameters/cursor"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/sort"},{"name":"clientId","in":"query","description":"Include only devices that match the provided owner clientId.  If clientId is omitted, all devices are included.","style":"form","explode":true,"schema":{"type":"string","format":"uuid","examples":["79658ca8-f1ba-4c25-b824-93813e9fba76"],"example":null}},{"name":"projectId","in":"query","description":"Include only devices that match the provided projectId.  If projectId is omitted, all devices are included.","style":"form","explode":true,"schema":{"type":"string","format":"uuid","examples":["79658ca8-f1ba-4c25-b824-93813e9fba76"],"example":null}},{"name":"deviceId","in":"query","description":"Include only devices that match the provided deviceId.  If projectId is omitted, all devices are included.","style":"form","explode":true,"schema":{"type":"string","format":"uuid","examples":["79658ca8-f1ba-4c25-b824-93813e9fba76"],"example":null}},{"name":"deviceSpecificationIds","in":"query","description":"Filter devices by their device specification.","style":"form","explode":true,"schema":{"type":"array","examples":[["37186a83-ef07-4c03-a9b5-0d385565188e"]],"items":{"type":"string","format":"uuid"},"example":null}},{"name":"moduleIds","in":"query","description":"Filter devices by their device specifications module identifier.","style":"form","explode":true,"schema":{"type":"array","examples":[["37186a83-ef07-4c03-a9b5-0d385565188e"]],"items":{"type":"string","format":"uuid"},"example":null}},{"name":"currentFirmwareVersion","in":"query","description":"Filter devices by their current firmware version for the given module.","style":"form","explode":true,"schema":{"type":"string","examples":[1],"example":null}},{"name":"targetFirmwareVersion","in":"query","description":"Filter devices by their target firmware version for the given module.","style":"form","explode":true,"schema":{"type":"string","examples":[1],"example":null}},{"name":"firmwareUpdateStartedAt","in":"query","description":"Filter devices by the date and time of their firmware update start for the given module.","style":"form","explode":true,"schema":{"type":"string","format":"date-time","examples":["2024-01-01T00:00:00.000Z"],"example":null}},{"name":"firmwareUpdateStatus","in":"query","description":"Filter devices by their firmware update status for the given module.","style":"form","explode":true,"schema":{"type":"string","examples":["IDLE","NOTIFYING","UPLOADING","FAILED"],"example":null}}],"responses":{"200":{"description":"The requested firmware states.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PageOfFirmwareStates","example":null}}}}},"security":[{"BearerAuth":["device.read"]}]}},"/firmware/states/target-firmware-requests":{"post":{"tags":["firmware-state"],"summary":"Set or reset the target firmware version for a list of devices.","description":"Set or reset the target firmware version for a list of devices.  This operation allows you to specify a target firmware version for multiple devices at once,  enabling efficient management of firmware updates across your fleet of devices.","operationId":"setTargetFirmwareVersionForDevices","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListOfFirmwareStates"}}},"required":true},"responses":{"200":{"description":"The target firmware has been set successfully for all specified devices."},"400":{"$ref":"#/components/responses/badRequest"}},"security":[{"BearerAuth":["device.update"]}]}}},"components":{"schemas":{"FirmwareFileUpload":{"type":"object","description":"Multipart form-data body for uploading a firmware file.","properties":{"file":{"type":"string","format":"binary","description":"The firmware file to upload.","example":null},"checksum":{"type":"string","description":"The SHA-256 checksum of the firmware file. This is used to verify the integrity of the file after upload.","examples":["3a7bd3e2360a3d80e355b8cbb1b1b9e0e5c6a8f9d2e5c3f1a2b4c5d6e7f8"],"pattern":"^[0-9a-fA-F]+$","example":null}},"required":["file"],"title":"FirmwareFileUpload","example":null},"FirmwareModule":{"type":"object","description":"Describes a KPN Things Firmware Module. A module represent a part of a device for which the firmware is managed by KPN Things.","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier of the module","examples":["99086060-b099-416e-a321-53220f4edf96"],"readOnly":true,"example":null},"name":{"type":"string","description":"The name of the module.","examples":["Bluetooth Module"],"pattern":"^[\\x20-\\x7E]{1,100}$","example":null},"firmwareVersionAttributeName":{"type":"string","description":"The name of the firmware version attribute sent by the device to report the current module firmware version.","examples":["btModuleVersion"],"pattern":"^[A-Za-z0-9_-]{1,100}$","example":null},"deviceSpecificationId":{"type":"string","format":"uuid","description":"id of the device specification to which the module belongs","examples":["99086060-b099-416e-a321-53220f4edf96"],"example":null},"clientId":{"type":"string","format":"uuid","description":"id of the client to which the module belongs","examples":["99086060-b099-416e-a321-53220f4edf96"],"readOnly":true,"example":null},"createdAt":{"type":"string","format":"date-time","description":"The timestamp when the module is created in the system.","examples":["2024-12-31T23:00:00.000Z"],"readOnly":true,"example":null},"createdBy":{"type":"string","description":"The user who created the module.","examples":["principal/9ebbb3b1-1b6b-46e7-8d58-bb8fe7ae24d4"],"readOnly":true,"example":null},"modifiedAt":{"type":"string","format":"date-time","description":"The timestamp when the module is last modified in the system.","examples":["2024-12-31T23:00:00.000Z"],"readOnly":true,"example":null},"modifiedBy":{"type":"string","description":"The user who last modified the module.","examples":["principal/9ebbb3b1-1b6b-46e7-8d58-bb8fe7ae24d4"],"readOnly":true,"example":null}},"required":["deviceSpecificationId","firmwareVersionAttributeName","id","name"],"title":"FirmwareModule","example":null},"ListOfFirmwareModules":{"type":"object","description":"A list of modules","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/FirmwareModule"},"minItems":1,"example":null}},"required":["items"],"title":"ListOfFirmwareModules","example":null},"Problem":{"type":"object","description":"Error information details","properties":{"type":{"type":"string","format":"uri-reference","default":"about:blank","description":"A URI reference that uniquely identifies the problem type only in the\ncontext of the provided API. Opposed to the specification in RFC-9457,\nit is neither recommended to be dereferenceable and point to a\nhuman-readable documentation nor globally unique for the problem type.","example":"/some/uri-reference"},"title":{"type":"string","description":"A short summary of the problem type. Written in English and readable\nfor engineers, usually not suited for non technical stakeholders and\nnot localized.","example":"some title for the error situation"},"status":{"type":"integer","format":"int32","description":"The HTTP status code generated by the origin server for this occurrence\nof the problem.","example":400,"exclusiveMaximum":600,"minimum":100},"detail":{"type":"string","description":"A human readable explanation specific to this occurrence of the\nproblem that is helpful to locate the problem and give advice on how\nto proceed. Written in English and readable for engineers, usually not\nsuited for non technical stakeholders and not localized.","example":"Some description for the error situation"},"instance":{"type":"string","format":"uri-reference","description":"A URI reference that identifies the specific occurrence of the problem,\ne.g. by adding a fragment identifier or sub-path to the problem type.\nMay be used to locate the root of this problem in the source code.","example":"/some/uri-reference#specific-occurrence-context"}},"title":"Problem","example":null},"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},"FirmwareDeviceSpecification":{"type":"object","description":"Firmware-enabled DeviceSpecification","properties":{"id":{"type":"string","format":"uuid","description":"The id of the device-specification","examples":["36e75427-4c6e-438c-89b5-0cbdb0d4068c"],"readOnly":true,"example":null},"name":{"type":"string","description":"Name of this device-specification","examples":["My first device-specification"],"example":null},"clientId":{"type":"string","format":"uuid","description":"The id of the owning client","examples":["36e75427-4c6e-438c-89b5-0cbdb0d4068c"],"readOnly":true,"example":null}},"required":["clientId","id","name"],"title":"FirmwareDeviceSpecification","example":null},"FirmwarePackage":{"type":"object","description":"Firmware package definition with optional embedded entities","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier of the firmware","examples":["99086060-b099-416e-a321-53220f4edf96"],"readOnly":true,"example":null},"firmwareVersion":{"type":"string","description":"The version of the firmware.","examples":["1.0.1"],"pattern":"^[a-zA-Z0-9._-]{1,100}$","example":null},"clientId":{"type":"string","format":"uuid","description":"id of the client to which the package belongs","examples":["99086060-b099-416e-a321-53220f4edf96"],"example":null},"deviceSpecificationId":{"type":"string","format":"uuid","description":"id of the device specification to which the firmware belongs","examples":["99086060-b099-416e-a321-53220f4edf96"],"example":null},"moduleId":{"type":"string","format":"uuid","description":"id of the module to which the firmware belongs","examples":["99086060-b099-416e-a321-53220f4edf96"],"example":null},"description":{"type":"string","description":"Description of the firmware.","examples":["Firmware package for Bluetooth module, for version 1.0.1 of the firmware"],"pattern":"^[\\x20-\\x7E]{1,300}$","example":null},"firmwareFileName":{"type":"string","description":"Filename of the firmware.","examples":["firmware_v1.0.1.bin"],"readOnly":true,"example":null},"releaseNotesFileName":{"type":"string","description":"Filename of the release notes.","examples":["release_notes_v1.0.1.txt"],"readOnly":true,"example":null},"_embedded":{"type":"object","properties":{"deviceSpecification":{"$ref":"#/components/schemas/FirmwareDeviceSpecification","example":null},"module":{"$ref":"#/components/schemas/FirmwareModule","example":null}},"example":null}},"required":["deviceSpecificationId","firmwareVersion","id","moduleId"],"title":"FirmwarePackage","example":null},"PageOfFirmwarePackages":{"type":"object","allOf":[{"$ref":"#/components/schemas/Page","example":null},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/FirmwarePackage"},"example":null}},"example":null}],"description":"A paginated list of firmware-packages.","title":"PageOfFirmwarePackages","example":null},"FileAttributes":{"type":"object","description":"Represents a file","properties":{"firmwarePackageId":{"type":"string","format":"uuid","description":"The id of the firmware package to which the file belongs","examples":["99086060-b099-416e-a321-53220f4edf96"],"readOnly":true,"example":null},"name":{"type":"string","description":"Name of the file","examples":["firmware.bin"],"pattern":"^[a-zA-Z0-9.-_]{1,100}$","example":null},"contentType":{"type":"string","description":"Content-Type of the file","examples":["application/octet-stream"],"pattern":"^[\\x20-\\x7E]{1,100}$","example":null},"fileType":{"type":"string","description":"The type of the file","examples":["firmware","releaseNotes"],"example":null},"deviceSpecificationId":{"type":"string","format":"uuid","description":"The id of the device specification to which the file belongs","examples":["99086060-b099-416e-a321-53220f4edf96"],"readOnly":true,"example":null},"createdAt":{"type":"string","format":"date-time","description":"The timestamp this file was created","examples":["2024-12-31T23:00:00.000Z"],"readOnly":true,"example":null},"createdBy":{"type":"string","description":"The identifier of the user that created this file","examples":["principal/9ebbb3b1-1b6b-46e7-8d58-bb8fe7ae24d4"],"readOnly":true,"example":null},"modifiedAt":{"type":"string","format":"date-time","description":"The timestamp this file was last modified","examples":["2024-12-31T23:00:00.000Z"],"readOnly":true,"example":null},"modifiedBy":{"type":"string","description":"The identifier of the user that last modified this file","examples":["principal/9ebbb3b1-1b6b-46e7-8d58-bb8fe7ae24d4"],"readOnly":true,"example":null}},"required":["contentType","name"],"title":"FileAttributes","example":null},"FirmwareState":{"type":"object","description":"Describes the module state for a specific device.","properties":{"moduleId":{"type":"string","format":"uuid","description":"Unique identifier of the module","examples":["99086060-b099-416e-a321-53220f4edf96"],"example":null},"deviceId":{"type":"string","format":"uuid","description":"Unique identifier of the device","examples":["99086060-b099-416e-a321-53220f4edf96"],"example":null},"deviceSpecificationId":{"type":"string","format":"uuid","description":"Unique identifier of the device specification","examples":["99086060-b099-416e-a321-53220f4edf96"],"readOnly":true,"example":null},"clientId":{"type":"string","format":"uuid","description":"id of the client that owns this device with this module state","examples":["99086060-b099-416e-a321-53220f4edf96"],"readOnly":true,"example":null},"projectId":{"type":"string","format":"uuid","description":"id of the project where this device with this module state reside","examples":["99086060-b099-416e-a321-53220f4edf96"],"readOnly":true,"example":null},"currentFirmwareVersion":{"type":"string","description":"The current firmware version of the module as reported by the device.","examples":["1.0.0"],"readOnly":true,"example":null},"targetFirmwareVersion":{"type":"string","description":"The target firmware version of the module. This is the version that the device should update to. If not present, the target firmware version will be reset.","examples":["1.0.1"],"example":null},"targetFirmwareVersionModifiedAt":{"type":"string","format":"date-time","description":"The timestamp when the target firmware was last modified.","examples":["2024-12-31T23:00:00.000Z"],"readOnly":true,"example":null},"firmwareUpdateStatus":{"type":"string","description":"The status of the firmware update process for the module.","examples":["IDLE","NOTIFYING","UPLOADING","FAILED"],"readOnly":true,"example":null},"firmwareUpdateStatusDetails":{"type":"string","description":"The status details of the firmware update process for the module.","examples":["Failed to deliver downlink message to device"],"readOnly":true,"example":null},"firmwareUpdateStatusModifiedAt":{"type":"string","format":"date-time","description":"The timestamp when the firmware update status was last modified.","examples":["2024-12-31T23:00:00.000Z"],"readOnly":true,"example":null}},"required":["deviceId","moduleId"],"title":"FirmwareState","example":null},"PageOfFirmwareStates":{"type":"object","allOf":[{"$ref":"#/components/schemas/Page","example":null},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/FirmwareState"},"example":null}},"example":null}],"description":"A paginated list of firmware-states.","title":"PageOfFirmwareStates","example":null},"ListOfFirmwareStates":{"type":"object","description":"A list of firmware module states.","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/FirmwareState"},"minItems":1,"example":null}},"required":["items"],"title":"ListOfFirmwareStates","example":null}},"responses":{"badRequest":{"description":"Request is missing required information or invalid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"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"}}}}