Ctrlk
ForumsBlogPricingContactLoginSignup
For the complete documentation index, see llms.txt. This page is also available as Markdown.

v14.5.0 (DEPRECATED)

Welcome to the balena python SDK documentation. This document aims to describe all the functions supported by the SDK, as well as showing examples of their expected usage.

Install the Balena SDK:

From Pip:

pip install balena-sdk

From Source (In case, you want to test a development branch):

https://github.com/balena-io/balena-sdk-python

Getting started:

>>> from balena import Balena
>>> balena = Balena()
>>> credentials = {'username':<your email>, 'password':<your password>}
>>> balena.auth.login(**credentials)
...

The Balena object can be configured with a dict of type Settings

balena = Balena({
    "balena_host": "balena-cloud.com",
    "api_version": "v6",
    "device_actions_endpoint_version": "v1",
    "data_directory": "/home/example/.balena",
    "image_cache_time": str(1 * 1000 * 60 * 60 * 24 * 7), # 1 week
    "token_refresh_interval": str(1 * 1000 * 60 * 60),    # 1 hour
    "timeout": str(30 * 1000),                            # request timeout, 30s
    "request_limit": str(300), # the number of requests per request_limit_interval that the SDK should respect, defaults to unlimited.
    "request_limit_interval": str(60), # the timespan that the request_limit should apply to in seconds, defaults to 60s (1 minute).
    "retry_rate_limited_request": False, # awaits and retry once a request is rate limited (429)
})

Notice that if you want to change for the staging environment, you could simply do: balena = Balena({"balena_host": "balena-staging.com"})

However, this will overwrite your balena-cloud settings (stored api keys etc). So we recommend using a different data_directory for each balena-sdk instance, e.g:

In adition, you can also run balena-python-sdk completely in memory, without writing anything to the file system like:

By default the SDK will throw once a request is Rate limited by the API (with a 429 status code). A 429 request will contain a header called "retry-after" which informs how long the client should wait before trying a new request. If you would like the SDK to use this header and wait and automatically retry the request, just do:

If you feel something is missing, not clear or could be improved, please don't hesitate to open an issue in GitHub, we'll be happy to help.

Table of Contents

Models

This module implements all models for balena python SDK.

Application

This class implements application model for balena python SDK.

Function: create(name, device_type, organization, application_class) ⇒ TypeApplication

Create an application.

Args:

Returns:

Examples:

Function: disable_device_urls(slug_or_uuid_or_id) ⇒ None

Disable device urls for all devices that belong to an application.

Args:

Examples:

Function: enable_device_urls(slug_or_uuid_or_id) ⇒ None

Enable device urls for all devices that belong to an application

Args:

Examples:

Function: generate_provisioning_key(slug_or_uuid_or_id, key_name, description, expiry_date) ⇒ str

Generate a device provisioning key for a specific application.

Args:

Returns:

Examples:

Function: get(slug_or_uuid_or_id, options, context) ⇒ TypeApplication

Get a single application.

Args:

Returns:

Examples:

Function: get_all(options, context) ⇒ List[TypeApplication]

Get all applications

Args:

Returns:

Examples:

Function: get_all_by_organization(org_handle_or_id, options) ⇒ List[TypeApplication]

Get all applications of an organization.

Args:

Returns:

Examples:

Function: get_all_directly_accessible(options) ⇒ List[TypeApplication]

Get all applications directly accessible by the user

Args:

Returns:

Examples:

Function: get_by_name(app_name, options, context) ⇒ TypeApplication

Get a single application using the appname.

Args:

Returns:

Examples:

Function: get_by_owner(app_name, owner, options) ⇒ TypeApplication

Get a single application using the appname and the handle of the owning organization.

Args:

Returns:

Examples:

Function: get_dashboard_url(app_id) ⇒ str

Get Dashboard URL for a specific application.

Args:

Returns:

Examples:

Function: get_directly_accessible(slug_or_uuid_or_id, options) ⇒ TypeApplication

Get a single application directly accessible by the user

Args:

Returns:

Examples:

Function: get_id(slug_or_uuid_or_id) ⇒ int

Given an application slug or uuid or id, returns it numeric id.

Args:

Returns:

Examples:

Function: get_target_release_hash(slug_or_uuid_or_id) ⇒ Optional[str]

Get the hash of the current release for a specific application.

Args:

Returns:

Examples:

Function: get_with_device_service_details(slug_or_uuid_or_id, options) ⇒ TypeApplicationWithDeviceServiceDetails

This method does not map exactly to the underlying model: it runs a larger prebuilt query, and reformats it into an easy to use and understand format. If you want more control, or to see the raw model directly, use application.get(uuidOrId, options) instead.

Args:

Returns:

Examples:

Function: grant_support_access(slug_or_uuid_or_id, expiry_timestamp) ⇒ None

Grant support access to an application until a specified time.

Args:

Examples:

Function: has(slug_or_uuid_or_id) ⇒ bool

Check if an application exists.

Args:

Returns:

Examples:

Function: has_any() ⇒ bool

Check if the user has any applications.

Returns:

Examples:

Function: is_tracking_latest_release(slug_or_uuid_or_id) ⇒ bool

Get whether the application is up to date and is tracking the latest finalized release for updates

Args:

Returns:

Examples:

Function: pin_to_release(slug_or_uuid_or_id, full_release_hash) ⇒ None

Configures the application to run a particular release and not get updated when the latest release changes.

Args:

Examples:

Function: purge(app_id) ⇒ None

Purge devices by application id

Args:

Examples:

Function: reboot(app_id, options) ⇒ None

Reboots devices by application id

Args:

Examples:

Function: remove(slug_or_uuid_or_id) ⇒ None

Remove application.

Args:

Examples:

Function: rename(slug_or_uuid_or_id, new_name) ⇒ None

Rename application.

Args:

Examples:

Function: restart(slug_or_uuid_or_id) ⇒ None

Restart application.

Args:

Examples:

Function: revoke_support_access(slug_or_uuid_or_id) ⇒ None

Revoke support access to an application.

Args:

Examples:

Function: shutdown(app_id, options) ⇒ None

Shutdown devices by application id

Args:

Examples:

Function: track_latest_release(slug_or_uuid_or_id) ⇒ None

Configure a specific application to track the latest available release.

Args:

Examples:

Function: will_track_new_releases(slug_or_uuid_or_id) ⇒ bool

Get whether the application is configured to receive updates whenever a new release is available.

Args:

Returns:

Examples:

ApplicationTag

This class implements application tag model for balena python SDK.

Function: get_all_by_application(slug_or_uuid_or_id, options) ⇒ List[BaseTagType]

Get all application tags for an application.

Args:

Returns:

Examples:

Function: remove(slug_or_uuid_or_id, tag_key) ⇒ None

Remove an application tag.

Args:

Examples:

Function: set(slug_or_uuid_or_id, tag_key, value) ⇒ None

Set an application tag (update tag value if it exists).

Args:

Returns:

Examples:

ApplicationConfigVariable

This class implements application config variable model for balena python SDK.

Function: get(slug_or_uuid_or_id, env_var_name) ⇒ Optional[str]

Get application config variable.

Args:

Examples:

Function: get_all_by_application(slug_or_uuid_or_id, options) ⇒ List[EnvironmentVariableBase]

Get all application config variables by application.

Args:

Returns:

Examples:

Function: remove(slug_or_uuid_or_id, key) ⇒ None

Remove an application config variable.

Args:

Examples:

Function: set(slug_or_uuid_or_id, env_var_name, value) ⇒ None

Set the value of a specific application config variable.

Args:

Examples:

ApplicationEnvVariable

This class implements application environment variable model for balena python SDK.

Function: get(slug_or_uuid_or_id, env_var_name) ⇒ Optional[str]

Get application environment variable.

Args:

Examples:

Function: get_all_by_application(slug_or_uuid_or_id, options) ⇒ List[EnvironmentVariableBase]

Get all application environment variables by application.

Args:

Returns:

Examples:

Function: remove(slug_or_uuid_or_id, key) ⇒ None

Remove an application environment variable.

Args:

Examples:

Function: set(slug_or_uuid_or_id, env_var_name, value) ⇒ None

Set the value of a specific application environment variable.

Args:

Examples:

BuildEnvVariable

This class implements build environment variable model for balena python SDK.

Function: get(slug_or_uuid_or_id, env_var_name) ⇒ Optional[str]

Get build environment variable.

Args:

Examples:

Function: get_all_by_application(slug_or_uuid_or_id, options) ⇒ List[EnvironmentVariableBase]

Get all build environment variables by application.

Args:

Returns:

Examples:

Function: remove(slug_or_uuid_or_id, key) ⇒ None

Remove an build environment variable.

Args:

Examples:

Function: set(slug_or_uuid_or_id, env_var_name, value) ⇒ None

Set the value of a specific build environment variable.

Args:

Examples:

ApplicationMembership

This class implements application membership model for balena python SDK.

Function: change_role(membership_id, role_name) ⇒ None

Changes the role of an application member.

Args:

Examples:

Function: create(slug_or_uuid_or_id, username, role_name) ⇒ ApplicationMembershipType

Creates a new membership for an application.

Args:

Returns:

Examples:

Function: get(membership_id, options) ⇒ ApplicationMembershipType

Get a single application membership.

Args:

Returns:

Examples:

Function: get_all(options) ⇒ List[ApplicationMembershipType]

Get all application memberships.

Args:

Returns:

Examples:

Function: get_all_by_application(slug_or_uuid_or_id, options) ⇒ List[ApplicationMembershipType]

Get all memberships by application.

Args:

Returns:

Examples:

Function: remove(membership_id) ⇒ None

Remove a membership.

Args:

ApplicationInvite

This class implements application invite model for balena python SDK.

Function: accept(invite_token) ⇒ None

Accepts an invite.

Args:

Examples:

Function: create(slug_or_uuid_or_id, options) ⇒ ApplicationInviteType

Creates a new invite for an application.

Args:

Returns:

Examples:

Function: get_all(options) ⇒ List[ApplicationInviteType]

Get all invites.

Args:

Returns:

Examples:

Function: get_all_by_application(slug_or_uuid_or_id, options) ⇒ List[ApplicationInviteType]

Get all invites by application.

Args:

Returns:

Examples:

Function: revoke(invite_id) ⇒ None

Revoke an invite.

Args:

Examples:

Device

This class implements device model for balena python SDK.

Function: deactivate(uuid_or_id_or_ids) ⇒ None

Deactivates a device.

Args:

Examples:

Function: disable_device_url(uuid_or_id_or_ids) ⇒ None

Disable device url for a device.

Args:

Examples:

Function: disable_local_mode(uuid_or_id) ⇒ None

Disable local mode.

Args:

Returns:

Examples:

Function: disable_lock_override(uuid_or_id) ⇒ None

Disable lock override.

Args:

Function: enable_device_url(uuid_or_id_or_ids) ⇒ None

Enable device url for a device.

Args:

Examples:

Function: enable_local_mode(uuid_or_id) ⇒ None

Enable local mode.

Args:

Examples:

Function: enable_lock_override(uuid_or_id) ⇒ None

Enable lock override.

Args:

Function: generate_device_key(uuid_or_id, name, description, expiry_date) ⇒ str

Generate a device key.

Args:

Examples:

Function: generate_uuid() ⇒ str

Generate a random device UUID.

Returns:

Examples:

Function: get(uuid_or_id, options) ⇒ TypeDevice

This method returns a single device by id or uuid.

Args:

Returns:

Examples:

Function: get_all(options) ⇒ List[TypeDevice]

This method returns all devices that the current user can access. In order to have the following computed properties in the result you have to explicitly define them in a $select in the extra options:

  • overall_status

  • overall_progress

  • is_frozen

Args:

Returns:

Examples:

Function: get_all_by_application(slug_or_uuid_or_id, options) ⇒ List[TypeDevice]

Get devices by application slug, uuid or id.

Args:

Returns:

Examples:

Function: get_all_by_organization(handle_or_id, options) ⇒ List[TypeDevice]

Get devices by organization slug, uuid or id.

Args:

Returns:

Examples:

Function: get_application_info(uuid_or_id) ⇒ Any

Deprecated Return information about the application running on the device. This function requires supervisor v1.8 or higher.

Args:

Returns:

Examples:

Function: get_application_name(uuid_or_id) ⇒ str

Get application name by device uuid.

Args:

Returns:

Function: get_by_name(name, options) ⇒ List[TypeDevice]

Get devices by device name.

Args:

Returns:

Examples:

Function: get_dashboard_url(uuid) ⇒ None

Get balena Dashboard URL for a specific device.

Args:

Examples:

Function: get_device_url(uuid_or_id) ⇒ str

Get a device url for a device.

Args:

Examples:

Function: get_local_ip_address(uuid_or_id) ⇒ List[str]

Get the local IP addresses of a device.

Args:

Returns:

Function: get_local_mode_support(uuid_or_id) ⇒ LocalModeResponse

Returns whether local mode is supported and a message describing the reason why local mode is not supported.

Args:

Returns:

Examples:

Function: get_mac_address(uuid_or_id) ⇒ List[str]

Get the MAC addresses of a device.

Args:

Returns:

Function: get_metrics(uuid_or_id) ⇒ DeviceMetricsType

Gets the metrics related information for a device.

Args:

Returns:

Function: get_name(uuid_or_id) ⇒ str

Get device name by device uuid.

Args:

Returns:

Function: get_os_update_status(uuid_or_id) ⇒ HUPStatusResponse

Get the OS update status of a device.

Args:

Returns:

Examples:

Function: get_status(uuid_or_id) ⇒ str

Get the status of a device.

Args:

Returns:

Examples:

Function: get_supervisor_state(uuid_or_id) ⇒ SupervisorStateType

Get the supervisor state on a device

Args:

Returns:

Examples:

Function: get_supervisor_target_state(uuid_or_id) ⇒ Any

Get the supervisor target state on a device

Args:

Returns:

Examples:

Function: get_supervisor_target_state_for_app(slug_or_uuid_or_id, release) ⇒ Any

Get the supervisor target state on a device

Args:

Returns:

Examples:

Function: get_with_service_details(uuid_or_id, options) ⇒ TypeDeviceWithServices

This method does not map exactly to the underlying model: it runs a larger prebuilt query, and reformats it into an easy to use and understand format. If you want more control, or to see the raw model directly, use device.get(uuidOrId, options) instead.

Args:

Returns:

Examples:

Function: grant_support_access(uuid_or_id_or_ids, expiry_timestamp) ⇒ None

Grant support access to a device until a specified time.

Args:

Examples:

Function: has(uuid_or_id) ⇒ bool

Check if a device exists.