Improve this doc
Detailed information for resources

balenaCloud API Resources

Note: We recently renamed applications to fleets and are in the process of updating our API resources. Application resources continue to function correctly and can be used to work with fleets. Find out more about the changes here.

Available fields

id
belongs_to__application
belongs_to__user
is_managed_by__device
actor
should_be_running__release
device_name
is_of__device_type
uuid
is_running__release
note
local_id
status
overall_status
is_online
last_connectivity_event
is_connected_to_vpn
last_vpn_event
ip_address
mac_address
public_address
os_version
os_variant
supervisor_version
should_be_managed_by__supervisor_release
is_managed_by__service_instance
provisioning_progress
provisioning_state
download_progress
is_web_accessible
longitude
latitude
location
custom_longitude
custom_latitude
logs_channel
is_locked_until__date
is_accessible_by_support_until__date
created_at
is_active
api_heartbeat_state
memory_usage
memory_total
storage_block_device
storage_usage
storage_total
cpu_temp
cpu_usage
cpu_id
is_undervolted

Examples

Get all devices

curl -X GET \
"https://api.balena-cloud.com/v6/device" \
-H  "Content-Type: application/json"  \
-H "Authorization: Bearer <AUTH_TOKEN>" 

Get all devices by fleet

curl -X GET \
"https://api.balena-cloud.com/v6/device?\$filter=belongs_to__application%20eq%20'<FLEET ID>'" \
-H  "Content-Type: application/json"  \
-H "Authorization: Bearer <AUTH_TOKEN>" 

Get device by ID

curl -X GET \
"https://api.balena-cloud.com/v6/device(<ID>)" \
-H  "Content-Type: application/json"  \
-H "Authorization: Bearer <AUTH_TOKEN>" 

Get device by UUID

curl -X GET \
"https://api.balena-cloud.com/v6/device(uuid='<UUID>')" \
-H  "Content-Type: application/json"  \
-H "Authorization: Bearer <AUTH_TOKEN>" 

Get the device overall_status field

The overall_status field is returned only when explicitly requested with $select.

curl -X GET \
"https://api.balena-cloud.com/v6/device(<ID>)?\$select=overall_status" \
-H  "Content-Type: application/json"  \
-H "Authorization: Bearer <AUTH_TOKEN>" 

Get the release device is pinned to

Note: should_be_running__release will be unset or null if the device isn't pinned to any release. For an unpinned device, the device.is_running__release field may be used to obtain the device's current state.

curl -X GET \
"https://api.balena-cloud.com/v6/device(<ID>)?\$select=should_be_running__release" \
-H  "Content-Type: application/json"  \
-H "Authorization: Bearer <AUTH_TOKEN>" 

Pin device to a specific release by ID

curl -X PATCH \
"https://api.balena-cloud.com/v6/device(<ID>)" \
-H  "Content-Type: application/json"  \
-H "Authorization: Bearer <AUTH_TOKEN>" \
--data '{
    "should_be_running__release": "<RELEASE ID>"
}'

Pin device to a specific release by UUID

curl -X PATCH \
"https://api.balena-cloud.com/v6/device(uuid='<UUID>')" \
-H  "Content-Type: application/json"  \
-H "Authorization: Bearer <AUTH_TOKEN>" \
--data '{
    "should_be_running__release": "<RELEASE ID>"
}'

Mark a device to be updated to a specific supervisor release

To request a list of available supervisor versions, check the respective documentation page for the supervisor release resource.

curl -X PATCH \
"https://api.balena-cloud.com/v6/device(uuid='<UUID>')" \
-H  "Content-Type: application/json"  \
-H "Authorization: Bearer <AUTH_TOKEN>" \
--data '{
    "should_be_managed_by__supervisor_release": "<SUPERVISOR RELEASE ID>"
}'

Rename device

curl -X PATCH \
"https://api.balena-cloud.com/v6/device(<ID>)" \
-H  "Content-Type: application/json"  \
-H "Authorization: Bearer <AUTH_TOKEN>" \
--data '{
    "device_name": "<NEW NAME>"
}'

Delete device

curl -X DELETE \
"https://api.balena-cloud.com/v6/device(<ID>)" \
-H  "Content-Type: application/json"  \
-H "Authorization: Bearer <AUTH_TOKEN>" 

Add note to a device

curl -X PATCH \
"https://api.balena-cloud.com/v6/device(<ID>)" \
-H  "Content-Type: application/json"  \
-H "Authorization: Bearer <AUTH_TOKEN>" \
--data '{
    "note": "<NEW NOTE>"
}'

Move device to another fleet

curl -X PATCH \
"https://api.balena-cloud.com/v6/device(<ID>)" \
-H  "Content-Type: application/json"  \
-H "Authorization: Bearer <AUTH_TOKEN>" \
--data '{
    "belongs_to__application": "<FLEET ID>"
}'

Deactivate an offline device (CHARGEABLE)

curl -X PATCH \
"https://api.balena-cloud.com/v6/device(<ID>)" \
-H  "Content-Type: application/json"  \
-H "Authorization: Bearer <AUTH_TOKEN>" \
--data '{
    "is_active": false
}'