Devices

Download the specification

In addition to the standard create, retrieve, update, delete, and list actions, devices expose two important sub-collections.

The device-groups sub-resource allows you to view and manage the groups a device belongs to, complementing the platform’s top-level /device-groups resource.

The network-adapters sub-resource provides access to the physical connectivity interfaces of a device—such as cellular (IMEI-based), LoRa (DevEUI-based), or generic internet adapters—which determine how the device connects to the platform.

Retrieve devices, filtered by search term and / or client ID.

get

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

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

qstring · min: 1Optional

Include only devices whose name or description contain the search term. Matching is done case-insensitively.

clientIdstring · uuidOptional

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

barcodestringOptional

Include only devices owned by the client partially matching barcode.

deviceSpecificationIdstring · uuid[]Optional

Filter devices by their device specification.

Example: null

createdBeforestring · date-timeOptional

Include only devices created before the provided date and time. The date-time must be in ISO 8601 format.

createdSincestring · date-timeOptional

Include only devices created at or after the provided date and time. The date-time must be in ISO 8601 format.

modifiedBeforestring · date-timeOptional

Include only devices modified before the provided date and time. The date-time must be in ISO 8601 format.

modifiedSincestring · date-timeOptional

Include only devices modified at or after the provided date and time. The date-time must be in ISO 8601 format.

Responses

200

Page of filtered devices. Only devices that are accessible to the caller are returned.

application/json

400

Request is missing required information or invalid

application/problem+json

get

/devices

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

No content

Create a new device.

post

Create a new device.

Required scopes

This endpoint requires the following scopes:

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

idstring · uuidRead-onlyOptional

The id of the device

Example: 36e75427-4c6e-438c-89b5-0cbdb0d4068c

createdAtstring · date-timeRead-onlyOptional

The timestamp when the device is created in the system.

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

createdBystringRead-onlyOptional

The user who created the device.

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

modifiedAtstring · date-timeRead-onlyOptional

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

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

modifiedBystringRead-onlyOptional

The user who last modified the device.

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

namestring · min: 1 · max: 255Required

Name of this device

Example: My first devicePattern: ^(?!\s*$).+

statusstringOptional

Status of the device. Known values include: ACTIVE and INACTIVE

barcodestringOptional

Barcode of the device

Example: 123456789

descriptionstring · max: 255Optional

Description of this device

Example: Device to explore KPN Things

clientIdstring · uuidRequired

ID of owning client

Example: 7098dc22-fed5-4d9e-8e68-6c6f853eac0c

projectIdstring · uuidRequired

ID of the project the device belongs to

Example: b6a883a8-41f9-428e-a8a1-4597de54fec6

deviceSpecificationIdstring · uuidRequired

ID of the device specification of the device

Example: 9c359e94-ace1-448c-8ac9-443a7d3d963f

_embeddedall ofOptional

and

Responses

201

The newly created device.

application/json

400

Request is missing required information or invalid

application/problem+json

post

/devices

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

No content

Retrieve a device by ID.

get

Required scopes

This endpoint requires the following scopes:

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

deviceIdstring · uuidRequired

Device identifier.

Responses

200

The device.

application/json

400

Request is missing required information or invalid

application/problem+json

get

/devices/{deviceId}

GET /devices/{deviceId} HTTP/1.1
Host: api.kpnthings.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Update a device.

put

Required scopes

This endpoint requires the following scopes:

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

deviceIdstring · uuidRequired

Device identifier.

Body

idstring · uuidRead-onlyOptional

The id of the device

Example: 36e75427-4c6e-438c-89b5-0cbdb0d4068c

createdAtstring · date-timeRead-onlyOptional

The timestamp when the device is created in the system.

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

createdBystringRead-onlyOptional

The user who created the device.

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

modifiedAtstring · date-timeRead-onlyOptional

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

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

modifiedBystringRead-onlyOptional

The user who last modified the device.

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

namestring · min: 1 · max: 255Required

Name of this device

Example: My first devicePattern: ^(?!\s*$).+

statusstringOptional

Status of the device. Known values include: ACTIVE and INACTIVE

barcodestringOptional

Barcode of the device

Example: 123456789

descriptionstring · max: 255Optional

Description of this device

Example: Device to explore KPN Things

clientIdstring · uuidRequired

ID of owning client

Example: 7098dc22-fed5-4d9e-8e68-6c6f853eac0c

projectIdstring · uuidRequired

ID of the project the device belongs to

Example: b6a883a8-41f9-428e-a8a1-4597de54fec6

deviceSpecificationIdstring · uuidRequired

ID of the device specification of the device

Example: 9c359e94-ace1-448c-8ac9-443a7d3d963f

_embeddedall ofOptional

and

Responses

200

The updated device.

application/json

put

/devices/{deviceId}

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

200

The updated device.

No content

Delete a device.

delete

Required scopes

This endpoint requires the following scopes:

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

deviceIdstring · uuidRequired

Device identifier.

Responses

204

Device has been deleted successfully.

No content

409

Conflict - Multiple possible reasons

application/json

delete

/devices/{deviceId}

DELETE /devices/{deviceId} HTTP/1.1
Host: api.kpnthings.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Retrieve the device groups a device is linked to.

get

Required scopes

This endpoint requires the following scopes:

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

deviceIdstring · uuidRequired

The ID of the device for which to retrieve linked device groups.

Query parameters

createdBeforestring · date-timeOptional

Include only links created before the provided date and time. The date-time must be in ISO 8601 format.

createdSincestring · date-timeOptional

Include only links created at or after the provided date and time. The date-time must be in ISO 8601 format.

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

Responses

200

Page of devices groups linked to the specified device.

application/json

get

/devices/{deviceId}/device-groups

GET /devices/{deviceId}/device-groups HTTP/1.1
Host: api.kpnthings.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

Page of devices groups linked to the specified device.

No content

Retrieve the link between a device and a device group.

get

Required scopes

This endpoint requires the following scopes:

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

deviceIdstring · uuidRequired

The ID of the device for which to retrieve the link to the device group.

deviceGroupIdstring · uuidRequired

The ID of the device group for which to retrieve the link to the device.

Query parameters

Responses

200

The link between the specified device and device group.

application/json

get

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

GET /devices/{deviceId}/device-groups/{deviceGroupId} HTTP/1.1
Host: api.kpnthings.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

The link between the specified device and device group.

No content

Retrieve the network adapters attached to a device.

get

Required scopes

This endpoint requires the following scopes:

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

deviceIdstring · uuidRequired

The ID of the device for which to retrieve network adapters.

Query parameters

typestringOptional

Include only network adapters of this type. Known values are: cellular, generic, lora.

Responses

200

List of network adapters attached to the specified device.

application/json

get

/devices/{deviceId}/network-adapters

GET /devices/{deviceId}/network-adapters HTTP/1.1
Host: api.kpnthings.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

List of network adapters attached to the specified device.

No content

Add a network adapter to a device

post

Required scopes

This endpoint requires the following scopes:

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

deviceIdstring · uuidRequired

The ID of the device for which to add a network adapter.

Body

A network adapter

Responses

201

The newly created network adapter.

application/json

post

/devices/{deviceId}/network-adapters

POST /devices/{deviceId}/network-adapters HTTP/1.1
Host: api.kpnthings.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*

201

The newly created network adapter.

No content

Update a network adapter.

put

Required scopes

This endpoint requires the following scopes:

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

deviceIdstring · uuidRequired

The ID of the device for which to update the network adapter.

adapterIdstring · uuidRequired

The ID of the network adapter to update.

Body

A network adapter

Responses

200

The updated network adapter.

application/json

put

/devices/{deviceId}/network-adapters/{adapterId}

PUT /devices/{deviceId}/network-adapters/{adapterId} HTTP/1.1
Host: api.kpnthings.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*

200

The updated network adapter.

No content

Delete a network adapter.

delete

Required scopes

This endpoint requires the following scopes:

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

deviceIdstring · uuidRequired

The ID of the device for which to delete the network adapter.

adapterIdstring · uuidRequired

The ID of the network adapter to delete.

Responses

204

Network adapter has been deleted successfully.

No content

delete

/devices/{deviceId}/network-adapters/{adapterId}

DELETE /devices/{deviceId}/network-adapters/{adapterId} HTTP/1.1
Host: api.kpnthings.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

204

Network adapter has been deleted successfully.

No content

PreviousConnector Bindings NextDevice Groups

Last updated 1 day ago

Was this helpful?