> For the complete documentation index, see [llms.txt](https://docs.kpnthings.com/kpn-things/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kpnthings.com/kpn-things/general-functions/apis/firmwares.md).
# Firmwares
The Firmwares API can be used to retrieve the firmware status and to update the firmware of your devices. Read more about the [Firmware Update Service](https://docs.kpnthings.com/kpn-things/kpn-firmware-over-the-air/).
You can use this API using your Grip API Key. Please note that not all Grip API Keys automatically have access to the Firmwares API. A firmware specific authorization is required, which must be requested from KPN via a standard Request. To do so, please contact your KPN representative.
Download the [specification](https://api.kpnthings.com/openapi-specifications/firmwares)
## Retrieve firmware modules for device-specifications.
> Retrieve firmware modules filtered by specified search criteria.
```json
{"openapi":"3.1.0","info":{"title":"Things Firmware Management API","version":"0.0.2"},"servers":[{"url":"https://api.kpnthings.com","description":"Things API Environment"}],"security":[{"BearerAuth":["specification.read"]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"ListOfFirmwareModules":{"type":"object","description":"A list of modules","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/FirmwareModule"},"minItems":1}},"required":["items"],"title":"ListOfFirmwareModules"},"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","readOnly":true},"name":{"type":"string","description":"The name of the module.","pattern":"^[\\x20-\\x7E]{1,100}$"},"firmwareVersionAttributeName":{"type":"string","description":"The name of the firmware version attribute sent by the device to report the current module firmware version.","pattern":"^[A-Za-z0-9_-]{1,100}$"},"deviceSpecificationId":{"type":"string","format":"uuid","description":"id of the device specification to which the module belongs"},"clientId":{"type":"string","format":"uuid","description":"id of the client to which the module belongs","readOnly":true},"createdAt":{"type":"string","format":"date-time","description":"The timestamp when the module is created in the system.","readOnly":true},"createdBy":{"type":"string","description":"The user who created the module.","readOnly":true},"modifiedAt":{"type":"string","format":"date-time","description":"The timestamp when the module is last modified in the system.","readOnly":true},"modifiedBy":{"type":"string","description":"The user who last modified the module.","readOnly":true}},"required":["deviceSpecificationId","firmwareVersionAttributeName","id","name"],"title":"FirmwareModule"},"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."},"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."},"status":{"type":"integer","format":"int32","description":"The HTTP status code generated by the origin server for this occurrence\nof the problem.","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."},"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."}},"title":"Problem"}},"responses":{"badRequest":{"description":"Request is missing required information or invalid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"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"}},{"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"}}],"responses":{"200":{"description":"A list of firmware modules.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListOfFirmwareModules"}}}},"400":{"$ref":"#/components/responses/badRequest"}}}}}}
```
## GET /firmware/modules/{moduleId}
> Retrieve a firmware module by ID.
```json
{"openapi":"3.1.0","info":{"title":"Things Firmware Management API","version":"0.0.2"},"servers":[{"url":"https://api.kpnthings.com","description":"Things API Environment"}],"security":[{"BearerAuth":["specification.read"]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"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","readOnly":true},"name":{"type":"string","description":"The name of the module.","pattern":"^[\\x20-\\x7E]{1,100}$"},"firmwareVersionAttributeName":{"type":"string","description":"The name of the firmware version attribute sent by the device to report the current module firmware version.","pattern":"^[A-Za-z0-9_-]{1,100}$"},"deviceSpecificationId":{"type":"string","format":"uuid","description":"id of the device specification to which the module belongs"},"clientId":{"type":"string","format":"uuid","description":"id of the client to which the module belongs","readOnly":true},"createdAt":{"type":"string","format":"date-time","description":"The timestamp when the module is created in the system.","readOnly":true},"createdBy":{"type":"string","description":"The user who created the module.","readOnly":true},"modifiedAt":{"type":"string","format":"date-time","description":"The timestamp when the module is last modified in the system.","readOnly":true},"modifiedBy":{"type":"string","description":"The user who last modified the module.","readOnly":true}},"required":["deviceSpecificationId","firmwareVersionAttributeName","id","name"],"title":"FirmwareModule"},"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."},"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."},"status":{"type":"integer","format":"int32","description":"The HTTP status code generated by the origin server for this occurrence\nof the problem.","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."},"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."}},"title":"Problem"}},"responses":{"badRequest":{"description":"Request is missing required information or invalid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/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"}}],"responses":{"200":{"description":"The requested firmware module.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FirmwareModule"}}}},"400":{"$ref":"#/components/responses/badRequest"}}}}}}
```
## Retrieve firmware packages
> Retrieve firmware packages by client, device specification and / or module.
```json
{"openapi":"3.1.0","info":{"title":"Things Firmware Management API","version":"0.0.2"},"servers":[{"url":"https://api.kpnthings.com","description":"Things API Environment"}],"security":[{"BearerAuth":["firmware.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":{"PageOfFirmwarePackages":{"type":"object","allOf":[{"$ref":"#/components/schemas/Page"},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/FirmwarePackage"}}}}],"description":"A paginated list of firmware-packages.","title":"PageOfFirmwarePackages"},"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"},"FirmwarePackage":{"type":"object","description":"Firmware package definition with optional embedded entities","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier of the firmware","readOnly":true},"firmwareVersion":{"type":"string","description":"The version of the firmware.","pattern":"^[a-zA-Z0-9._-]{1,100}$"},"clientId":{"type":"string","format":"uuid","description":"id of the client to which the package belongs"},"deviceSpecificationId":{"type":"string","format":"uuid","description":"id of the device specification to which the firmware belongs"},"moduleId":{"type":"string","format":"uuid","description":"id of the module to which the firmware belongs"},"description":{"type":"string","description":"Description of the firmware.","pattern":"^[\\x20-\\x7E]{1,300}$"},"firmwareFileName":{"type":"string","description":"Filename of the firmware.","readOnly":true},"releaseNotesFileName":{"type":"string","description":"Filename of the release notes.","readOnly":true},"_embedded":{"type":"object","properties":{"deviceSpecification":{"$ref":"#/components/schemas/FirmwareDeviceSpecification"},"module":{"$ref":"#/components/schemas/FirmwareModule"}}}},"required":["deviceSpecificationId","firmwareVersion","id","moduleId"],"title":"FirmwarePackage"},"FirmwareDeviceSpecification":{"type":"object","description":"Firmware-enabled DeviceSpecification","properties":{"id":{"type":"string","format":"uuid","description":"The id of the device-specification","readOnly":true},"name":{"type":"string","description":"Name of this device-specification"},"clientId":{"type":"string","format":"uuid","description":"The id of the owning client","readOnly":true}},"required":["clientId","id","name"],"title":"FirmwareDeviceSpecification"},"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","readOnly":true},"name":{"type":"string","description":"The name of the module.","pattern":"^[\\x20-\\x7E]{1,100}$"},"firmwareVersionAttributeName":{"type":"string","description":"The name of the firmware version attribute sent by the device to report the current module firmware version.","pattern":"^[A-Za-z0-9_-]{1,100}$"},"deviceSpecificationId":{"type":"string","format":"uuid","description":"id of the device specification to which the module belongs"},"clientId":{"type":"string","format":"uuid","description":"id of the client to which the module belongs","readOnly":true},"createdAt":{"type":"string","format":"date-time","description":"The timestamp when the module is created in the system.","readOnly":true},"createdBy":{"type":"string","description":"The user who created the module.","readOnly":true},"modifiedAt":{"type":"string","format":"date-time","description":"The timestamp when the module is last modified in the system.","readOnly":true},"modifiedBy":{"type":"string","description":"The user who last modified the module.","readOnly":true}},"required":["deviceSpecificationId","firmwareVersionAttributeName","id","name"],"title":"FirmwareModule"},"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."},"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."},"status":{"type":"integer","format":"int32","description":"The HTTP status code generated by the origin server for this occurrence\nof the problem.","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."},"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."}},"title":"Problem"}},"responses":{"badRequest":{"description":"Request is missing required information or invalid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/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"}},{"name":"moduleId","in":"query","description":"Firmware Module identifier.","style":"form","explode":true,"schema":{"type":"string","format":"uuid"}},{"name":"clientId","in":"query","description":"Client identifier of the owner of the packages.","style":"form","explode":true,"schema":{"type":"string","format":"uuid"}},{"name":"embed","in":"query","description":"Results to embed in the response.","style":"form","explode":true,"schema":{"type":"array","items":{"type":"string","enum":["module","deviceSpecification"]}}}],"responses":{"200":{"description":"Page of firmware packages.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PageOfFirmwarePackages"}}}},"400":{"$ref":"#/components/responses/badRequest"}}}}}}
```
## POST /firmware/packages
> Create a firmware package for one of the modules of a device specification.
```json
{"openapi":"3.1.0","info":{"title":"Things Firmware Management API","version":"0.0.2"},"servers":[{"url":"https://api.kpnthings.com","description":"Things API Environment"}],"security":[{"BearerAuth":["firmware.create"]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"FirmwarePackage":{"type":"object","description":"Firmware package definition with optional embedded entities","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier of the firmware","readOnly":true},"firmwareVersion":{"type":"string","description":"The version of the firmware.","pattern":"^[a-zA-Z0-9._-]{1,100}$"},"clientId":{"type":"string","format":"uuid","description":"id of the client to which the package belongs"},"deviceSpecificationId":{"type":"string","format":"uuid","description":"id of the device specification to which the firmware belongs"},"moduleId":{"type":"string","format":"uuid","description":"id of the module to which the firmware belongs"},"description":{"type":"string","description":"Description of the firmware.","pattern":"^[\\x20-\\x7E]{1,300}$"},"firmwareFileName":{"type":"string","description":"Filename of the firmware.","readOnly":true},"releaseNotesFileName":{"type":"string","description":"Filename of the release notes.","readOnly":true},"_embedded":{"type":"object","properties":{"deviceSpecification":{"$ref":"#/components/schemas/FirmwareDeviceSpecification"},"module":{"$ref":"#/components/schemas/FirmwareModule"}}}},"required":["deviceSpecificationId","firmwareVersion","id","moduleId"],"title":"FirmwarePackage"},"FirmwareDeviceSpecification":{"type":"object","description":"Firmware-enabled DeviceSpecification","properties":{"id":{"type":"string","format":"uuid","description":"The id of the device-specification","readOnly":true},"name":{"type":"string","description":"Name of this device-specification"},"clientId":{"type":"string","format":"uuid","description":"The id of the owning client","readOnly":true}},"required":["clientId","id","name"],"title":"FirmwareDeviceSpecification"},"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","readOnly":true},"name":{"type":"string","description":"The name of the module.","pattern":"^[\\x20-\\x7E]{1,100}$"},"firmwareVersionAttributeName":{"type":"string","description":"The name of the firmware version attribute sent by the device to report the current module firmware version.","pattern":"^[A-Za-z0-9_-]{1,100}$"},"deviceSpecificationId":{"type":"string","format":"uuid","description":"id of the device specification to which the module belongs"},"clientId":{"type":"string","format":"uuid","description":"id of the client to which the module belongs","readOnly":true},"createdAt":{"type":"string","format":"date-time","description":"The timestamp when the module is created in the system.","readOnly":true},"createdBy":{"type":"string","description":"The user who created the module.","readOnly":true},"modifiedAt":{"type":"string","format":"date-time","description":"The timestamp when the module is last modified in the system.","readOnly":true},"modifiedBy":{"type":"string","description":"The user who last modified the module.","readOnly":true}},"required":["deviceSpecificationId","firmwareVersionAttributeName","id","name"],"title":"FirmwareModule"},"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."},"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."},"status":{"type":"integer","format":"int32","description":"The HTTP status code generated by the origin server for this occurrence\nof the problem.","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."},"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."}},"title":"Problem"}},"responses":{"badRequest":{"description":"Request is missing required information or invalid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/firmware/packages":{"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"}}},"required":true},"responses":{"201":{"description":"The newly created firmware.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FirmwarePackage"}}}},"400":{"$ref":"#/components/responses/badRequest"}}}}}}
```
## GET /firmware/packages/{firmwarePackageId}
> Retrieve a firmware package by ID.
```json
{"openapi":"3.1.0","info":{"title":"Things Firmware Management API","version":"0.0.2"},"servers":[{"url":"https://api.kpnthings.com","description":"Things API Environment"}],"security":[{"BearerAuth":["firmware.read"]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"FirmwarePackage":{"type":"object","description":"Firmware package definition with optional embedded entities","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier of the firmware","readOnly":true},"firmwareVersion":{"type":"string","description":"The version of the firmware.","pattern":"^[a-zA-Z0-9._-]{1,100}$"},"clientId":{"type":"string","format":"uuid","description":"id of the client to which the package belongs"},"deviceSpecificationId":{"type":"string","format":"uuid","description":"id of the device specification to which the firmware belongs"},"moduleId":{"type":"string","format":"uuid","description":"id of the module to which the firmware belongs"},"description":{"type":"string","description":"Description of the firmware.","pattern":"^[\\x20-\\x7E]{1,300}$"},"firmwareFileName":{"type":"string","description":"Filename of the firmware.","readOnly":true},"releaseNotesFileName":{"type":"string","description":"Filename of the release notes.","readOnly":true},"_embedded":{"type":"object","properties":{"deviceSpecification":{"$ref":"#/components/schemas/FirmwareDeviceSpecification"},"module":{"$ref":"#/components/schemas/FirmwareModule"}}}},"required":["deviceSpecificationId","firmwareVersion","id","moduleId"],"title":"FirmwarePackage"},"FirmwareDeviceSpecification":{"type":"object","description":"Firmware-enabled DeviceSpecification","properties":{"id":{"type":"string","format":"uuid","description":"The id of the device-specification","readOnly":true},"name":{"type":"string","description":"Name of this device-specification"},"clientId":{"type":"string","format":"uuid","description":"The id of the owning client","readOnly":true}},"required":["clientId","id","name"],"title":"FirmwareDeviceSpecification"},"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","readOnly":true},"name":{"type":"string","description":"The name of the module.","pattern":"^[\\x20-\\x7E]{1,100}$"},"firmwareVersionAttributeName":{"type":"string","description":"The name of the firmware version attribute sent by the device to report the current module firmware version.","pattern":"^[A-Za-z0-9_-]{1,100}$"},"deviceSpecificationId":{"type":"string","format":"uuid","description":"id of the device specification to which the module belongs"},"clientId":{"type":"string","format":"uuid","description":"id of the client to which the module belongs","readOnly":true},"createdAt":{"type":"string","format":"date-time","description":"The timestamp when the module is created in the system.","readOnly":true},"createdBy":{"type":"string","description":"The user who created the module.","readOnly":true},"modifiedAt":{"type":"string","format":"date-time","description":"The timestamp when the module is last modified in the system.","readOnly":true},"modifiedBy":{"type":"string","description":"The user who last modified the module.","readOnly":true}},"required":["deviceSpecificationId","firmwareVersionAttributeName","id","name"],"title":"FirmwareModule"},"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."},"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."},"status":{"type":"integer","format":"int32","description":"The HTTP status code generated by the origin server for this occurrence\nof the problem.","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."},"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."}},"title":"Problem"}},"responses":{"badRequest":{"description":"Request is missing required information or invalid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/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"}},{"name":"embed","in":"query","description":"Results to embed in the response.","style":"form","explode":true,"schema":{"type":"array","items":{"type":"string","enum":["module","deviceSpecification"]}}}],"responses":{"200":{"description":"The requested firmware package.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FirmwarePackage"}}}},"400":{"$ref":"#/components/responses/badRequest"}}}}}}
```
## Update a firmware package.
> Update the description of a firmware package. Note that the firmwareVersion, deviceSpecificationId and moduleId can not be modified.
```json
{"openapi":"3.1.0","info":{"title":"Things Firmware Management API","version":"0.0.2"},"servers":[{"url":"https://api.kpnthings.com","description":"Things API Environment"}],"security":[{"BearerAuth":["firmware.update"]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"FirmwarePackage":{"type":"object","description":"Firmware package definition with optional embedded entities","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier of the firmware","readOnly":true},"firmwareVersion":{"type":"string","description":"The version of the firmware.","pattern":"^[a-zA-Z0-9._-]{1,100}$"},"clientId":{"type":"string","format":"uuid","description":"id of the client to which the package belongs"},"deviceSpecificationId":{"type":"string","format":"uuid","description":"id of the device specification to which the firmware belongs"},"moduleId":{"type":"string","format":"uuid","description":"id of the module to which the firmware belongs"},"description":{"type":"string","description":"Description of the firmware.","pattern":"^[\\x20-\\x7E]{1,300}$"},"firmwareFileName":{"type":"string","description":"Filename of the firmware.","readOnly":true},"releaseNotesFileName":{"type":"string","description":"Filename of the release notes.","readOnly":true},"_embedded":{"type":"object","properties":{"deviceSpecification":{"$ref":"#/components/schemas/FirmwareDeviceSpecification"},"module":{"$ref":"#/components/schemas/FirmwareModule"}}}},"required":["deviceSpecificationId","firmwareVersion","id","moduleId"],"title":"FirmwarePackage"},"FirmwareDeviceSpecification":{"type":"object","description":"Firmware-enabled DeviceSpecification","properties":{"id":{"type":"string","format":"uuid","description":"The id of the device-specification","readOnly":true},"name":{"type":"string","description":"Name of this device-specification"},"clientId":{"type":"string","format":"uuid","description":"The id of the owning client","readOnly":true}},"required":["clientId","id","name"],"title":"FirmwareDeviceSpecification"},"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","readOnly":true},"name":{"type":"string","description":"The name of the module.","pattern":"^[\\x20-\\x7E]{1,100}$"},"firmwareVersionAttributeName":{"type":"string","description":"The name of the firmware version attribute sent by the device to report the current module firmware version.","pattern":"^[A-Za-z0-9_-]{1,100}$"},"deviceSpecificationId":{"type":"string","format":"uuid","description":"id of the device specification to which the module belongs"},"clientId":{"type":"string","format":"uuid","description":"id of the client to which the module belongs","readOnly":true},"createdAt":{"type":"string","format":"date-time","description":"The timestamp when the module is created in the system.","readOnly":true},"createdBy":{"type":"string","description":"The user who created the module.","readOnly":true},"modifiedAt":{"type":"string","format":"date-time","description":"The timestamp when the module is last modified in the system.","readOnly":true},"modifiedBy":{"type":"string","description":"The user who last modified the module.","readOnly":true}},"required":["deviceSpecificationId","firmwareVersionAttributeName","id","name"],"title":"FirmwareModule"},"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."},"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."},"status":{"type":"integer","format":"int32","description":"The HTTP status code generated by the origin server for this occurrence\nof the problem.","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."},"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."}},"title":"Problem"}},"responses":{"badRequest":{"description":"Request is missing required information or invalid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/firmware/packages/{firmwarePackageId}":{"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"}}],"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"}}}},"400":{"$ref":"#/components/responses/badRequest"}}}}}}
```
## DELETE /firmware/packages/{firmwarePackageId}
> Delete a firmware package by ID.
```json
{"openapi":"3.1.0","info":{"title":"Things Firmware Management API","version":"0.0.2"},"servers":[{"url":"https://api.kpnthings.com","description":"Things API Environment"}],"security":[{"BearerAuth":["firmware.delete"]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}}},"paths":{"/firmware/packages/{firmwarePackageId}":{"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"}}],"responses":{"204":{"description":"Firmware package has been deleted successfully."}}}}}}
```
## Download the firmware file of a firmware package.
> Download the firmware file of a firmware package. Only one file can be downloaded per request, \
> so the firmwarePackageId query parameter is required.
```json
{"openapi":"3.1.0","info":{"title":"Things Firmware Management API","version":"0.0.2"},"servers":[{"url":"https://api.kpnthings.com","description":"Things API Environment"}],"security":[{"BearerAuth":["firmware.read"]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"responses":{"badRequest":{"description":"Request is missing required information or invalid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"schemas":{"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."},"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."},"status":{"type":"integer","format":"int32","description":"The HTTP status code generated by the origin server for this occurrence\nof the problem.","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."},"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."}},"title":"Problem"}}},"paths":{"/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"}}],"responses":{"200":{"description":"The requested file in binary format.","content":{"application/json":{"schema":{"type":"string","format":"binary"}}}},"400":{"$ref":"#/components/responses/badRequest"}}}}}}
```
## Upload a firmware file for a firmware package.
> Upload a firmware or release notes file and add it to a specific firmware package.\
> Note that a firmware file can only be posted once per firmware package, and that it can not be deleted.
```json
{"openapi":"3.1.0","info":{"title":"Things Firmware Management API","version":"0.0.2"},"servers":[{"url":"https://api.kpnthings.com","description":"Things API Environment"}],"security":[{"BearerAuth":["firmware.write"]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"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."},"checksum":{"type":"string","description":"The SHA-256 checksum of the firmware file. This is used to verify the integrity of the file after upload.","pattern":"^[0-9a-fA-F]+$"}},"required":["file"],"title":"FirmwareFileUpload"},"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","readOnly":true},"name":{"type":"string","description":"Name of the file","pattern":"^[a-zA-Z0-9.-_]{1,100}$"},"contentType":{"type":"string","description":"Content-Type of the file","pattern":"^[\\x20-\\x7E]{1,100}$"},"fileType":{"type":"string","description":"The type of the file"},"deviceSpecificationId":{"type":"string","format":"uuid","description":"The id of the device specification to which the file belongs","readOnly":true},"createdAt":{"type":"string","format":"date-time","description":"The timestamp this file was created","readOnly":true},"createdBy":{"type":"string","description":"The identifier of the user that created this file","readOnly":true},"modifiedAt":{"type":"string","format":"date-time","description":"The timestamp this file was last modified","readOnly":true},"modifiedBy":{"type":"string","description":"The identifier of the user that last modified this file","readOnly":true}},"required":["contentType","name"],"title":"FileAttributes"},"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."},"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."},"status":{"type":"integer","format":"int32","description":"The HTTP status code generated by the origin server for this occurrence\nof the problem.","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."},"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."}},"title":"Problem"}},"responses":{"badRequest":{"description":"Request is missing required information or invalid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/firmware/packages/{firmwarePackageId}/firmware-file":{"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"}}],"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"}}}},"400":{"$ref":"#/components/responses/badRequest"}}}}}}
```
## Download the release notes file of a firmware package.
> Download the most recent release notes file of a firmware package. Only one file can be downloaded per request, \
> so the firmwarePackageId query parameter is required.
```json
{"openapi":"3.1.0","info":{"title":"Things Firmware Management API","version":"0.0.2"},"servers":[{"url":"https://api.kpnthings.com","description":"Things API Environment"}],"security":[{"BearerAuth":["firmware.read"]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"responses":{"badRequest":{"description":"Request is missing required information or invalid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"schemas":{"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."},"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."},"status":{"type":"integer","format":"int32","description":"The HTTP status code generated by the origin server for this occurrence\nof the problem.","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."},"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."}},"title":"Problem"}}},"paths":{"/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"}}],"responses":{"200":{"description":"The requested file in binary format.","content":{"application/json":{"schema":{"type":"string","format":"binary"}}}},"400":{"$ref":"#/components/responses/badRequest"}}}}}}
```
## Upload a release notes file for a firmware package.
> Upload a release notes file and add it to a specific firmware package.\
> The release notes file can be posted multiple times per firmware package, this will overwrite the previous release notes file if it already \
> exists for that firmware package.
```json
{"openapi":"3.1.0","info":{"title":"Things Firmware Management API","version":"0.0.2"},"servers":[{"url":"https://api.kpnthings.com","description":"Things API Environment"}],"security":[{"BearerAuth":["firmware.write"]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"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."},"checksum":{"type":"string","description":"The SHA-256 checksum of the firmware file. This is used to verify the integrity of the file after upload.","pattern":"^[0-9a-fA-F]+$"}},"required":["file"],"title":"FirmwareFileUpload"},"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","readOnly":true},"name":{"type":"string","description":"Name of the file","pattern":"^[a-zA-Z0-9.-_]{1,100}$"},"contentType":{"type":"string","description":"Content-Type of the file","pattern":"^[\\x20-\\x7E]{1,100}$"},"fileType":{"type":"string","description":"The type of the file"},"deviceSpecificationId":{"type":"string","format":"uuid","description":"The id of the device specification to which the file belongs","readOnly":true},"createdAt":{"type":"string","format":"date-time","description":"The timestamp this file was created","readOnly":true},"createdBy":{"type":"string","description":"The identifier of the user that created this file","readOnly":true},"modifiedAt":{"type":"string","format":"date-time","description":"The timestamp this file was last modified","readOnly":true},"modifiedBy":{"type":"string","description":"The identifier of the user that last modified this file","readOnly":true}},"required":["contentType","name"],"title":"FileAttributes"},"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."},"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."},"status":{"type":"integer","format":"int32","description":"The HTTP status code generated by the origin server for this occurrence\nof the problem.","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."},"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."}},"title":"Problem"}},"responses":{"badRequest":{"description":"Request is missing required information or invalid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/firmware/packages/{firmwarePackageId}/release-notes-file":{"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"}}],"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"}}}},"400":{"$ref":"#/components/responses/badRequest"}}}}}}
```
## DELETE /firmware/packages/{firmwarePackageId}/release-notes-file
> Delete the release notes file of a firmware package.
```json
{"openapi":"3.1.0","info":{"title":"Things Firmware Management API","version":"0.0.2"},"servers":[{"url":"https://api.kpnthings.com","description":"Things API Environment"}],"security":[{"BearerAuth":["firmware.delete"]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"responses":{"badRequest":{"description":"Request is missing required information or invalid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"schemas":{"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."},"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."},"status":{"type":"integer","format":"int32","description":"The HTTP status code generated by the origin server for this occurrence\nof the problem.","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."},"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."}},"title":"Problem"}}},"paths":{"/firmware/packages/{firmwarePackageId}/release-notes-file":{"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"}}],"responses":{"204":{"description":"Deleted the release notes file."},"400":{"$ref":"#/components/responses/badRequest"}}}}}}
```
## Retrieve firmware states.
> Retrieve firmware states for devices filtered by specified search criteria
```json
{"openapi":"3.1.0","info":{"title":"Things Firmware Management API","version":"0.0.2"},"servers":[{"url":"https://api.kpnthings.com","description":"Things API Environment"}],"security":[{"BearerAuth":["device.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":{"PageOfFirmwareStates":{"type":"object","allOf":[{"$ref":"#/components/schemas/Page"},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/FirmwareState"}}}}],"description":"A paginated list of firmware-states.","title":"PageOfFirmwareStates"},"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"},"FirmwareState":{"type":"object","description":"Describes the module state for a specific device.","properties":{"moduleId":{"type":"string","format":"uuid","description":"Unique identifier of the module"},"deviceId":{"type":"string","format":"uuid","description":"Unique identifier of the device"},"deviceSpecificationId":{"type":"string","format":"uuid","description":"Unique identifier of the device specification","readOnly":true},"clientId":{"type":"string","format":"uuid","description":"id of the client that owns this device with this module state","readOnly":true},"projectId":{"type":"string","format":"uuid","description":"id of the project where this device with this module state reside","readOnly":true},"currentFirmwareVersion":{"type":"string","description":"The current firmware version of the module as reported by the device.","readOnly":true},"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."},"targetFirmwareVersionModifiedAt":{"type":"string","format":"date-time","description":"The timestamp when the target firmware was last modified.","readOnly":true},"firmwareUpdateStatus":{"type":"string","description":"The status of the firmware update process for the module.","readOnly":true},"firmwareUpdateStatusDetails":{"type":"string","description":"The status details of the firmware update process for the module.","readOnly":true},"firmwareUpdateStatusModifiedAt":{"type":"string","format":"date-time","description":"The timestamp when the firmware update status was last modified.","readOnly":true}},"required":["deviceId","moduleId"],"title":"FirmwareState"}}},"paths":{"/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"}},{"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"}},{"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"}},{"name":"deviceSpecificationIds","in":"query","description":"Filter devices by their device specification.","style":"form","explode":true,"schema":{"type":"array","items":{"type":"string","format":"uuid"}}},{"name":"moduleIds","in":"query","description":"Filter devices by their device specifications module identifier.","style":"form","explode":true,"schema":{"type":"array","items":{"type":"string","format":"uuid"}}},{"name":"currentFirmwareVersion","in":"query","description":"Filter devices by their current firmware version for the given module.","style":"form","explode":true,"schema":{"type":"string"}},{"name":"targetFirmwareVersion","in":"query","description":"Filter devices by their target firmware version for the given module.","style":"form","explode":true,"schema":{"type":"string"}},{"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"}},{"name":"firmwareUpdateStatus","in":"query","description":"Filter devices by their firmware update status for the given module.","style":"form","explode":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The requested firmware states.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PageOfFirmwareStates"}}}}}}}}}
```
## Set or reset the target firmware version for a list of devices.
> 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.
```json
{"openapi":"3.1.0","info":{"title":"Things Firmware Management API","version":"0.0.2"},"servers":[{"url":"https://api.kpnthings.com","description":"Things API Environment"}],"security":[{"BearerAuth":["device.update"]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"ListOfFirmwareStates":{"type":"object","description":"A list of firmware module states.","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/FirmwareState"},"minItems":1}},"required":["items"],"title":"ListOfFirmwareStates"},"FirmwareState":{"type":"object","description":"Describes the module state for a specific device.","properties":{"moduleId":{"type":"string","format":"uuid","description":"Unique identifier of the module"},"deviceId":{"type":"string","format":"uuid","description":"Unique identifier of the device"},"deviceSpecificationId":{"type":"string","format":"uuid","description":"Unique identifier of the device specification","readOnly":true},"clientId":{"type":"string","format":"uuid","description":"id of the client that owns this device with this module state","readOnly":true},"projectId":{"type":"string","format":"uuid","description":"id of the project where this device with this module state reside","readOnly":true},"currentFirmwareVersion":{"type":"string","description":"The current firmware version of the module as reported by the device.","readOnly":true},"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."},"targetFirmwareVersionModifiedAt":{"type":"string","format":"date-time","description":"The timestamp when the target firmware was last modified.","readOnly":true},"firmwareUpdateStatus":{"type":"string","description":"The status of the firmware update process for the module.","readOnly":true},"firmwareUpdateStatusDetails":{"type":"string","description":"The status details of the firmware update process for the module.","readOnly":true},"firmwareUpdateStatusModifiedAt":{"type":"string","format":"date-time","description":"The timestamp when the firmware update status was last modified.","readOnly":true}},"required":["deviceId","moduleId"],"title":"FirmwareState"},"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."},"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."},"status":{"type":"integer","format":"int32","description":"The HTTP status code generated by the origin server for this occurrence\nof the problem.","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."},"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."}},"title":"Problem"}},"responses":{"badRequest":{"description":"Request is missing required information or invalid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/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"}}}}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## 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, and the optional `goal` query parameter:
```
GET https://docs.kpnthings.com/kpn-things/general-functions/apis/firmwares.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
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.