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.

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

Retrieve firmware modules for device-specifications.

get

Retrieve firmware modules filtered by specified search criteria.

Required scopes

This endpoint requires the following scopes:

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

deviceSpecificationIdstring · uuidOptional

Device specification identifier.

Example: 12345678-1234-1234-1234-12345678abcd

clientIdstring · uuidOptional

Client identifier of the owner of the device specification to which this module belongs.

Example: 12345678-1234-1234-1234-12345678abcd

Responses

200

A list of firmware modules.

application/json

A list of modules

400

Request is missing required information or invalid

application/problem+json

get/firmware/modules

GET /firmware/modules HTTP/1.1
Host: api.kpnthings.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Retrieve a firmware module by ID.

get

Required scopes

This endpoint requires the following scopes:

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

moduleIdstring · uuidRequired

Module identifier.

Responses

200

The requested firmware module.

application/json

Describes a KPN Things Firmware Module. A module represent a part of a device for which the firmware is managed by KPN Things.

idstring · uuidRead-onlyRequired

Unique identifier of the module

Example: 99086060-b099-416e-a321-53220f4edf96

namestringRequired

The name of the module.

Example: Bluetooth ModulePattern: ^[\x20-\x7E]{1,100}$

firmwareVersionAttributeNamestringRequired

The name of the firmware version attribute sent by the device to report the current module firmware version.

Example: btModuleVersionPattern: ^[A-Za-z0-9_-]{1,100}$

deviceSpecificationIdstring · uuidRequired

id of the device specification to which the module belongs

Example: 99086060-b099-416e-a321-53220f4edf96

clientIdstring · uuidRead-onlyOptional

id of the client to which the module belongs

Example: 99086060-b099-416e-a321-53220f4edf96

createdAtstring · date-timeRead-onlyOptional

The timestamp when the module is created in the system.

Example: 2024-12-31T23:00:00.000Z

createdBystringRead-onlyOptional

The user who created the module.

Example: principal/9ebbb3b1-1b6b-46e7-8d58-bb8fe7ae24d4

modifiedAtstring · date-timeRead-onlyOptional

The timestamp when the module is last modified in the system.

Example: 2024-12-31T23:00:00.000Z

modifiedBystringRead-onlyOptional

The user who last modified the module.

Example: principal/9ebbb3b1-1b6b-46e7-8d58-bb8fe7ae24d4

400

Request is missing required information or invalid

application/problem+json

get/firmware/modules/{moduleId}

GET /firmware/modules/{moduleId} HTTP/1.1
Host: api.kpnthings.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Retrieve firmware packages

get

Retrieve firmware packages by client, device specification and / or module.

Required scopes

This endpoint requires the following scopes:

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

cursorstring · cursorOptional

String that encodes all necessary information to retrieve a page.

limitintegerOptional

Limit the number of results (per page).

Default: 50

sortstringOptional

Sorting fields separated by comma. Default order is Ascending (ASC), minus(-) should be used in front of field name for Descending (DESC) order.

Example: createdAt,-name

deviceSpecificationIdstring · uuidOptional

Device specification identifier.

Example: 12345678-1234-1234-1234-12345678abcd

moduleIdstring · uuidOptional

Firmware Module identifier.

Example: 12341234-1234-1234-1234-12345678abcd

clientIdstring · uuidOptional

Client identifier of the owner of the packages.

Example: 12341234-1234-1234-1234-12345678abcd

Responses

200

Page of firmware packages.

application/json

Page of items

nextstring · uriOptional

Pagination link pointing to the next page. Only provided when not at the last page.

prevstring · uriOptional

Pagination link pointing to the previous page. Only provided when not at the first page.

400

Request is missing required information or invalid

application/problem+json

get/firmware/packages

GET /firmware/packages HTTP/1.1
Host: api.kpnthings.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Create a firmware package for one of the modules of a device specification.

post

Required scopes

This endpoint requires the following scopes:

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

Firmware package definition with optional embedded entities

idstring · uuidRead-onlyRequired

Unique identifier of the firmware

Example: 99086060-b099-416e-a321-53220f4edf96

firmwareVersionstringRequired

The version of the firmware.

Example: 1.0.1Pattern: ^[a-zA-Z0-9._-]{1,100}$

clientIdstring · uuidOptional

id of the client to which the package belongs

Example: 99086060-b099-416e-a321-53220f4edf96

deviceSpecificationIdstring · uuidRequired

id of the device specification to which the firmware belongs

Example: 99086060-b099-416e-a321-53220f4edf96

moduleIdstring · uuidRequired

id of the module to which the firmware belongs

Example: 99086060-b099-416e-a321-53220f4edf96

descriptionstringOptional

Description of the firmware.

Example: Firmware package for Bluetooth module, for version 1.0.1 of the firmwarePattern: ^[\x20-\x7E]{1,300}$

firmwareFileNamestringRead-onlyOptional

Filename of the firmware.

Example: firmware_v1.0.1.bin

releaseNotesFileNamestringRead-onlyOptional

Filename of the release notes.

Example: release_notes_v1.0.1.txt

Responses

201

The newly created firmware.

application/json

Firmware package definition with optional embedded entities

idstring · uuidRead-onlyRequired

Unique identifier of the firmware

Example: 99086060-b099-416e-a321-53220f4edf96

firmwareVersionstringRequired

The version of the firmware.

Example: 1.0.1Pattern: ^[a-zA-Z0-9._-]{1,100}$

clientIdstring · uuidOptional

id of the client to which the package belongs

Example: 99086060-b099-416e-a321-53220f4edf96

deviceSpecificationIdstring · uuidRequired

id of the device specification to which the firmware belongs

Example: 99086060-b099-416e-a321-53220f4edf96

moduleIdstring · uuidRequired

id of the module to which the firmware belongs

Example: 99086060-b099-416e-a321-53220f4edf96

descriptionstringOptional

Description of the firmware.

Example: Firmware package for Bluetooth module, for version 1.0.1 of the firmwarePattern: ^[\x20-\x7E]{1,300}$

firmwareFileNamestringRead-onlyOptional

Filename of the firmware.

Example: firmware_v1.0.1.bin

releaseNotesFileNamestringRead-onlyOptional

Filename of the release notes.

Example: release_notes_v1.0.1.txt

400

Request is missing required information or invalid

application/problem+json

post/firmware/packages

POST /firmware/packages HTTP/1.1
Host: api.kpnthings.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*

No content

Retrieve a firmware package by ID.

get

Required scopes

This endpoint requires the following scopes:

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

firmwarePackageIdstring · uuidRequired

Firmware package identifier.

Example: 12345678-1234-1234-1234-12345678abcd

Query parameters

Responses

200

The requested firmware package.

application/json

Firmware package definition with optional embedded entities

idstring · uuidRead-onlyRequired

Unique identifier of the firmware

Example: 99086060-b099-416e-a321-53220f4edf96

firmwareVersionstringRequired

The version of the firmware.

Example: 1.0.1Pattern: ^[a-zA-Z0-9._-]{1,100}$

clientIdstring · uuidOptional

id of the client to which the package belongs

Example: 99086060-b099-416e-a321-53220f4edf96

deviceSpecificationIdstring · uuidRequired

id of the device specification to which the firmware belongs

Example: 99086060-b099-416e-a321-53220f4edf96

moduleIdstring · uuidRequired

id of the module to which the firmware belongs

Example: 99086060-b099-416e-a321-53220f4edf96

descriptionstringOptional

Description of the firmware.

Example: Firmware package for Bluetooth module, for version 1.0.1 of the firmwarePattern: ^[\x20-\x7E]{1,300}$

firmwareFileNamestringRead-onlyOptional

Filename of the firmware.

Example: firmware_v1.0.1.bin

releaseNotesFileNamestringRead-onlyOptional

Filename of the release notes.

Example: release_notes_v1.0.1.txt

400

Request is missing required information or invalid

application/problem+json

get/firmware/packages/{firmwarePackageId}

GET /firmware/packages/{firmwarePackageId} HTTP/1.1
Host: api.kpnthings.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Update a firmware package.

put

Update the description of a firmware package. Note that the firmwareVersion, deviceSpecificationId and moduleId can not be modified.

Required scopes

This endpoint requires the following scopes:

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

firmwarePackageIdstring · uuidRequired

Firmware identifier.

Example: 12345678-1234-1234-1234-12345678abcd

Body

Firmware package definition with optional embedded entities

idstring · uuidRead-onlyRequired

Unique identifier of the firmware

Example: 99086060-b099-416e-a321-53220f4edf96

firmwareVersionstringRequired

The version of the firmware.

Example: 1.0.1Pattern: ^[a-zA-Z0-9._-]{1,100}$

clientIdstring · uuidOptional

id of the client to which the package belongs

Example: 99086060-b099-416e-a321-53220f4edf96

deviceSpecificationIdstring · uuidRequired

id of the device specification to which the firmware belongs

Example: 99086060-b099-416e-a321-53220f4edf96

moduleIdstring · uuidRequired

id of the module to which the firmware belongs

Example: 99086060-b099-416e-a321-53220f4edf96

descriptionstringOptional

Description of the firmware.

Example: Firmware package for Bluetooth module, for version 1.0.1 of the firmwarePattern: ^[\x20-\x7E]{1,300}$

firmwareFileNamestringRead-onlyOptional

Filename of the firmware.

Example: firmware_v1.0.1.bin

releaseNotesFileNamestringRead-onlyOptional

Filename of the release notes.

Example: release_notes_v1.0.1.txt

Responses

201

The updated firmware.

application/json

Firmware package definition with optional embedded entities

idstring · uuidRead-onlyRequired

Unique identifier of the firmware

Example: 99086060-b099-416e-a321-53220f4edf96

firmwareVersionstringRequired

The version of the firmware.

Example: 1.0.1Pattern: ^[a-zA-Z0-9._-]{1,100}$

clientIdstring · uuidOptional

id of the client to which the package belongs

Example: 99086060-b099-416e-a321-53220f4edf96

deviceSpecificationIdstring · uuidRequired

id of the device specification to which the firmware belongs

Example: 99086060-b099-416e-a321-53220f4edf96

moduleIdstring · uuidRequired

id of the module to which the firmware belongs

Example: 99086060-b099-416e-a321-53220f4edf96

descriptionstringOptional

Description of the firmware.

Example: Firmware package for Bluetooth module, for version 1.0.1 of the firmwarePattern: ^[\x20-\x7E]{1,300}$

firmwareFileNamestringRead-onlyOptional

Filename of the firmware.

Example: firmware_v1.0.1.bin

releaseNotesFileNamestringRead-onlyOptional

Filename of the release notes.

Example: release_notes_v1.0.1.txt

400

Request is missing required information or invalid

application/problem+json

put/firmware/packages/{firmwarePackageId}

PUT /firmware/packages/{firmwarePackageId} HTTP/1.1
Host: api.kpnthings.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*

No content

Delete a firmware package by ID.

delete

Required scopes

This endpoint requires the following scopes:

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

firmwarePackageIdstring · uuidRequired

Firmware package identifier.

Example: 12345678-1234-1234-1234-12345678abcd

Responses

204

Firmware package has been deleted successfully.

No content

delete/firmware/packages/{firmwarePackageId}

DELETE /firmware/packages/{firmwarePackageId} HTTP/1.1
Host: api.kpnthings.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

204

Firmware package has been deleted successfully.

No content

Download the firmware file of a firmware package.

get

Download the firmware file of a firmware package. Only one file can be downloaded per request, so the firmwarePackageId query parameter is required.

Required scopes

This endpoint requires the following scopes:

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

firmwarePackageIdstring · uuidRequired

Firmware identifier.

Example: 12345678-1234-1234-1234-12345678abcd

Responses

200

The requested file in binary format.

application/json

string · binaryOptional

400

Request is missing required information or invalid

application/problem+json

get/firmware/packages/{firmwarePackageId}/firmware-file

GET /firmware/packages/{firmwarePackageId}/firmware-file HTTP/1.1
Host: api.kpnthings.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Upload a firmware file for a firmware package.

post

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.

Required scopes

This endpoint requires the following scopes:

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

firmwarePackageIdstring · uuidRequired

Firmware identifier.

Example: 12345678-1234-1234-1234-12345678abcd

Body

Multipart form-data body for uploading a firmware file.

filestring · binaryRequired

The firmware file to upload.

checksumstringOptional

The SHA-256 checksum of the firmware file. This is used to verify the integrity of the file after upload.

Example: 3a7bd3e2360a3d80e355b8cbb1b1b9e0e5c6a8f9d2e5c3f1a2b4c5d6e7f8Pattern: ^[0-9a-fA-F]+$

Responses

200

The information about the uploaded file for a device specification.

application/json

Represents a file

firmwarePackageIdstring · uuidRead-onlyOptional

The id of the firmware package to which the file belongs

Example: 99086060-b099-416e-a321-53220f4edf96

namestringRequired

Name of the file

Example: firmware.binPattern: ^[a-zA-Z0-9.-_]{1,100}$

contentTypestringRequired

Content-Type of the file

Example: application/octet-streamPattern: ^[\x20-\x7E]{1,100}$

fileTypestringOptional

The type of the file

Example: firmware

deviceSpecificationIdstring · uuidRead-onlyOptional

The id of the device specification to which the file belongs

Example: 99086060-b099-416e-a321-53220f4edf96

createdAtstring · date-timeRead-onlyOptional

The timestamp this file was created

Example: 2024-12-31T23:00:00.000Z

createdBystringRead-onlyOptional

The identifier of the user that created this file

Example: principal/9ebbb3b1-1b6b-46e7-8d58-bb8fe7ae24d4

modifiedAtstring · date-timeRead-onlyOptional

The timestamp this file was last modified

Example: 2024-12-31T23:00:00.000Z

modifiedBystringRead-onlyOptional

The identifier of the user that last modified this file

Example: principal/9ebbb3b1-1b6b-46e7-8d58-bb8fe7ae24d4

400

Request is missing required information or invalid

application/problem+json

post/firmware/packages/{firmwarePackageId}/firmware-file

POST /firmware/packages/{firmwarePackageId}/firmware-file HTTP/1.1
Host: api.kpnthings.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: multipart/form-data
Accept: */*

No content

Download the release notes file of a firmware package.

get

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.

Required scopes

This endpoint requires the following scopes:

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

firmwarePackageIdstring · uuidRequired

Firmware identifier.

Example: 12345678-1234-1234-1234-12345678abcd

Responses

200

The requested file in binary format.

application/json

string · binaryOptional

400

Request is missing required information or invalid

application/problem+json

get/firmware/packages/{firmwarePackageId}/release-notes-file

GET /firmware/packages/{firmwarePackageId}/release-notes-file HTTP/1.1
Host: api.kpnthings.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Upload a release notes file for a firmware package.

post

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.

Required scopes

This endpoint requires the following scopes:

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

firmwarePackageIdstring · uuidRequired

Firmware identifier.

Example: 12345678-1234-1234-1234-12345678abcd

Body

Multipart form-data body for uploading a firmware file.

filestring · binaryRequired

The firmware file to upload.

checksumstringOptional

The SHA-256 checksum of the firmware file. This is used to verify the integrity of the file after upload.

Example: 3a7bd3e2360a3d80e355b8cbb1b1b9e0e5c6a8f9d2e5c3f1a2b4c5d6e7f8Pattern: ^[0-9a-fA-F]+$

Responses

200

The information about the uploaded file.

application/json

Represents a file

firmwarePackageIdstring · uuidRead-onlyOptional

The id of the firmware package to which the file belongs

Example: 99086060-b099-416e-a321-53220f4edf96

namestringRequired

Name of the file

Example: firmware.binPattern: ^[a-zA-Z0-9.-_]{1,100}$

contentTypestringRequired

Content-Type of the file

Example: application/octet-streamPattern: ^[\x20-\x7E]{1,100}$

fileTypestringOptional

The type of the file

Example: firmware

deviceSpecificationIdstring · uuidRead-onlyOptional

The id of the device specification to which the file belongs

Example: 99086060-b099-416e-a321-53220f4edf96

createdAtstring · date-timeRead-onlyOptional

The timestamp this file was created

Example: 2024-12-31T23:00:00.000Z

createdBystringRead-onlyOptional

The identifier of the user that created this file

Example: principal/9ebbb3b1-1b6b-46e7-8d58-bb8fe7ae24d4

modifiedAtstring · date-timeRead-onlyOptional

The timestamp this file was last modified

Example: 2024-12-31T23:00:00.000Z

modifiedBystringRead-onlyOptional

The identifier of the user that last modified this file

Example: principal/9ebbb3b1-1b6b-46e7-8d58-bb8fe7ae24d4

400

Request is missing required information or invalid

application/problem+json

post/firmware/packages/{firmwarePackageId}/release-notes-file

POST /firmware/packages/{firmwarePackageId}/release-notes-file HTTP/1.1
Host: api.kpnthings.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: multipart/form-data
Accept: */*

No content

Delete the release notes file of a firmware package.

delete

Required scopes

This endpoint requires the following scopes:

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

firmwarePackageIdstring · uuidRequired

Firmware package identifier.

Example: 12345678-1234-1234-1234-12345678abcd

Responses

204

Deleted the release notes file.

No content

400

Request is missing required information or invalid

application/problem+json

delete/firmware/packages/{firmwarePackageId}/release-notes-file

DELETE /firmware/packages/{firmwarePackageId}/release-notes-file HTTP/1.1
Host: api.kpnthings.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Retrieve firmware states.

get

Retrieve firmware states for devices filtered by specified search criteria

Required scopes

This endpoint requires the following scopes:

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

cursorstring · cursorOptional

String that encodes all necessary information to retrieve a page.

limitintegerOptional

Limit the number of results (per page).

Default: 50

sortstringOptional

Sorting fields separated by comma. Default order is Ascending (ASC), minus(-) should be used in front of field name for Descending (DESC) order.

Example: createdAt,-name

clientIdstring · uuidOptional

Include only devices that match the provided owner clientId. If clientId is omitted, all devices are included.

Example: 79658ca8-f1ba-4c25-b824-93813e9fba76

projectIdstring · uuidOptional

Include only devices that match the provided projectId. If projectId is omitted, all devices are included.

Example: 79658ca8-f1ba-4c25-b824-93813e9fba76

deviceIdstring · uuidOptional

Include only devices that match the provided deviceId. If projectId is omitted, all devices are included.

Example: 79658ca8-f1ba-4c25-b824-93813e9fba76

deviceSpecificationIdsstring · uuid[]Optional

Filter devices by their device specification.

Example: ["37186a83-ef07-4c03-a9b5-0d385565188e"]

moduleIdsstring · uuid[]Optional

Filter devices by their device specifications module identifier.

Example: ["37186a83-ef07-4c03-a9b5-0d385565188e"]

currentFirmwareVersionstringOptional

Filter devices by their current firmware version for the given module.

Example: 1

targetFirmwareVersionstringOptional

Filter devices by their target firmware version for the given module.

Example: 1

firmwareUpdateStartedAtstring · date-timeOptional

Filter devices by the date and time of their firmware update start for the given module.

Example: 2024-01-01T00:00:00.000Z

firmwareUpdateStatusstringOptional

Filter devices by their firmware update status for the given module.

Example: IDLE

Responses

200

The requested firmware states.

application/json

Page of items

nextstring · uriOptional

Pagination link pointing to the next page. Only provided when not at the last page.

prevstring · uriOptional

Pagination link pointing to the previous page. Only provided when not at the first page.

get/firmware/states

GET /firmware/states HTTP/1.1
Host: api.kpnthings.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

The requested firmware states.

No content

Set or reset the target firmware version for a list of devices.

post

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.

Required scopes

This endpoint requires the following scopes:

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

A list of firmware module states.

Responses

200

The target firmware has been set successfully for all specified devices.

No content

400

Request is missing required information or invalid

application/problem+json

post/firmware/states/target-firmware-requests

POST /firmware/states/target-firmware-requests HTTP/1.1
Host: api.kpnthings.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*

No content