Skip to content

Device

The Device API manages device registation with the Builder.

When devices are first booted, they will "register" with the builder using their device ID (ClaimID). The device then remains under the management of the Builder until it is "claimed" by a user for management using the "claim" API.

When claimed, the device is redirected to the device cloud when it next invokes the "register" API.


Get

The Get API will fetch a device record by its ID (ClaimID).

Endpoint

1
POST /device/get

Authorized Role/Capability

1
user

JSON Body Fields

Field Type Required Notes
id string yes Device Claim ID

Response

Field Type Notes
accessed date When the device was last accessed
accountId string Owning manager account ID
created date When the device was first connected
id string Device Claim ID
productId string Product ID
version string Firmware version

Claim

Claim a device for management by a device cloud.

Once a device has registered itself with the builder, a user can claim the device for management. The claim ID would typically be printed on the device label during manufacturer.

A claim request may specify the device as a test device where it will not be counted towards the subscription device count.

Endpoint

1
POST /device/claim

Authorized Role/Capability

1
claimDevice

JSON Body Fields

Field Type Required Notes
id string yes Device claim ID

Response

The claimed device.

Field Type Notes
accessed date When the device was last accessed
accountId string Owning manager account ID
created date When the device was first connected
id string Device Claim ID
productId string Product ID
version string Firmware version

Find

Find matching devices.

Endpoint

1
POST /device/find

Authorized Role/Capability

1
user

Response

An array of devices owned by the user.

Field Type Notes
accessed date When the device was last accessed
accountId string Owning manager account ID
created date When the device was first connected
id string Device Claim ID
productId string Product ID
version string Firmware version

Query Path

Field Type Notes
filter string Simple filter string to filter
next object Pagination token for the next page
prev object Pagination token for the previous page
limit number Number of items to retrieve. Defaults to 1.
where string Where clause to filter

Remove

Release a device from management by a device cloud

Releasing a device returns it to the builder to be available for claiming by another cloud.

Endpoint

1
POST /device/remove

Authorized Role/Capability

1
releaseDevice

JSON Body Fields

Field Type Required Notes
id string yes Device claim ID