circle-info
We've migrated to a new docs platform!
Read morearrow-up-right
search
ForumsBlogPricingContactLoginSignup

v21.7.4

hashtag
Installation

Install the balena SDK by running:

$ npm install --save balena-sdk

hashtag
Bundling for browsers

If you're using webpack, browserify, or a similar tool then you probably want to bundle the balena SDK into your application yourself, rather than using the pre-built balena-browser.min.js bundle.

If you intend to do that, be sure to remove the following dependencies that are actually unnecessary in the browser, because they're only used in Node environments. This will significantly reduce the size of your resulting bundle:

  • fs

  • path

  • balena-settings-client

  • node-localstorage

hashtag
Bundling with pkg

The balena SDK includes builds for various ECMAScript versions that are dynamically selected at runtime (using @balena/es-versionarrow-up-right). For this reason, packagers like pkgarrow-up-right are not able to automatically detect which assets to include in the output package. The following sample pkg section should be added to your application's package.json file to instruct pkg to bundle the required assets:

  "pkg": {
    "scripts": [
      "node_modules/balena-sdk/**/*.js"
    ],
    "assets": [
      "node_modules/pinejs-client-core/**/*"
    ]
  }

For more information, please refer to the respective documentation from the pkg projectarrow-up-right.

hashtag
Trying balenaSDK in the browser

BalenaSDK is widely utilized in the balenaCloud dashboardarrow-up-right to perform operations. The SDK has been made available in the browser console by default to test balenaSDK queries on the go. To use it, head to the balenaCloud dashboardarrow-up-right and open the browser developer consolearrow-up-right. There, you will find balenaSDK initialized in the console and ready to run SDK queries.

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

hashtag
Modules

balena-sdk

hashtag
Objects

balena : object

hashtag
Functions

listImagesFromTargetState(targetState) ⇒

hashtag
balena-sdk

hashtag
balena-sdk~getSdk()

The module exports a single factory function.

Kind: inner method of balena-sdk Summary: Creates a new SDK instance using the default or the provided options. Example

hashtag
balena-sdk~setSharedOptions(options)

Set options that are used by calls to fromSharedOptions(). The options accepted are the same as those used in the main SDK factory function. If you use this method, it should be called as soon as possible during app startup and before any calls to fromSharedOptions() are made.

Kind: inner method of balena-sdk Summary: Set shared default options Access: public

Param
Type
Default
Description

options

Object

The shared default options

[options.apiUrl]

String

'https://api.balena-cloud.com/'

the balena API url to use.

[options.builderUrl]

String

'https://builder.balena-cloud.com/'

the balena builder url to use.

[options.deviceUrlsBase]

String

'balena-devices.com'

the base balena device API url to use.

[options.requestLimit]

Number

the number of requests per requestLimitInterval that the SDK should respect.

[options.requestLimitInterval]

Number

60000

the timespan that the requestLimit should apply to in milliseconds, defaults to 60000 (1 minute).

[options.retryRateLimitedRequests]

Boolean | function

false

Determines whether to automatically retry requests that are failing with a 429 Too Many Requests status code and that include a numeric Retry-After response header. - If false, rate-limited requests will not be retried, and the rate limit error will be propagated. - If true, all rate-limited requests will be retried after the duration specified by the Retry-After header. - If a function (retryAfterMs: number) => boolean is provided, it will be called with the retry duration in ms and the request will be retried only when true is returned.

[options.dataDirectory]

String | False

'$HOME/.balena'

ignored in the browser unless false, the directory where the user settings are stored, normally retrieved like require('balena-settings-client').get('dataDirectory'). Providing false creates an isolated in-memory instance.

[options.isBrowser]

Boolean

the flag to tell if the module works in the browser. If not set will be computed based on the presence of the global window value.

[options.debug]

Boolean

when set will print some extra debug information.

Example

hashtag
balena-sdk~fromSharedOptions()

Create an SDK instance using shared default options set using the setSharedOptions() method. If options have not been set using this method, then this method will use the same defaults as the main SDK factory function.

Kind: inner method of balena-sdk Summary: Create an SDK instance using shared default options Access: public Example

hashtag
balena : object

Kind: global namespace

hashtag
balena.interceptors : Array.<Interceptor>

The current array of interceptors to use. Interceptors intercept requests made internally and are executed in the order they appear in this array for requests, and in the reverse order for responses.

Kind: static property of balena Summary: Array of interceptors Access: public Example

hashtag
interceptors.Interceptor : object

An interceptor implements some set of the four interception hook callbacks. To continue processing, each function should return a value or a promise that successfully resolves to a value.

To halt processing, each function should throw an error or return a promise that rejects with an error.

Kind: static typedef of interceptors Properties

Name
Type
Description

[request]

function

Callback invoked before requests are made. Called with the request options, should return (or resolve to) new request options, or throw/reject.

[response]

function

Callback invoked before responses are returned. Called with the response, should return (or resolve to) a new response, or throw/reject.

[requestError]

function

Callback invoked if an error happens before a request. Called with the error itself, caused by a preceeding request interceptor rejecting/throwing an error for the request, or a failing in preflight token validation. Should return (or resolve to) new request options, or throw/reject.

[responseError]

function

Callback invoked if an error happens in the response. Called with the error itself, caused by a preceeding response interceptor rejecting/throwing an error for the request, a network error, or an error response from the server. Should return (or resolve to) a new response, or throw/reject.

hashtag
balena.utils : Object

The utils instance offers some convenient features for clients.

Kind: static property of balena Summary: Balena utils instance Access: public Example

Example

hashtag
balena.request : Object

The balena-request instance used internally. This should not be necessary in normal usage, but can be useful if you want to make an API request directly, using the same token and hooks as the SDK.

Kind: static property of balena Summary: Balena request instance Access: public Example

hashtag
balena.pine : Object

The pinejs-client instance used internally. This should not be necessary in normal usage, but can be useful if you want to directly make pine queries to the api for some resource that isn't directly supported in the SDK.

Kind: static property of balena Summary: Balena pine instance Access: public Example

hashtag
balena.errors : Object

The balena-errors module used internally. This is provided primarily for convenience, and to avoid the necessity for separate balena-errors dependencies. You'll want to use this if you need to match on the specific type of error thrown by the SDK.

Kind: static property of balena Summary: Balena errors module Access: public Example

hashtag
balena.models : object

Kind: static namespace of balena

hashtag
models.application : object

Kind: static namespace of models

application.tags : object

Kind: static namespace of application

tags.getAllByApplication(slugOrUuidOrId, [options]) ⇒ Promise

Kind: static method of tags Summary: Get all application tags for an application Access: public Fulfil: Object[] - application tags

Param
Type
Default
Description

slugOrUuidOrId

String | Number

application slug (string), uuid (string) or id (number)

[options]

Object

{}

extra pine options to use

Example

Example

tags.set(slugOrUuidOrId, tagKey, value) ⇒ Promise

Kind: static method of tags Summary: Set an application tag Access: public

Param
Type
Description

slugOrUuidOrId

String | Number

application slug (string), uuid (string) or id (number)

tagKey

String

tag key

value

String | undefined

tag value

Example

Example

tags.remove(slugOrUuidOrId, tagKey) ⇒ Promise

Kind: static method of tags Summary: Remove an application tag Access: public

Param
Type
Description

slugOrUuidOrId

String | Number

application slug (string), uuid (string) or id (number)

tagKey

String

tag key

Example

application.configVar : object

Kind: static namespace of application

configVar.getAllByApplication(slugOrUuidOrId, [options]) ⇒ Promise

Kind: static method of configVar Summary: Get all config variables for an application Access: public Fulfil: Object[] - application config variables

Param
Type
Default
Description

slugOrUuidOrId

String | Number

application slug (string), uuid (string) or id (number)

[options]

Object

{}

extra pine options to use

Example

Example

configVar.get(slugOrUuidOrId, key) ⇒ Promise

Kind: static method of configVar Summary: Get the value of a specific config variable Access: public Fulfil: String|undefined - the config variable value (or undefined)

Param
Type
Description

slugOrUuidOrId

String | Number

application slug (string), uuid (string) or id (number)

key

String

config variable name

Example

Example

configVar.set(slugOrUuidOrId, key, value) ⇒ Promise

Kind: static method of configVar Summary: Set the value of a specific config variable Access: public

Param
Type
Description

slugOrUuidOrId

String | Number

application slug (string), uuid (string) or id (number)

key

String

config variable name

value

String

config variable value

Example

Example

configVar.remove(slugOrUuidOrId, key) ⇒ Promise

Kind: static method of configVar Summary: Clear the value of a specific config variable Access: public

Param
Type
Description

slugOrUuidOrId

String | Number

application slug (string), uuid (string) or id (number)

key

String

config variable name

Example

Example

application.envVar : object

Kind: static namespace of application

envVar.getAllByApplication(slugOrUuidOrId, [options]) ⇒ Promise

Kind: static method of envVar Summary: Get all environment variables for an application Access: public Fulfil: Object[] - application environment variables

Param
Type
Default
Description

slugOrUuidOrId

String | Number

application slug (string), uuid (string) or id (number)

[options]

Object

{}

extra pine options to use

Example

Example

envVar.get(slugOrUuidOrId, key) ⇒ Promise

Kind: static method of envVar Summary: Get the value of a specific environment variable Access: public Fulfil: String|undefined - the environment variable value (or undefined)

Param
Type
Description

slugOrUuidOrId

String | Number

application slug (string), uuid (string) or id (number)

key

String

environment variable name

Example

Example

envVar.set(slugOrUuidOrId, key, value) ⇒ Promise

Kind: static method of envVar Summary: Set the value of a specific environment variable Access: public

Param
Type
Description

slugOrUuidOrId

String | Number

application slug (string), uuid (string) or id (number)

key

String

environment variable name

value

String

environment variable value

Example

Example

envVar.remove(slugOrUuidOrId, key) ⇒ Promise

Kind: static method of envVar Summary: Clear the value of a specific environment variable Access: public

Param
Type
Description

slugOrUuidOrId

String | Number

application slug (string), uuid (string) or id (number)

key

String

environment variable name

Example

Example

application.buildVar : object

Kind: static namespace of application

buildVar.getAllByApplication(slugOrUuidOrId, [options]) ⇒ Promise

Kind: static method of buildVar Summary: Get all build environment variables for an application Access: public Fulfil: Object[] - application build environment variables

Param
Type
Default
Description

slugOrUuidOrId

String | Number

application slug (string), uuid (string) or id (number)

[options]

Object

{}

extra pine options to use

Example

Example

buildVar.get(slugOrUuidOrId, key) ⇒ Promise

Kind: static method of buildVar Summary: Get the value of a specific build environment variable Access: public Fulfil: String|undefined - the build environment variable value (or undefined)

Param
Type
Description

slugOrUuidOrId

String | Number

application slug (string), uuid (string) or id (number)

key

String

build environment variable name

Example

Example

buildVar.set(slugOrUuidOrId, key, value) ⇒ Promise

Kind: static method of buildVar Summary: Set the value of a specific build environment variable Access: public

Param
Type
Description

slugOrUuidOrId

String | Number

application slug (string), uuid (string) or id (number)

key

String

build environment variable name

value

String

build environment variable value

Example

Example

buildVar.remove(slugOrUuidOrId, key) ⇒ Promise

Kind: static method of buildVar Summary: Clear the value of a specific build environment variable Access: public

Param
Type
Description

slugOrUuidOrId

String | Number

application slug (string), uuid (string) or id (number)

key

String

build environment variable name

Example

Example

application.membership : object

Kind: static namespace of application

membership.get(membershipId, [options]) ⇒ Promise

This method returns a single application membership.

Kind: static method of membership Summary: Get a single application membership Access: public Fulfil: Object - application membership

Param
Type
Default
Description

membershipId

number | Object

the id or an object with the unique user & is_member_of__application numeric pair of the membership

[options]

Object

{}

extra pine options to use

Example

membership.getAllByApplication(slugOrUuidOrId, [options]) ⇒ Promise

This method returns all application memberships for a specific application.

Kind: static method of membership Summary: Get all memberships by application Access: public Fulfil: Object[] - application memberships

Param
Type
Default
Description

slugOrUuidOrId

String | Number

application slug (string), uuid (string) or id (number)

[options]

Object

{}

extra pine options to use

Example

Example

membership.getAllByUser(usernameOrId, [options]) ⇒ Promise

This method returns all application memberships for a specific user.

Kind: static method of membership Summary: Get all memberships by user Access: public Fulfil: Object[] - application memberships

Param
Type
Default
Description

usernameOrId

String | Number

the user's username (string) or id (number)

[options]

Object

{}

extra pine options to use

Example

Example

membership.create(options) ⇒ Promise

This method adds a user to an application by their username if they are a member of the organization.

Kind: static method of membership Summary: Creates a new membership for an application Access: public Fulfil: Object - application membership

Param
Type
Default
Description

options

Object

membership creation parameters

options.application

String | Number

application handle (string), or id (number)

options.username

String

the username of the balena user that will become a member

[options.roleName]

String

"member"

the role name to be granted to the membership

Example

membership.changeRole(idOrUniqueKey, roleName) ⇒ Promise

This method changes the role of an application member.

Kind: static method of membership Summary: Changes the role of an application member Access: public

Param
Type
Description

idOrUniqueKey

Number | Object

the id or an object with the unique user & is_member_of__application numeric pair of the membership that will be changed

roleName

String

the role name to be granted to the membership

Example

Example

membership.remove(idOrUniqueKey) ⇒ Promise

Kind: static method of membership Summary: Remove a membership Access: public

Param
Type
Description

idOrUniqueKey

Number | Object

the id or an object with the unique user & is_member_of__application numeric pair of the membership that will be removed

Example

Example

application.invite : object

Kind: static namespace of application

invite.getAll([options]) ⇒ Promise

This method returns all invites.

Kind: static method of invite Summary: Get all invites Access: public Fulfil: Object[] - invites

Param
Type
Default
Description

[options]

Object

{}

extra pine options to use

Example

invite.getAllByApplication(slugOrUuidOrId, [options]) ⇒ Promise

This method returns all invites for a specific application.

Kind: static method of invite Summary: Get all invites by application Access: public Fulfil: Object[] - invites

Param
Type
Default
Description

slugOrUuidOrId

String | Number

application slug (string), uuid (string) or id (number)

[options]

Object

{}

extra pine options to use

Example

Example

invite.create(slugOrUuidOrId, options, [message]) ⇒ Promise

This method invites a user by their email to an application.

Kind: static method of invite Summary: Creates a new invite for an application Access: public Fulfil: String - application invite

Param
Type
Default
Description

slugOrUuidOrId

String | Number

application slug (string), uuid (string) or id (number)

options

Object

invite creation parameters

options.invitee

String

the email of the invitee

[options.roleName]

String

"developer"

the role name to be granted to the invitee

[message]

String

the message to send along with the invite

Example

invite.revoke(id) ⇒ Promise

Kind: static method of invite Summary: Revoke an invite Access: public

Param
Type
Description

id

Number

application invite id

Example

invite.accept(invitationToken) ⇒ Promise

This method adds the calling user to the application.

Kind: static method of invite Summary: Accepts an invite Access: public

Param
Type
Description

invitationToken

String

invite token

Example

application.getDashboardUrl(id) ⇒ String

Kind: static method of application Summary: Get Dashboard URL for a specific application Returns: String - - Dashboard URL for the specific application Throws:

  • Exception if the id is not a finite number

Param
Type
Description

id

Number

Application id

Example

application.getAll([options], [context]) ⇒ Promise

Kind: static method of application Summary: Get all applications Access: public Fulfil: Object[] - applications

Param
Type
Default
Description

[options]

Object

{}

extra pine options to use

[context]

String

extra access filters, undefined or 'directly_accessible'

Example

application.getAllDirectlyAccessible([options]) ⇒ Promise

Kind: static method of application Summary: Get all applications directly accessible by the user Access: public Fulfil: Object[] - applications

Param
Type
Default
Description

[options]

Object

{}

extra pine options to use

Example

application.getAllByOrganization(orgHandleOrId, [options]) ⇒ Promise

Kind: static method of application Summary: Get all applications of an organization Access: public Fulfil: Object[] - applications

Param
Type
Default
Description

orgHandleOrId

Number | String

organization handle (string) or id (number)

[options]

Object

{}

extra pine options to use

Example

application.get(slugOrUuidOrId, [options], [context]) ⇒ Promise

Kind: static method of application Summary: Get a single application Access: public Fulfil: Object - application

Param
Type
Default
Description

slugOrUuidOrId

String | Number

application slug (string), uuid (string) or id (number)

[options]

Object

{}

extra pine options to use

[context]

String

extra access filters, undefined or 'directly_accessible'

Example

Example

Example

application.getDirectlyAccessible(slugOrUuidOrId, [options]) ⇒ Promise

Kind: static method of application Summary: Get a single application directly accessible by the user Access: public Fulfil: Object - application

Param
Type
Default
Description

slugOrUuidOrId

String | Number

application slug (string), uuid (string) or id (number)

[options]

Object

{}

extra pine options to use

Example

Example

application.getWithDeviceServiceDetails(slugOrUuidOrId, [options]) ⇒ Promise

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.

Kind: static method of application Summary: Get a single application and its devices, along with each device's associated services' essential details Access: public Fulfil: Object - application

Param
Type
Default
Description

slugOrUuidOrId

String | Number

application slug (string), uuid (string) or id (number)

[options]

Object

{}

extra pine options to use

Example

Example

application.getAppByName(appName, [options], [context]) ⇒ Promise

Kind: static method of application Summary: Get a single application using the appname and the handle of the owning organization Access: public Fulfil: Object - application

Param
Type
Default
Description

appName

String

application name

[options]

Object

{}

extra pine options to use

[context]

String

extra access filters, undefined or 'directly_accessible'

Example

application.has(slugOrUuidOrId) ⇒ Promise

Kind: static method of application Summary: Check if an application exists Access: public Fulfil: Boolean - has application

Param
Type
Description

slugOrUuidOrId

String | Number

application slug (string), uuid (string) or id (number)

Example

Example

application.hasAny() ⇒ Promise

Kind: static method of application Summary: Check if the user has access to any applications Access: public Fulfil: Boolean - has any applications Example

application.create(options) ⇒ Promise

Kind: static method of application Summary: Create an application Access: public Fulfil: Object - application

Param
Type
Description

options

Object

application creation parameters

options.name

String

application name

[options.uuid]

String

application uuid

[options.applicationClass]

String

application class: 'app'

options.deviceType

String

device type slug

options.organization

String | Number

handle (string) or id (number) of the organization that the application will belong to or null

Example

Example

Example

application.remove(slugOrUuidOrIdOrIds) ⇒ Promise

Kind: static method of application Summary: Remove application Access: public

Param
Type
Description

slugOrUuidOrIdOrIds

String | Number | Array.<Number>

application slug (string), uuid (string) or id (number) or array of ids

Example

Example

application.rename(slugOrUuidOrId, newName) ⇒ Promise

Kind: static method of application Summary: Rename application Access: public

Param
Type
Description

slugOrUuidOrId

String | Number

application slug (string), uuid (string) or id (number)

newName

String

new application name (string)

Example

Example

application.restart(slugOrUuidOrId) ⇒ Promise

Kind: static method of application Summary: Restart application Access: public

Param
Type
Description

slugOrUuidOrId

String | Number

application slug (string), uuid (string) or id (number)

Example

Example

application.generateProvisioningKey(generateProvisioningKeyParams) ⇒ Promise

Kind: static method of application Summary: Generate a device provisioning key for a specific application Access: public Fulfil: String - device provisioning key

Param
Type
Description

generateProvisioningKeyParams

Object

an object containing the parameters for the provisioning key generation

generateProvisioningKeyParams.slugOrUuidOrId

String | Number

application slug (string), uuid (string) or id (number)

generateProvisioningKeyParams.keyExpiryDate

String

Expiry Date for provisioning key

[generateProvisioningKeyParams.keyName]

String

Provisioning key name

[generateProvisioningKeyParams.keyDescription]

String

Description for provisioning key

Example

Example

Example

application.purge(appId) ⇒ Promise

Kind: static method of application Summary: Purge devices by application id Access: public

Param
Type
Description

appId

Number

application id

Example

application.shutdown(appId, [options]) ⇒ Promise

Kind: static method of application Summary: Shutdown devices by application id Access: public

Param
Type
Default
Description

appId

Number

application id

[options]

Object

options

[options.force]

Boolean

false

override update lock

Example

application.reboot(appId, [options]) ⇒ Promise

Kind: static method of application Summary: Reboot devices by application id Access: public

Param
Type
Default
Description

appId

Number

application id

[options]

Object

options

[options.force]

Boolean

false

override update lock

Example

application.willTrackNewReleases(slugOrUuidOrId) ⇒ Promise

Kind: static method of application Summary: Get whether the application is configured to receive updates whenever a new release is available Access: public Fulfil: Boolean - is tracking the latest release

Param
Type
Description

slugOrUuidOrId

String | Number

application slug (string), uuid (string) or id (number)

Example

Example

application.isTrackingLatestRelease(slugOrUuidOrId) ⇒ Promise

Kind: static method of application Summary: Get whether the application is up to date and is tracking the latest finalized release for updates Access: public Fulfil: Boolean - is tracking the latest release

Param
Type
Description

slugOrUuidOrId

String | Number

application slug (string), uuid (string) or id (number)

Example

Example

application.pinToRelease(slugOrUuidOrId, fullReleaseHash) ⇒ Promise

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

Kind: static method of application Summary: Set a specific application to run a particular release Access: public

Param
Type
Description

slugOrUuidOrId

String | Number

application slug (string), uuid (string) or id (number)

fullReleaseHash

String

the hash of a successful release (string)

Example

Example

application.getTargetReleaseHash(slugOrUuidOrId) ⇒ Promise

Kind: static method of application Summary: Get the hash of the current release for a specific application Access: public Fulfil: String|undefined - The release hash of the current release

Param
Type
Description

slugOrUuidOrId

String | Number

application slug (string), uuid (string) or id (number)

Example

Example

Example

application.trackLatestRelease(slugOrUuidOrId) ⇒ Promise

The application's current release will be updated with each new successfully built release.

Kind: static method of application Summary: Configure a specific application to track the latest finalized available release Access: public

Param
Type
Description

slugOrUuidOrId

String | Number

application slug (string), uuid (string) or id (number)

Example

Example

application.enableDeviceUrls(slugOrUuidOrId) ⇒ Promise

Kind: static method of application Summary: Enable device urls for all devices that belong to an application Access: public

Param
Type
Description

slugOrUuidOrId

String | Number

application slug (string), uuid (string) or id (number)

Example

Example

application.disableDeviceUrls(slugOrUuidOrId) ⇒ Promise

Kind: static method of application Summary: Disable device urls for all devices that belong to an application Access: public

Param
Type
Description

slugOrUuidOrId

String | Number

application slug (string), uuid (string) or id (number)

Example

Example

application.grantSupportAccess(slugOrUuidOrId, expiryTimestamp) ⇒ Promise

Kind: static method of application Summary: Grant support access to an application until a specified time Access: public

Param
Type
Description

slugOrUuidOrId

String | Number

application slug (string), uuid (string) or id (number)

expiryTimestamp

Number

a timestamp in ms for when the support access will expire

Example

Example

application.revokeSupportAccess(slugOrUuidOrId) ⇒ Promise

Kind: static method of application Summary: Revoke support access to an application Access: public

Param
Type
Description

slugOrUuidOrId

String | Number

application slug (string), uuid (string) or id (number)

Example

Example

hashtag
models.device : object

Kind: static namespace of models

device.tags : object

Kind: static namespace of device

tags.getAllByApplication(slugOrUuidOrId, [options]) ⇒ Promise

Kind: static method of tags Summary: Get all device tags for an application Access: public Fulfil: Object[] - device tags

Param
Type
Default
Description

slugOrUuidOrId

String | Number

application slug (string), uuid (string) or id (number)

[options]

Object

{}

extra pine options to use

Example

Example

tags.getAllByDevice(uuidOrId, [options]) ⇒ Promise

Kind: static method of tags Summary: Get all device tags for a device Access: public Fulfil: Object[] - device tags

Param
Type
Default
Description

uuidOrId

String | Number

device uuid (string) or id (number)

[options]

Object

{}

extra pine options to use

Example

Example

tags.set(uuidOrId, tagKey, value) ⇒ Promise

Kind: static method of tags Summary: Set a device tag Access: public

Param
Type
Description

uuidOrId

String | Number

device uuid (string) or id (number)

tagKey

String

tag key

value

String | undefined

tag value

Example

Example

tags.remove(uuidOrId, tagKey) ⇒ Promise

Kind: static method of tags Summary: Remove a device tag Access: public

Param
Type
Description

uuidOrId

String | Number

device uuid (string) or id (number)

tagKey

String

tag key

Example

device.configVar : object

Kind: static namespace of device

configVar.getAllByDevice(uuidOrId, [options]) ⇒ Promise

Kind: static method of configVar Summary: Get all config variables for a device Access: public Fulfil: Object[] - device config variables

Param
Type
Default
Description

uuidOrId

String | Number

device uuid (string) or id (number)

[options]

Object

{}

extra pine options to use

Example

Example

configVar.getAllByApplication(slugOrUuidOrId, [options]) ⇒ Promise

Kind: static method of configVar Summary: Get all device config variables by application Access: public Fulfil: Object[] - device config variables

Param
Type
Default
Description

slugOrUuidOrId

String | Number

application slug (string), uuid (string) or id (number)

[options]

Object

{}

extra pine options to use

Example

Example

configVar.get(uuidOrId, key) ⇒ Promise

Kind: static method of configVar Summary: Get the value of a specific config variable Access: public Fulfil: String|undefined - the config variable value (or undefined)

Param
Type
Description

uuidOrId

String | Number

device uuid (string) or id (number)

key

String

config variable name

Example

Example

configVar.set(uuidOrId, key, value) ⇒ Promise

Kind: static method of configVar Summary: Set the value of a specific config variable Access: public

Param
Type
Description

uuidOrId

String | Number

device uuid (string) or id (number)

key

String

config variable name

value

String

config variable value

Example

Example

configVar.remove(uuidOrId, key) ⇒ Promise

Kind: static method of configVar Summary: Clear the value of a specific config variable Access: public

Param
Type
Description

uuidOrId

String | Number

device uuid (string) or id (number)

key

String

config variable name

Example

Example

device.envVar : object

Kind: static namespace of device

envVar.getAllByDevice(uuidOrId, [options]) ⇒ Promise

Kind: static method of envVar Summary: Get all environment variables for a device Access: public Fulfil: Object[] - device environment variables

Param
Type
Default
Description

uuidOrId

String | Number

device uuid (string) or id (number)

[options]

Object

{}

extra pine options to use

Example

Example

envVar.getAllByApplication(slugOrUuidOrId, [options]) ⇒ Promise

Kind: static method of envVar Summary: Get all device environment variables by application Access: public Fulfil: Object[] - device environment variables

Param
Type
Default
Description

slugOrUuidOrId

String | Number

application slug (string), uuid (string) or id (number)

[options]

Object

{}

extra pine options to use

Example

Example

envVar.get(uuidOrId, key) ⇒ Promise

Kind: static method of envVar Summary: Get the value of a specific environment variable Access: public Fulfil: String|undefined - the environment variable value (or undefined)

Param
Type
Description

uuidOrId

String | Number

device uuid (string) or id (number)

key

String

environment variable name

Example

Example

envVar.set(uuidOrId, key, value) ⇒ Promise

Kind: static method of envVar Summary: Set the value of a specific environment variable Access: public

Param
Type
Description

uuidOrId

String | Number

device uuid (string) or id (number)

key

String

environment variable name

value

String

environment variable value

Example

Example

envVar.remove(uuidOrId, key) ⇒ Promise

Kind: static method of envVar Summary: Clear the value of a specific environment variable Access: public

Param
Type
Description

uuidOrId

String | Number

device uuid (string) or id (number)

key

String

environment variable name

Example

Example

device.serviceVar : object

Kind: static namespace of device

serviceVar.getAllByDevice(uuidOrId, [options]) ⇒ Promise

Kind: static method of serviceVar Summary: Get all service variable overrides for a device Access: public Fulfil: Object[] - service variables

Param
Type
Default
Description

uuidOrId

String | Number

device uuid (string) or id (number)

[options]

Object

{}

extra pine options to use

Example

Example

serviceVar.getAllByApplication(slugOrUuidOrId, [options]) ⇒ Promise

Kind: static method of serviceVar Summary: Get all device service variable overrides by application Access: public Fulfil: Object[] - service variables

Param
Type
Default
Description

slugOrUuidOrId

String | Number

application slug (string), uuid (string) or id (number)

[options]

Object

{}

extra pine options to use

Example

Example

serviceVar.get(uuidOrId, serviceNameOrId, key) ⇒ Promise

Kind: static method of serviceVar Summary: Get the overriden value of a service variable on a device Access: public Fulfil: String|undefined - the variable value (or undefined)

Param
Type
Description

uuidOrId

String | Number

device uuid (string) or id (number)

serviceNameOrId

String | Number

service name (string) or id (number)

key

String

variable name

Example

Example

Example

serviceVar.set(uuidOrId, serviceNameOrId, key, value) ⇒ Promise

Kind: static method of serviceVar Summary: Set the overriden value of a service variable on a device Access: public

Param
Type
Description

uuidOrId

String | Number

device uuid (string) or id (number)

serviceNameOrId

String | Number

service name (string) or id (number)

key

String

variable name

value

String

variable value

Example

Example

Example

serviceVar.remove(uuidOrId, serviceNameOrId, key) ⇒ Promise

Kind: static method of serviceVar Summary: Clear the overridden value of a service variable on a device Access: public

Param
Type
Description

uuidOrId

String | Number

device uuid (string) or id (number)

serviceNameOrId

String | Number

service name (string) or id (number)

key

String

variable name

Example

Example

Example

device.history : object

Kind: static namespace of device

history.getAllByDevice(uuidOrId, [options]) ⇒ Promise

Kind: static method of history Summary: Get all history entries for a device Access: public Fulfil: Object[] - device history

Param
Type
Default
Description

uuidOrId

String | Number

device uuid (32 / 62 digits string) or id (number)

[options]

Object

options

[options.fromDate]

Date

subDays(new Date(), 7)

history entries older or equal to this date - default now() - 7 days

[options.toDate]

Date

history entries younger or equal to this date

Example

Example

Example

history.getAllByApplication(slugOrUuidOrId, [options]) ⇒ Promise

Kind: static method of history Summary: Get all device history entries by application with time frame Access: public Fulfil: Object[] - device history

Param
Type
Default
Description

slugOrUuidOrId

String | Number

application slug (string), uuid (string) or id (number)

[options]

Object

options

[options.fromDate]

Date

subDays(new Date(), 7)

history entries older or equal to this date - default now() - 7 days

[options.toDate]

Date

history entries younger or equal to this date

Example

Example

Example

device.getDashboardUrl(uuid) ⇒ String

Kind: static method of device Summary: Get Dashboard URL for a specific device Returns: String - - Dashboard URL for the specific device Throws:

  • Exception if the uuid is empty

Param
Type
Description

uuid

String

Device uuid

Example

device.getAllByApplication(slugOrUuidOrId, [options]) ⇒ Promise

This method returns all devices of a specific application. 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

  • should_be_running__release

Kind: static method of device Summary: Get all devices by application Access: public Fulfil: Object[] - devices

Param
Type
Default
Description

slugOrUuidOrId

String | Number

application slug (string), uuid (string) or id (number)

[options]

Object

{}

extra pine options to use

Example

Example

Example

device.getAllByOrganization(handleOrId, [options]) ⇒ Promise

This method returns all devices of a specific application. 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

  • should_be_running__release

Kind: static method of device Summary: Get all devices by organization Access: public Fulfil: Object[] - devices

Param
Type
Default
Description

handleOrId

String | Number

organization handle (string) or id (number).

[options]

Object

{}

extra pine options to use

Example

Example

Example

device.get(uuidOrId, [options]) ⇒ Promise

This method returns a single device by id or uuid. 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

  • should_be_running__release

Kind: static method of device Summary: Get a single device Access: public Fulfil: Object - device

Param
Type
Default
Description

uuidOrId

String | Number

device uuid (string) or id (number)

[options]

Object

{}

extra pine options to use

Example

Example

Example

device.getWithServiceDetails(uuidOrId, [options]) ⇒ Promise

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.

Kind: static method of device Summary: Get a single device along with its associated services' details, including their associated commit Access: public Fulfil: Object - device with service details

Param
Type
Default
Description

uuidOrId

String | Number

device uuid (string) or id (number)

[options]

Object

{}

extra pine options to use

Example

Example

device.getByName(name) ⇒ Promise

Kind: static method of device Summary: Get devices by name Access: public Fulfil: Object[] - devices

Param
Type
Description

name

String

device name

Example

device.getName(uuidOrId) ⇒ Promise

Kind: static method of device Summary: Get the name of a device Access: public Fulfil: String - device name

Param
Type
Description

uuidOrId

String | Number

device uuid (string) or id (number)

Example

Example

device.getApplicationName(uuidOrId) ⇒ Promise

Kind: static method of device Summary: Get application name Access: public Fulfil: String - application name

Param
Type
Description

uuidOrId

String | Number

device uuid (string) or id (number)

Example

Example

device.has(uuidOrId) ⇒ Promise

Kind: static method of device Summary: Check if a device exists Access: public Fulfil: Boolean - has device

Param
Type
Description

uuidOrId

String | Number

device uuid (string) or id (number)

Example

Example

device.isOnline(uuidOrId) ⇒ Promise

Kind: static method of device Summary: Check if a device is online Access: public Fulfil: Boolean - is device online

Param
Type
Description

uuidOrId

String | Number

device uuid (string) or id (number)

Example

Example

device.getLocalIPAddresses(uuidOrId) ⇒ Promise

Kind: static method of device Summary: Get the local IP addresses of a device Access: public Fulfil: String[] - local ip addresses Reject: Error Will reject if the device is offline

Param
Type
Description

uuidOrId

String | Number

device uuid (string) or id (number)

Example

Example

device.getMACAddresses(uuidOrId) ⇒ Promise

Kind: static method of device Summary: Get the MAC addresses of a device Access: public Fulfil: String[] - mac addresses

Param
Type
Description

uuidOrId

String | Number

device uuid (string) or id (number)

Example

Example

device.getMetrics(uuidOrId) ⇒ Promise

Kind: static method of device Summary: Get the metrics related information for a device Access: public Fulfil: Object - device metrics

Param
Type
Description

uuidOrId

String | Number

device uuid (string) or id (number)

Example

Example

device.remove(uuidOrIdOrArray) ⇒ Promise

Kind: static method of device Summary: Remove device Access: public

Param
Type
Description

uuidOrIdOrArray

String | Array.<String> | Number | Array.<Number>

device uuid (string) or id (number) or array of full uuids or ids

Example

Example

device.deactivate(uuidOrIdOrArray) ⇒ Promise

Kind: static method of device Summary: Deactivate device Access: public

Param
Type
Description

uuidOrIdOrArray

String | Array.<String> | Number | Array.<Number>

device uuid (string) or id (number) or array of full uuids or ids

Example

Example

device.rename(uuidOrId, newName) ⇒ Promise

Kind: static method of device Summary: Rename device Access: public

Param
Type
Description

uuidOrId

String | Number

device uuid (string) or id (number)

newName

String

the device new name

Example

Example

device.setNote(uuidOrIdOrArray, note) ⇒ Promise

Kind: static method of device Summary: Note a device Access: public

Param
Type
Description

uuidOrIdOrArray

String | Array.<String> | Number | Array.<Number>

device uuid (string) or id (number) or array of full uuids or ids

note

String

the note

Example

Example

device.setCustomLocation(uuidOrIdOrArray, location) ⇒ Promise

Kind: static method of device Summary: Set a custom location for a device Access: public

Param
Type
Description

uuidOrIdOrArray

String | Array.<String> | Number | Array.<Number>

device uuid (string) or id (number) or array of full uuids or ids

location

Object

the location ({ latitude: 123, longitude: 456 })

Example

Example

device.unsetCustomLocation(uuidOrIdOrArray) ⇒ Promise

Kind: static method of device Summary: Clear the custom location of a device Access: public

Param
Type
Description

uuidOrIdOrArray

String | Array.<String> | Number | Array.<Number>

device uuid (string) or id (number) or array of full uuids or ids

Example

Example

device.move(uuidOrIdOrArray, applicationSlugOrUuidOrId) ⇒ Promise

Kind: static method of device Summary: Move a device to another application Access: public

Param
Type
Description

uuidOrIdOrArray

String | Array.<String> | Number | Array.<Number>

device uuid (string) or id (number) or array of full uuids or ids

applicationSlugOrUuidOrId

String | Number

application slug (string), uuid (string) or id (number)

Example

Example

Example

device.getSupervisorTargetState(uuidOrId, version) ⇒ Promise

Kind: static method of device Summary: Get the target supervisor state on a device Access: public

Param
Type
Description

uuidOrId

String | Number

device uuid (string) or id (number)

version

Number

(optional) target state version (2 or 3), default to 2

Example

Example

Example

device.getSupervisorTargetStateForApp(uuidOrId, release) ⇒ Promise

Kind: static method of device Summary: Get the target supervisor state on a "generic" device on a fleet Access: public

Param
Type
Description

uuidOrId

String | Number

fleet uuid (string) or id (number)

release

String

(optional) release uuid (default tracked)

Example

Example

Example

device.generateUniqueKey() ⇒ String

Kind: static method of device Summary: Generate a random key, useful for both uuid and api key. Returns: String - A generated key Access: public Example

device.register(applicationSlugOrUuidOrId, uuid, [deviceTypeSlug]) ⇒ Promise

Kind: static method of device Summary: Register a new device with a Balena application. Access: public Fulfil: Object Device registration info ({ id: "...", uuid: "...", api_key: "..." })

Param
Type
Description

applicationSlugOrUuidOrId

String | Number

application slug (string), uuid (string) or id (number)

uuid

String

device uuid

[deviceTypeSlug]

String

device type slug (string) or alias (string)

Example

Example

Example

device.generateDeviceKey(uuidOrId, [keyName], [keyDescription]) ⇒ Promise

Kind: static method of device Summary: Generate a device key Access: public

Param
Type
Description

uuidOrId

String | Number

device uuid (string) or id (number)

[keyName]

String

Device key name

[keyDescription]

String

Description for device key

Example

Example

device.hasDeviceUrl(uuidOrId) ⇒ Promise

Kind: static method of device Summary: Check if a device is web accessible with device utls Access: public Fulfil: Boolean - has device url

Param
Type
Description

uuidOrId

String | Number

device uuid (string) or id (number)

Example

Example

device.getDeviceUrl(uuidOrId) ⇒ Promise

Kind: static method of device Summary: Get a device url Access: public Fulfil: String - device url

Param
Type
Description

uuidOrId

String | Number

device uuid (string) or id (number)

Example

Example

device.enableDeviceUrl(uuidOrIdOrArray) ⇒ Promise

Kind: static method of device Summary: Enable device url for a device Access: public

Param
Type
Description

uuidOrIdOrArray

String | Array.<String> | Number | Array.<Number>

device uuid (string) or id (number) or array of full uuids or ids

Example

Example

device.disableDeviceUrl(uuidOrIdOrArray) ⇒ Promise

Kind: static method of device Summary: Disable device url for a device Access: public

Param
Type
Description

uuidOrIdOrArray

String | Array.<String> | Number | Array.<Number>

device uuid (string) or id (number) or array of full uuids or ids

Example

Example

device.enableLocalMode(uuidOrId) ⇒ Promise

Kind: static method of device Summary: Enable local mode Access: public

Param
Type
Description

uuidOrId

String | Number

device uuid (string) or id (number)

Example

Example

device.disableLocalMode(uuidOrId) ⇒ Promise

Kind: static method of device Summary: Disable local mode Access: public

Param
Type
Description

uuidOrId

String | Number

device uuid (string) or id (number)

Example

Example

device.isInLocalMode(uuidOrId) ⇒ Promise

Kind: static method of device Summary: Check if local mode is enabled on the device Access: public Fulfil: Boolean - has device url

Param
Type
Description

uuidOrId

String | Number

device uuid (string) or id (number)

Example

Example

device.getLocalModeSupport(device) ⇒ Object

Kind: static method of device Summary: Returns whether local mode is supported along with a message describing the reason why local mode is not supported. Returns: Object - Local mode support info ({ supported: true/false, message: "..." }) Access: public

Param
Type
Description

device

Object

A device object

Example

device.enableLockOverride(uuidOrId) ⇒ Promise

Kind: static method of device Summary: Enable lock override Access: public

Param
Type
Description

uuidOrId

String | Number

device uuid (string) or id (number)

Example

Example

device.disableLockOverride(uuidOrId) ⇒ Promise

Kind: static method of device Summary: Disable lock override Access: public

Param
Type
Description

uuidOrId

String | Number

device uuid (string) or id (number)

Example

Example

device.hasLockOverride(uuidOrId) ⇒ Promise

Kind: static method of device Summary: Check if a device has the lock override enabled Access: public

Param
Type
Description

uuidOrId

String | Number

device uuid (string) or id (number)

Example

Example

device.getStatus(uuidOrId) ⇒ Promise

Convenience method for getting the overall status of a device. It's recommended to use balena.models.device.get() instead, in case that you need to retrieve more device fields than just the status.

Kind: static method of device Summary: Get the status of a device Access: public Fulfil: String - device status See: get for an example on selecting the overall_status field.

Param
Type
Description

uuidOrId

String | Number

device uuid (string) or id (number)

Example

Example

device.getProgress(uuidOrId) ⇒ Promise

Convenience method for getting the overall progress of a device. It's recommended to use balena.models.device.get() instead, in case that you need to retrieve more device fields than just the progress.

Kind: static method of device Summary: Get the progress of a device Access: public Fulfil: Number|Null - device progress See: get for an example on selecting the overall_progress field.

Param
Type
Description

uuidOrId

String | Number

device uuid (string) or id (number)

Example

Example

device.grantSupportAccess(uuidOrIdOrArray, expiryTimestamp) ⇒ Promise

Kind: static method of device Summary: Grant support access to a device until a specified time Access: public

Param
Type
Description

uuidOrIdOrArray

String | Array.<String> | Number | Array.<Number>

device uuid (string) or id (number) or array of full uuids or ids

expiryTimestamp

Number

a timestamp in ms for when the support access will expire

Example

Example

device.revokeSupportAccess(uuidOrIdOrArray) ⇒ Promise

Kind: static method of device Summary: Revoke support access to a device Access: public

Param
Type
Description

uuidOrIdOrArray

String | Array.<String> | Number | Array.<Number>

device uuid (string) or id (number) or array of full uuids or ids

Example

Example

device.lastOnline(device) ⇒ String

If the device has never been online this method returns the string Connecting....

Kind: static method of device Summary: Get a string showing when a device was last set as online Access: public

Param
Type
Description

device

Object

A device object

Example

device.getOsVersion(device) ⇒ String

Kind: static method of device Summary: Get the OS version (version number and variant combined) running on a device Access: public

Param
Type
Description

device

Object

A device object

Example

device.isTrackingApplicationRelease(uuidOrId) ⇒ Promise

Kind: static method of device Summary: Get whether the device is configured to track the current application release Access: public Fulfil: Boolean - is tracking the current application release

Param
Type
Description

uuidOrId

String | Number

device uuid (string) or id (number)

Example

device.getTargetReleaseHash(uuidOrId) ⇒ Promise

Kind: static method of device Summary: Get the hash of the currently tracked release for a specific device Access: public Fulfil: String - The release hash of the currently tracked release

Param
Type
Description

uuidOrId

String | Number

device uuid (string) or id (number)

Example

Example

device.pinToRelease(uuidOrIdOrArray, fullReleaseHashOrId) ⇒ Promise

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

Kind: static method of device Summary: Set a specific device to run a particular release Access: public

Param
Type
Description

uuidOrIdOrArray

String | Array.<String> | Number | Array.<Number>

device uuid (string) or id (number) or array of full uuids or ids

fullReleaseHashOrId

String | Number

the hash of a successful release (string) or id (number)

Example

Example

device.trackApplicationRelease(uuidOrIdOrArray) ⇒ Promise

The device's current release will be updated with each new successfully built release.

Kind: static method of device Summary: Configure a specific device to track the current application release Access: public

Param
Type
Description

uuidOrIdOrArray

String | Array.<String> | Number | Array.<Number>

device uuid (string) or id (number) or array of full uuids or ids

Example

device.setSupervisorRelease(uuidOrIdOrArray, supervisorVersionOrId) ⇒ Promise

Configures the device to run a particular supervisor release.

Kind: static method of device Summary: Set a specific device to run a particular supervisor release Access: public

Param
Type
Description

uuidOrIdOrArray

String | Array.<String> | Number | Array.<Number>

device uuid (string) or id (number) or array of full uuids or ids

supervisorVersionOrId

String | Number

the raw version of a supervisor release (string) or id (number)

Example

Example

device.startOsUpdate(uuidOrUuids, targetOsVersion, [options]) ⇒ Promise

Kind: static method of device Summary: Start an OS update on a device Access: public Fulfil: Object - action response

Param
Type
Description

uuidOrUuids

String | Array.<String>

full device uuid or array of full uuids

targetOsVersion

String

semver-compatible version for the target device Unsupported (unpublished) version will result in rejection. The version must be the exact version number, a "prod" variant and greater than the one running on the device. To resolve the semver-compatible range use balena.model.os.getMaxSatisfyingVersion.

[options]

Object

options

[options.runDetached]

Boolean

run the update in detached mode. True by default

Example

device.ping(uuidOrId) ⇒ Promise

This is useful to signal that the supervisor is alive and responding.

Kind: static method of device Summary: Ping a device Access: public

Param
Type
Description

uuidOrId

String | Number

device uuid (string) or id (number)

Example

Example

device.identify(uuidOrId) ⇒ Promise

Kind: static method of device Summary: Identify device Access: public

Param
Type
Description

uuidOrId

String | Number

device uuid (string) or id (number)

Example

Example

device.restartApplication(uuidOrId) ⇒ Promise

This function restarts the Docker container running the application on the device, but doesn't reboot the device itself.

Kind: static method of device Summary: Restart application on device Access: public

Param
Type
Description

uuidOrId

String | Number

device uuid (string) or id (number)

Example

Example

device.reboot(uuidOrId, [options]) ⇒ Promise

Kind: static method of device Summary: Reboot device Access: public

Param
Type
Default
Description

uuidOrId

String | Number

device uuid (string) or id (number)

[options]

Object

options

[options.force]

Boolean

false

override update lock

Example

Example

device.shutdown(uuidOrId, [options]) ⇒ Promise

Kind: static method of device Summary: Shutdown device Access: public

Param
Type
Default
Description

uuidOrId

String | Number

device uuid (string) or id (number)

[options]

Object

options

[options.force]

Boolean

false

override update lock

Example

Example

device.purge(uuidOrId) ⇒ Promise

This function clears the user application's /data directory.

Kind: static method of device Summary: Purge device Access: public

Param
Type
Description

uuidOrId

String | Number

device uuid (string) or id (number)

Example

Example

device.update(uuidOrId, [options]) ⇒ Promise

Kind: static method of device Summary: Trigger an update check on the supervisor Access: public

Param
Type
Default
Description

uuidOrId

String | Number

device uuid (string) or id (number)

[options]

Object

options

[options.force]

Boolean

false

override update lock

Example

Example

device.getSupervisorState(uuidOrId) ⇒ Promise

Kind: static method of device Summary: Get the supervisor state on a device Access: public

Param
Type
Description

uuidOrId

String | Number

device uuid (string) or id (number)

Example

Example

device.startService(uuidOrId, imageId) ⇒ Promise

Kind: static method of device Summary: Start a service on a device Access: public

Param
Type
Description

uuidOrId

String | Number

device uuid (string) or id (number)

imageId

Number

id of the image to start

Example

Example

device.stopService(uuidOrId, imageId) ⇒ Promise

Kind: static method of device Summary: Stop a service on a device Access: public

Param
Type
Description

uuidOrId

String | Number

device uuid (string) or id (number)

imageId

Number

id of the image to stop

Example

Example

device.restartService(uuidOrId, imageId) ⇒ Promise

Kind: static method of device Summary: Restart a service on a device Access: public

Param
Type
Description

uuidOrId

String | Number

device uuid (string) or id (number)

imageId

Number

id of the image to restart

Example

Example

hashtag
models.deviceType : object

Kind: static namespace of models

deviceType.get(idOrSlug, [options]) ⇒ Promise

This method returns a single device type.

Kind: static method of deviceType Summary: Get a single deviceType Access: public Fulfil: Object[] - device types

Param
Type
Default
Description

idOrSlug

String | Number

device type slug (string) or alias (string) or id

[options]

Object

{}

extra pine options to use

Example

Example

deviceType.getAll([options]) ⇒ Promise

This method returns all device types.

Kind: static method of deviceType Summary: Get all deviceTypes Access: public Fulfil: Object[] - device types

Param
Type
Default
Description

[options]

Object

{}

extra pine options to use

Example

Example

deviceType.getAllSupported([options]) ⇒ Promise

This method returns all supported device types.

Kind: static method of deviceType Summary: Get all supported deviceTypes Access: public Fulfil: Object[] - device types

Param
Type
Default
Description

[options]

Object

{}

extra pine options to use

Example

Example

deviceType.getBySlugOrName(slugOrName) ⇒ Promise

Kind: static method of deviceType Summary: Get a deviceType by slug or name Access: public Fulfil: Object - device type

Param
Type
Description

slugOrName

String

deviceType slug

Example

deviceType.getName(deviceTypeSlug) ⇒ Promise

Kind: static method of deviceType Summary: Get display name for a device Access: public Fulfil: String - device display name

Param
Type
Description

deviceTypeSlug

String

device type slug

Example

deviceType.getSlugByName(deviceTypeName) ⇒ Promise

Kind: static method of deviceType Summary: Get device slug Access: public Fulfil: String - device slug name

Param
Type
Description

deviceTypeName

String

device type name

Example

deviceType.getInterpolatedPartials(deviceTypeSlug) ⇒ Promise

Kind: static method of deviceType Summary: Get a contract with resolved partial templates Access: public Fulfil: Contract - device type contract with resolved partials

Param
Type
Description

deviceTypeSlug

String

device type slug

Example

deviceType.getInstructions(deviceTypeSlugOrContract) ⇒ Promise

Kind: static method of deviceType Summary: Get instructions for installing a host OS on a given device type Access: public Fulfil: Object | String[] - step by step instructions for installing the host OS to the device

Param
Type
Description

deviceTypeSlugOrContract

String | Object

device type slug or contract

Example

deviceType.getInstallMethod(deviceTypeSlug) ⇒ Promise

Kind: static method of deviceType Summary: Get installation method on a given device type Access: public Fulfil: String - the installation method supported for the given device type slug

Param
Type
Description

deviceTypeSlug

String

device type slug

Example

hashtag
models.apiKey : object

Kind: static namespace of models

apiKey.create(createApiKeyParams) ⇒ Promise

This method registers a new api key for the current user with the name given.

Kind: static method of apiKey Summary: Creates a new user API key Access: public Fulfil: String - API key

Param
Type
Default
Description

createApiKeyParams

Object

an object containing the parameters for the creation of an API key

createApiKeyParams.name

String

the API key name

createApiKeyParams.expiryDate

String

the API key expiry date

[createApiKeyParams.description]

String

the API key description

Example

Example

apiKey.getAll([options]) ⇒ Promise

Kind: static method of apiKey Summary: Get all accessible API keys Access: public Fulfil: Object[] - apiKeys

Param
Type
Default
Description

[options]

Object

{}

extra pine options to use

Example

apiKey.getAllNamedUserApiKeys([options]) ⇒ Promise

Kind: static method of apiKey Summary: Get all named user API keys of the current user Access: public Fulfil: Object[] - apiKeys

Param
Type
Default
Description

[options]

Object

{}

extra pine options to use

Example

apiKey.getProvisioningApiKeysByApplication(slugOrUuidOrId, [options]) ⇒ Promise

Kind: static method of apiKey Summary: Get all provisioning API keys for an application Access: public Fulfil: Object[] - apiKeys

Param
Type
Default
Description

slugOrUuidOrId

String | Number

application slug (string), uuid (string) or id (number)

[options]

Object

{}

extra pine options to use

Example

apiKey.getDeviceApiKeysByDevice(uuidOrId, [options]) ⇒ Promise

Kind: static method of apiKey Summary: Get all API keys for a device Access: public Fulfil: Object[] - apiKeys

Param
Type
Default
Description

uuidOrId

String | Number

device, uuid (string) or id (number)

[options]

Object

{}

extra pine options to use

Example

apiKey.update(id, apiKeyInfo) ⇒ Promise

Kind: static method of apiKey Summary: Update the details of an API key Access: public

Param
Type
Description

id

Number

API key id

apiKeyInfo

Object

an object with the updated name

Example

Example

Example

Example

apiKey.revoke(id) ⇒ Promise

Kind: static method of apiKey Summary: Revoke an API key Access: public

Param
Type
Description

id

Number

API key id

Example

hashtag
models.key : object

Kind: static namespace of models

key.getAll([options]) ⇒ Promise

Kind: static method of key Summary: Get all ssh keys Access: public Fulfil: Object[] - ssh keys

Param
Type
Default
Description

[options]

Object

{}

extra pine options to use

Example

key.get(id) ⇒ Promise

Kind: static method of key Summary: Get a single ssh key Access: public Fulfil: Object - ssh key

Param
Type
Description

id

Number

key id

Example

key.remove(id) ⇒ Promise

Kind: static method of key Summary: Remove ssh key Access: public

Param
Type
Description

id

Number

key id

Example

key.create(title, key) ⇒ Promise

Kind: static method of key Summary: Create a ssh key Access: public Fulfil: Object - ssh key

Param
Type
Description

title

String

key title

key

String

the public ssh key

Example

hashtag
models.organization : object

Kind: static namespace of models

organization.membership : object

Kind: static namespace of organization

membership.get(membershipId, [options]) ⇒ Promise

This method returns a single organization membership.

Kind: static method of membership Summary: Get a single organization membership Access: public Fulfil: Object - organization membership

Param
Type
Default
Description

membershipId

number | Object

the id or an object with the unique user & is_member_of__organization numeric pair of the membership

[options]

Object

{}

extra pine options to use

Example

membership.getAllByOrganization(handleOrId, [options]) ⇒ Promise

This method returns all organization memberships for a specific organization.

Kind: static method of membership Summary: Get all memberships by organization Access: public Fulfil: Object[] - organization memberships

Param
Type
Default
Description

handleOrId

String | Number

organization handle (string) or id (number).

[options]

Object

{}

extra pine options to use

Example

Example

membership.getAllByUser(usernameOrId, [options]) ⇒ Promise

This method returns all organization memberships for a specific user.

Kind: static method of membership Summary: Get all memberships by user Access: public Fulfil: Object[] - organization memberships

Param
Type
Default
Description

usernameOrId

String | Number

the user's username (string) or id (number)

[options]

Object

{}

extra pine options to use

Example

Example

membership.changeRole(idOrUniqueKey, roleName) ⇒ Promise

This method changes the role of an organization member.

Kind: static method of membership Summary: Changes the role of an organization member Access: public

Param
Type
Description

idOrUniqueKey

Number | Object

the id or an object with the unique user & is_member_of__organization numeric pair of the membership that will be changed

roleName

String

the role name to be granted to the membership

Example

Example

membership.remove(id) ⇒ Promise

Kind: static method of membership Summary: Remove a membership Access: public

Param
Type
Description

id

Number

organization membership id

Example

Example

organization.invite : object

Kind: static namespace of organization

invite.getAll([options]) ⇒ Promise

This method returns all invites.

Kind: static method of invite Summary: Get all invites Access: public Fulfil: Object[] - invites

Param
Type
Default
Description

[options]

Object

{}

extra pine options to use

Example

invite.getAllByOrganization(handleOrId, [options]) ⇒ Promise

This method returns all invites for a specific organization.

Kind: static method of invite Summary: Get all invites by organization Access: public Fulfil: Object[] - invites

Param
Type
Default
Description

handleOrId

String | Number

organization handle (string), or id (number)

[options]

Object

{}

extra pine options to use

Example

Example

invite.create(handleOrId, options, [message]) ⇒ Promise

This method invites a user by their email to an organization.

Kind: static method of invite Summary: Creates a new invite for an organization Access: public Fulfil: String - organization invite

Param
Type
Default
Description

handleOrId

String | Number

organization handle (string), or id (number)

options

Object

invite creation parameters

options.invitee

String

the email of the invitee

[options.roleName]

String

"developer"

the role name to be granted to the invitee

[message]

String

the message to send along with the invite

Example

invite.revoke(id) ⇒ Promise

Kind: static method of invite Summary: Revoke an invite Access: public

Param
Type
Description

id

Number

organization invite id

Example

invite.accept(invitationToken) ⇒ Promise

This method adds the calling user to the organization.

Kind: static method of invite Summary: Accepts an invite Access: public

Param
Type
Description

invitationToken

String

invite token

Example

organization.create(options) ⇒ Promise

This method creates a new organization with the current user as an administrator.

Kind: static method of organization Summary: Creates a new organization Access: public Fulfil: String - Organization

Param
Type
Description

options

Object

Organization parameters to use.

options.name

String

Required: the name of the organization that will be created.

[options.handle]

String

The handle of the organization that will be created.

Example

Example

Example

organization.getAll([options]) ⇒ Promise

Kind: static method of organization Summary: Get all Organizations Access: public Fulfil: Object[] - organizations

Param
Type
Default
Description

[options]

Object

{}

extra pine options to use

Example

organization.get(handleOrId, [options]) ⇒ Promise

Kind: static method of organization Summary: Get a single organization Access: public Fulfil: Object - organization

Param
Type
Default
Description

handleOrId

String | Number

organization handle (string) or id (number).

[options]

Object

{}

extra pine options to use

Example

Example

organization.remove(handleOrId) ⇒ Promise

Kind: static method of organization Summary: Remove an Organization Access: public

Param
Type
Description

handleOrId

String | Number

organization handle (string) or id (number).

Example

hashtag
models.team : object

Kind: static namespace of models

team.applicationAccess : object

Kind: static namespace of team

applicationAccess.getAllByTeam(teamId, [options]) ⇒ Promise

This method get all team application access.

Kind: static method of applicationAccess Summary: Get all team applications access Access: public Fulfil: Object[] - team application access

Param
Type
Default
Description

teamId

Number

Required: the team id.

[options]

Object

{}

extra pine options to use

Example

applicationAccess.get(teamApplicationAccessId, [options]) ⇒ Promise

This method get specific team application access.

Kind: static method of applicationAccess Summary: Get team applications access Access: public Fulfil: Object - TeamApplicationAccess

Param
Type
Default
Description

teamApplicationAccessId

Number

Required: the team application access id.

[options]

Object

{}

extra pine options to use

Example

applicationAccess.update(teamApplicationAccessId, roleName) ⇒ Promise

This method update a team application access role.

Kind: static method of applicationAccess Summary: Update team application access Access: public Fulfil: Object - TeamApplicationAccess

Param
Type
Description

teamApplicationAccessId

Number

Required: the team application access id.

roleName

String

Required: The new role to assing (ApplicationMembershipRoles).

Example

applicationAccess.remove(teamApplicationAccessId) ⇒ Promise

This remove a team application access.

Kind: static method of applicationAccess Summary: Remove team application access Access: public Fulfil: void

Param
Type
Description

teamApplicationAccessId

Number

Required: the team application access id.

Example

team.create(organizationSlugOrId, name) ⇒ Promise

This method creates a new team.

Kind: static method of team Summary: Creates a new Team Access: public Fulfil: Object - Team

Param
Type
Description

organizationSlugOrId

Number

Required: the organization slug or id the team will be part of.

name

String

Required: the name of the team that will be created.

Example

Example

team.getAllByOrganization(organizationSlugOrId, [options]) ⇒ Promise

Kind: static method of team Summary: Get all Teams of a specific Organization Access: public Fulfil: Object[] - Teams

Param
Type
Default
Description

organizationSlugOrId

Number

Required: the organization slug or id the team is part of.

[options]

Object

{}

extra pine options to use

Example

Example

team.get(teamId, [options]) ⇒ Promise

Kind: static method of team Summary: Get a single Team Access: public Fulfil: Object - Team

Param
Type
Default
Description

teamId

Number

team id (number).

[options]

Object

{}

extra pine options to use

Example

team.rename(teamId, newName) ⇒ Promise

Kind: static method of team Summary: Rename Team Access: public

Param
Type
Description

teamId

Number

team id (number)

newName

String

new team name (string)

Example

team.remove(teamId) ⇒ Promise

Kind: static method of team Summary: Remove a Team Access: public

Param
Type
Description

teamId

Number

team id (number).

Example

hashtag
models.os : object

Kind: static namespace of models

os.getAvailableOsVersions(deviceTypes, [options]) ⇒ Promise

Kind: static method of os Summary: Get the supported OS versions for the provided device type(s) Access: public Fulfil: Object[]|Object - An array of OsVersion objects when a single device type slug is provided, or a dictionary of OsVersion objects by device type slug when an array of device type slugs is provided.

Param
Type
Default
Description

deviceTypes

String | Array.<String>

device type slug or array of slugs

[options]

Object

Extra pine options & draft filter to use

[options.includeDraft]

Boolean

false

Whether pre-releases should be included in the results

Example

Example

os.getAllOsVersions(deviceTypes, [options]) ⇒ Promise

Kind: static method of os Summary: Get all OS versions for the provided device type(s), inlcuding invalidated ones Access: public Fulfil: Object[]|Object - An array of OsVersion objects when a single device type slug is provided, or a dictionary of OsVersion objects by device type slug when an array of device type slugs is provided.

Param
Type
Default
Description

deviceTypes

String | Array.<String>

device type slug or array of slugs

[options]

Object

{}

extra pine options to use

Example

Example

Example

os.getDownloadSize(deviceType, [version]) ⇒ Promise

Note! Currently only the raw (uncompressed) size is reported.

Kind: static method of os Summary: Get OS download size estimate Access: public Fulfil: Number - OS image download size, in bytes.

Param
Type
Description

deviceType

String

device type slug

[version]

String

semver-compatible version or 'latest', defaults to 'latest'. The version must be the exact version number.

Example

os.getMaxSatisfyingVersion(deviceType, versionOrRange, [osType]) ⇒ Promise

Kind: static method of os Summary: Get the max OS version satisfying the given range Access: public Fulfil: String|null - the version number, or null if no matching versions are found

Param
Type
Description

deviceType

String

device type slug

versionOrRange

String

can be one of * the exact version number, in which case it is returned if the version is supported, or null is returned otherwise, * a semverarrow-up-right-compatible range specification, in which case the most recent satisfying version is returned if it exists, or null is returned, * 'latest'/'default' in which case the most recent version is returned, excluding pre-releases, Defaults to 'latest'.

[osType]

String

can be one of 'default', 'esr' or null to include all types

Example

os.download(options) ⇒ Promise

Kind: static method of os Summary: Download an OS image Access: public Fulfil: ReadableStream - download stream

Param
Type
Default
Description

options

Object

OS image options to use.

options.deviceType

String

device type slug

[options.version]

String

'latest'

semver-compatible version or 'latest', defaults to 'latest' Unsupported (unpublished) version will result in rejection. The version must be the exact version number.

[options.developmentMode]

Boolean

controls development mode for unified balenaOS releases.

[options.appId]

Number

the application ID (number).

[options.fileType]

String

download file type. One of '.img' or '.zip' or '.gz'.

[options.imageType]

String

download file type. One of 'raw' or 'flasher'

[options.appUpdatePollInterval]

Number

how often the OS checks for updates, in minutes.

[options.network]

String

the network type that the device will use, one of 'ethernet' or 'wifi'.

[options.wifiKey]

String

the key for the wifi network the device will connect to if network is wifi.

[options.wifiSsid]

String

the ssid for the wifi network the device will connect to if network is wifi.

Example

os.getConfig(slugOrUuidOrId, options) ⇒ Promise

Builds the config.json for a device in the given application, with the given options.

Note that an OS version is required. For versions < 2.7.8, config generation is only supported when using a session token, not an API key.

Kind: static method of os Summary: Get an applications config.json Access: public Fulfil: Object - application configuration as a JSON object.

Param
Type
Default
Description

slugOrUuidOrId

String | Number

application slug (string), uuid (string) or id (number).

options

Object

OS configuration options to use.

options.version

String

Required: the OS version of the image.

[options.network]

String

'ethernet'

The network type that the device will use, one of 'ethernet' or 'wifi'.

[options.appUpdatePollInterval]

Number

How often the OS checks for updates, in minutes.

[options.provisioningKeyName]

String

Name assigned to API key

[options.provisioningKeyExpiryDate]

String

Expiry Date assigned to API key

[options.developmentMode]

Boolean

Controls development mode for unified balenaOS releases.

[options.wifiKey]

String

The key for the wifi network the device will connect to.

[options.wifiSsid]

String

The ssid for the wifi network the device will connect to.

[options.ip]

String

static ip address.

[options.gateway]

String

static ip gateway.

[options.netmask]

String

static ip netmask.

Example

os.isSupportedOsUpdate(deviceType, currentVersion, targetVersion) ⇒ Promise

Kind: static method of os Summary: Returns whether the provided device type supports OS updates between the provided balenaOS versions Access: public Fulfil: Boolean - whether upgrading the OS to the target version is supported

Param
Type
Description

deviceType

String

device type slug

currentVersion

String

semver-compatible version for the starting OS version

targetVersion

String

semver-compatible version for the target OS version

Example

os.getOsUpdateType(deviceType, currentVersion, targetVersion) ⇒ Promise

Kind: static method of os Summary: Returns the OS update type based on device type, current and target balenaOS versions Access: public Fulfil: String - Currently available types are:

  • resinhup11

  • resinhup12

  • balenahup

    • takeover

Throws error in any of these cases:

  • Current or target versions are invalid

  • Current or target versions do not match in dev/prod type

  • Current and target versions imply a downgrade operation

  • Action is not supported by device type

Param
Type
Description

deviceType

String

device type slug

currentVersion

String

semver-compatible version for the starting OS version

targetVersion

String

semver-compatible version for the target OS version

Example

os.getSupportedOsUpdateVersions(deviceType, currentVersion, [options]) ⇒ Promise

Kind: static method of os Summary: Returns the supported OS update targets for the provided device type Access: public Fulfil: Object[]|Object - An array of OsVersion objects when a single device type slug is provided, or a dictionary of OsVersion objects by device type slug when an array of device type slugs is provided. Fulfil: Object - the versions information, of the following structure:

  • versions - an array of strings, containing exact version numbers that OS update is supported

  • recommended - the recommended version, i.e. the most recent version that is not pre-release, can be null

  • current - the provided current version after normalization

Param
Type
Default
Description

deviceType

String

device type slug

currentVersion

String

semver-compatible version for the starting OS version

[options]

Object

Extra options to filter the OS releases by

[options.includeDraft]

Boolean

false

Whether pre-releases should be included in the results

Example

os.isArchitectureCompatibleWith(osArchitecture, applicationArchitecture) ⇒ Boolean

Kind: static method of os Summary: Returns whether the specified OS architecture is compatible with the target architecture Returns: Boolean - - Whether the specified OS architecture is capable of running applications build for the target architecture Access: public

Param
Type
Description

osArchitecture

String

The OS's architecture as specified in its device type

applicationArchitecture

String

The application's architecture as specified in its device type

Example

os.getSupervisorReleasesForCpuArchitecture(cpuArchitectureSlugOrId, [options]) ⇒ Promise.<String>

Kind: static method of os Summary: Returns the Releases of the supervisor for the CPU Architecture Returns: Promise.<String> - - An array of Release objects that can be used to manage a device as supervisors. Access: public

Param
Type
Default
Description

cpuArchitectureSlugOrId

String | Number

The slug (string) or id (number) for the CPU Architecture

[options]

Object

{}

extra pine options to use

Example

hashtag
models.config : object

Kind: static namespace of models

config.getAll() ⇒ Promise

Kind: static method of config Summary: Get all configuration Access: public Fulfil: Object - configuration Example

config.getDeviceTypes() ⇒ Promise

use balena.models.deviceType.getAll

Kind: static method of config Summary: Get device types Access: public Fulfil: Object[] - device types Example

config.getDeviceTypeManifestBySlug(slugOrName) ⇒ Promise

use balena.models.deviceType.getBySlugOrName

Kind: static method of config Summary: Get a device type manifest by slug Access: public Fulfil: Object - device type manifest

Param
Type
Description

slugOrName

String

device type slug

Example

config.getDeviceOptions(deviceType) ⇒ Promise

Kind: static method of config Summary: Get configuration/initialization options for a device type Access: public Fulfil: Object[] - configuration options

Param
Type
Description

deviceType

String

device type slug

Example

config.getConfigVarSchema(deviceType) ⇒ Promise

Kind: static method of config Summary: Get configuration variables schema for a device type Access: public Fulfil: Object[] - configuration options

Param
Type
Description

deviceType

String

device type slug

Example

hashtag
models.release : object

Kind: static namespace of models

release.tags : object

Kind: static namespace of release

tags.getAllByApplication(slugOrUuidOrId, [options]) ⇒ Promise

Kind: static method of tags Summary: Get all release tags for an application Access: public Fulfil: Object[] - release tags

Param
Type
Default
Description

slugOrUuidOrId

String | Number

application slug (string), uuid (string) or id (number)

[options]

Object

{}

extra pine options to use

Example

Example

tags.getAllByRelease(commitOrIdOrRawVersion, [options]) ⇒ Promise

Kind: static method of tags Summary: Get all release tags for a release Access: public Fulfil: Object[] - release tags

Param
Type
Default
Description

commitOrIdOrRawVersion

String | Number | Object

release commit (string) or id (number) or an object with the unique application (number or string) & rawVersion (string) pair of the release

[options]

Object

{}

extra pine options to use

Example

Example

Example

tags.set(commitOrIdOrRawVersion, tagKey, value) ⇒ Promise

Kind: static method of tags Summary: Set a release tag Access: public

Param
Type
Description

commitOrIdOrRawVersion

String | Number | Object

release commit (string) or id (number) or an object with the unique application (number or string) & rawVersion (string) pair of the release

tagKey

String

tag key

value

String | undefined

tag value

Example

Example

Example

tags.remove(commitOrIdOrRawVersion, tagKey) ⇒ Promise

Kind: static method of tags Summary: Remove a release tag Access: public

Param
Type
Description

commitOrIdOrRawVersion

String | Number | Object

release commit (string) or id (number) or an object with the unique application (number or string) & rawVersion (string) pair of the release

tagKey

String

tag key

Example

Example

Example

release.get(commitOrIdOrRawVersion, [options]) ⇒ Promise

Kind: static method of release Summary: Get a specific release Access: public Fulfil: Object - release

Param
Type
Default
Description

commitOrIdOrRawVersion

String | Number | Object

release commit (string) or id (number) or an object with the unique application (number or string) & rawVersion (string) pair of the release

[options]

Object

{}

extra pine options to use

Example

Example

Example

release.getWithImageDetails(commitOrIdOrRawVersion, [options]) ⇒ Promise

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 significantly more control, or to see the raw model directly, use release.get(id, options) instead.

Kind: static method of release Summary: Get a specific release with the details of the images built Access: public Fulfil: Object - release with image details

Param
Type
Default
Description

commitOrIdOrRawVersion

String | Number | Object

release commit (string) or id (number) or an object with the unique application (number or string) & rawVersion (string) pair of the release

[options]

Object

{}

a map of extra pine options

[options.release]

Boolean

{}

extra pine options for releases

[options.image]

Object

{}

extra pine options for images

Example

Example

Example

Example

release.getAllByApplication(slugOrUuidOrId, [options]) ⇒ Promise

Kind: static method of release Summary: Get all releases from an application Access: public Fulfil: Object[] - releases

Param
Type
Default
Description

slugOrUuidOrId

String | Number

application slug (string), uuid (string) or id (number)

[options]

Object

{}

extra pine options to use

Example

Example

release.getLatestByApplication(slugOrUuidOrId, [options]) ⇒ Promise

Kind: static method of release Summary: Get the latest successful release for an application Access: public Fulfil: Object|undefined - release

Param
Type
Default
Description

slugOrUuidOrId

String | Number

application slug (string), uuid (string) or id (number)

[options]

Object

{}

extra pine options to use

Example

Example

release.createFromUrl(slugOrUuidOrId, urlDeployOptions) ⇒ Promise

Kind: static method of release Summary: Create a new release built from the source in the provided url Access: public Fulfil: number - release ID

Param
Type
Default
Description

slugOrUuidOrId

String | Number

application slug (string), uuid (string) or id (number)

urlDeployOptions

Object

builder options

urlDeployOptions.url

String

a url with a tarball of the project to build

[urlDeployOptions.shouldFlatten]

Boolean

true

Should be true when the tarball includes an extra root folder with all the content

Example

Example

release.finalize(commitOrIdOrRawVersion) ⇒ Promise

Kind: static method of release Summary: Finalizes a draft release Access: public Fulfil: void

Param
Type
Description

commitOrIdOrRawVersion

String | Number | Object

release commit (string) or id (number) or an object with the unique application (number or string) & rawVersion (string) pair of the release

Example

Example

Example

release.setIsInvalidated(commitOrIdOrRawVersion, isInvalidated) ⇒ Promise

Kind: static method of release Summary: Set the is_invalidated property of a release to true or false Access: public Fulfil: void

Param
Type
Description

commitOrIdOrRawVersion

String | Number | Object

release commit (string) or id (number) or an object with the unique application (number or string) & rawVersion (string) pair of the release

isInvalidated

Boolean

boolean value, true for invalidated, false for validated

Example

Example

Example

Example

Example

release.setNote(commitOrIdOrRawVersion, noteOrNull) ⇒ Promise

Kind: static method of release Summary: Add a note to a release Access: public

Param
Type
Description

commitOrIdOrRawVersion

String | Number | Object

release commit (string) or id (number) or an object with the unique application (number or string) & rawVersion (string) pair of the release

noteOrNull

String | Null

the note

Example

Example

Example

release.setKnownIssueList(commitOrIdOrRawVersion, knownIssueListOrNull) ⇒ Promise

Kind: static method of release Summary: Add a known issue list to a release Access: public

Param
Type
Description

commitOrIdOrRawVersion

String | Number | Object

release commit (string) or id (number) or an object with the unique application (number or string) & rawVersion (string) pair of the release

knownIssueListOrNull

String | Null

the known issue list

Example

Example

Example

hashtag
models.service : object

Kind: static namespace of models

service.var : object

Kind: static namespace of service

var.getAllByService(serviceIdOrNaturalKey, [options]) ⇒ Promise

Kind: static method of var Summary: Get all variables for a service Access: public Fulfil: Object[] - service variables

Param
Type
Default
Description

serviceIdOrNaturalKey

Number | Object

service id (number) or appliation-service_name pair

[options]

Object

{}

extra pine options to use

Example

Example

var.getAllByApplication(slugOrUuidOrId, [options]) ⇒ Promise

Kind: static method of var Summary: Get all service variables by application Access: public Fulfil: Object[] - service variables

Param
Type
Default
Description

slugOrUuidOrId

String | Number

application slug (string), uuid (string) or id (number)

[options]

Object

{}

extra pine options to use

Example

Example

var.get(serviceIdOrNaturalKey, key) ⇒ Promise

Kind: static method of var Summary: Get the value of a specific service variable Access: public Fulfil: String|undefined - the variable value (or undefined)

Param
Type
Description

serviceIdOrNaturalKey

Number | Object

service id (number) or appliation-service_name pair

key

String

variable name

Example

Example

var.set(serviceIdOrNaturalKey, key, value) ⇒ Promise

Kind: static method of var Summary: Set the value of a specific service variable Access: public

Param
Type
Description

serviceIdOrNaturalKey

Number | Object

service id (number) or appliation-service_name pair

key

String

variable name

value

String

variable value

Example

Example

var.remove(serviceIdOrNaturalKey, key) ⇒ Promise

Kind: static method of var Summary: Clear the value of a specific service variable Access: public

Param
Type
Description

serviceIdOrNaturalKey

Number | Object

service id (number) or appliation-service_name pair

key

String

variable name

Example

Example

service.getAllByApplication(slugOrUuidOrId, [options]) ⇒ Promise

Kind: static method of service Summary: Get all services from an application Access: public Fulfil: Object[] - services

Param
Type
Default
Description

slugOrUuidOrId

String | Number

application slug (string), uuid (string) or id (number)

[options]

Object

{}

extra pine options to use

Example

Example

hashtag
models.image : object

Kind: static namespace of models

image.get(id, [options]) ⇒ Promise

Kind: static method of image Summary: Get a specific image Access: public Fulfil: Object - image

Param
Type
Default
Description

id

Number

image id

[options]

Object

{}

extra pine options to use

Example

image.getLogs(id) ⇒ Promise

Kind: static method of image Summary: Get the logs for an image Access: public Fulfil: string | null - logs

Param
Type
Description

id

Number

image id

Example

hashtag
models.creditBundle : object

Kind: static namespace of models

creditBundle.getAllByOrg(organization, [options]) ⇒ Promise

Kind: static method of creditBundle Summary: Get all of the credit bundles purchased by the given org Access: public Fulfil: Object[] - credit bundles

Param
Type
Default
Description

organization

String | Number

handle (string) or id (number) of the target organization.

[options]

Object

{}

extra pine options to use

Example

creditBundle.create(organization, featureId, creditsToPurchase) ⇒ Promise

Kind: static method of creditBundle Summary: Purchase a credit bundle for the given feature and org of the given quantity Access: public Fulfil: Object[] - credit bundles

Param
Type
Description

organization

String | Number

handle (string) or id (number) of the target organization.

featureId

Number

id (number) of the feature for which credits are being purchased.

creditsToPurchase

Number

number of credits being purchased.

Example

hashtag
models.billing : object

Note! The billing methods are available on Balena.io exclusively.

Kind: static namespace of models

billing.getAccount(organization) ⇒ Promise

Kind: static method of billing Summary: Get the user's billing account Access: public Fulfil: Object - billing account

Param
Type
Description

organization

String | Number

handle (string) or id (number) of the target organization.

Example

billing.getPlan(organization) ⇒ Promise

Kind: static method of billing Summary: Get the current billing plan Access: public Fulfil: Object - billing plan

Param
Type
Description

organization

String | Number

handle (string) or id (number) of the target organization.

Example

billing.getBillingInfo(organization) ⇒ Promise

Kind: static method of billing Summary: Get the current billing information Access: public Fulfil: Object - billing information

Param
Type
Description

organization

String | Number

handle (string) or id (number) of the target organization.

Example

billing.createSetupIntent(setupIntentParams) ⇒ Promise

Kind: static method of billing Summary: Create a Stripe setup intent required for setting billing information Access: public Fulfil: Object - partial stripe setup intent object

Param
Type
Description

setupIntentParams

Object

an object containing the parameters for the setup intent creation

extraParams.organization

String | Number

handle (string) or id (number) of the target organization.

[extraParams.'g-recaptcha-response']

String | undefined

the captcha response

Example

billing.updateBillingInfo(organization, billingInfo) ⇒ Promise

Kind: static method of billing Summary: Update the current billing information Access: public Fulfil: Object - billing information

Param
Type
Description

organization

String | Number

handle (string) or id (number) of the target organization.

billingInfo

Object

an object containing a billing info token_id

billingInfo.token_id

String

the token id generated for the billing info form

[billingInfo.'g-recaptcha-response']

String | undefined

the captcha response

[billingInfo.token_type]

String | undefined

token type

Example

billing.removeBillingInfo(organization) ⇒ Promise

Kind: static method of billing Summary: Remove an organization's billing information Access: public

Param
Type
Description

organization

String | Number

handle (string) or id (number) of the target organization.

Example

billing.updateAccountInfo(organization, accountInfo)

Kind: static method of billing Summary: Update the current billing account information Access: public

Param
Type
Description

organization

String | Number

handle (string) or id (number) of the target organization.

accountInfo

AccountInfo

an object containing billing account info

Example

Example

billing.changePlan(organization, planChangeOptions) ⇒ Promise

Kind: static method of billing Summary: Change the current billing plan Access: public

Param
Type
Description

organization

String | Number

handle (string) or id (number) of the target organization.

planChangeOptions

Object

an object containing the billing plan change options

billingInfo.tier

String

the code of the target billing plan

billingInfo.cycle

String

the billing cycle

[billingInfo.planChangeReason]

String

the reason for changing the current plan

Example

billing.getInvoices(organization) ⇒ Promise

Kind: static method of billing Summary: Get the available invoices Access: public Fulfil: Object - invoices

Param
Type
Description

organization

String | Number

handle (string) or id (number) of the target organization.

Example

billing.downloadInvoice(organization) ⇒ Promise

Kind: static method of billing Summary: Download a specific invoice Access: public Fulfil: Blob|ReadableStream - blob on the browser, download stream on node

Param
Type
Description

organization

String | Number

handle (string) or id (number) of the target organization.

String

an invoice number

Example

hashtag
balena.auth : object

Kind: static namespace of balena

hashtag
auth.twoFactor : object

Kind: static namespace of auth

twoFactor.isEnabled() ⇒ Promise

Kind: static method of twoFactor Summary: Check if two factor authentication is enabled Access: public Fulfil: Boolean - whether 2fa is enabled Example

twoFactor.isPassed() ⇒ Promise

Kind: static method of twoFactor Summary: Check if two factor authentication challenge was passed Access: public Fulfil: Boolean - whether 2fa challenge was passed Example

twoFactor.verify(code) ⇒ Promise

Verifies two factor authentication. Note that this method not update the token automatically. You should use challenge when possible, as it takes care of that as well.

Kind: static method of twoFactor Summary: Verify two factor authentication Access: public Fulfil: String - session token

Param
Type
Description

code

String

code

Example

twoFactor.getSetupKey() ⇒ Promise

Retrieves a setup key for enabling two factor authentication.

Kind: static method of twoFactor Summary: Get two factor authentication setup key Access: public Fulfil: String - setup key Example

twoFactor.enable(code) ⇒ Promise

Enables two factor authentication.

Kind: static method of twoFactor Summary: Enable two factor authentication Access: public Fulfil: String - session token

Param
Type
Description

code

String

code

Example

twoFactor.challenge(code) ⇒ Promise

You should use login when possible, as it takes care of saving the token and email as well.

Kind: static method of twoFactor Summary: Challenge two factor authentication and complete login Access: public

Param
Type
Description

code

String

code

Example

twoFactor.disable(password) ⇒ Promise

Disables two factor authentication.

Kind: static method of twoFactor Summary: Disable two factor authentication Access: public Fulfil: String - session token

Param
Type
Description

password

String

password

Example

hashtag
auth.whoami() ⇒ Promise

This will only work if you used login or loginWithToken to log in.

Kind: static method of auth Summary: Return current logged in information Access: public Fulfil: (Object|undefined) - actor information, if it exists Example

hashtag
auth.authenticate(credentials) ⇒ Promise

You should use login when possible, as it takes care of saving the token and email as well.

Notice that if credentials contains extra keys, they'll be discarted by the server automatically.

Kind: static method of auth Summary: Authenticate with the server Access: protected Fulfil: String - session token

Param
Type
Description

credentials

Object

in the form of email, password

credentials.email

String

the email

credentials.password

String

the password

Example

hashtag
auth.login(credentials) ⇒ Promise

If the login is successful, the token is persisted between sessions.

Kind: static method of auth Summary: Login Access: public

Param
Type
Description

credentials

Object

in the form of email, password

credentials.email

String

the email

credentials.password

String

the password

Example

hashtag
auth.loginWithToken(authToken) ⇒ Promise

Login to balena with a session token or api key instead of with credentials.

Kind: static method of auth Summary: Login with a token or api key Access: public

Param
Type
Description

authToken

String

the auth token

Example

hashtag
auth.isLoggedIn() ⇒ Promise

Kind: static method of auth Summary: Check if you're logged in Access: public Fulfil: Boolean - is logged in Example

hashtag
auth.getToken() ⇒ Promise

This will only work if you used login to log in.

Kind: static method of auth Summary: Get current logged in user's raw API key or session token Access: public Fulfil: String - raw API key or session token Example

hashtag
auth.getUserInfo() ⇒ Promise

This will only work if you used login to log in.

Kind: static method of auth Summary: Get current logged in user's info Access: public Fulfil: Object - user info Example

hashtag
auth.getActorId() ⇒ Promise

This will only work if you used login or loginWithToken to log in.

Kind: static method of auth Summary: Get current logged in actor id Access: public Fulfil: Number - actor id Example

hashtag
auth.logout() ⇒ Promise

Kind: static method of auth Summary: Logout Access: public Example

hashtag
auth.register(credentials) ⇒ Promise

Kind: static method of auth Summary: Register a user account Access: public Fulfil: String - session token

Param
Type
Description

credentials

Object

in the form of username, password and email

credentials.email

String

the email

credentials.password

String

the password

[credentials.'g-recaptcha-response']

String | undefined

the captcha response

Example

hashtag
auth.verifyEmail(verificationPayload) ⇒ Promise

Kind: static method of auth Summary: Verifies an email Access: public Fulfil: String - session token

Param
Type
Description

verificationPayload

Object

in the form of email, and token

verificationPayload.email

String

the email

verificationPayload.token

String

the verification token

Example

hashtag
auth.requestVerificationEmail() ⇒ Promise

This will only work if you used login to log in.

Kind: static method of auth Summary: Re-send verification email to the user Access: public Example

hashtag
balena.logs : object

Kind: static namespace of balena

hashtag
logs.subscribe(uuidOrId, [options]) ⇒ Promise.<LogSubscription>

Connects to the stream of devices logs, returning a LogSubscription, which can be used to listen for logs as they appear, line by line.

Kind: static method of logs Summary: Subscribe to device logs Access: public Fulfil: LogSubscription

Param
Type
Default
Description

uuidOrId

String | Number

device uuid (string) or id (number)

[options]

Object

options

[options.count]

Number | 'all'

0

number of historical messages to include (or 'all')

[options.start]

Number | String

the timestamp or ISO Date string after which to retrieve historical messages. When specified, the count parameter needs to also be provided.

Example

Example

hashtag
logs.history(uuidOrId, [options]) ⇒ Promise

Get an array of the latest log messages for a given device.

Kind: static method of logs Summary: Get device logs history Access: public Fulfil: Object[] - history lines

Param
Type
Default
Description

uuidOrId

String | Number

device uuid (string) or id (number)

[options]

Object

options

[options.count]

Number | 'all'

1000

number of log messages to return (or 'all')

[options.start]

Number | String

the timestamp or ISO Date string after which to retrieve historical messages

Example

Example

Example

Example

hashtag
logs.LogSubscription : EventEmitter

The log subscription emits events as log data arrives. You can get a LogSubscription for a given device by calling balena.logs.subscribe(deviceId)

Kind: static typedef of logs

LogSubscription.unsubscribe()

Disconnect from the logs feed and stop receiving any future events on this emitter.

Kind: static method of LogSubscription Summary: Unsubscribe from device logs Access: public Example

"line"

Kind: event emitted by LogSubscription Summary: Event fired when a new line of log output is available Example

"error"

Kind: event emitted by LogSubscription Summary: Event fired when an error has occured reading the device logs Example

hashtag
balena.settings : object

Kind: static namespace of balena

hashtag
settings.get([key]) ⇒ Promise

Kind: static method of settings Summary: Get a single setting. Only implemented in Node.js Access: public Fulfil: * - setting value

Param
Type
Description

[key]

String

setting key

Example

hashtag
settings.getAll() ⇒ Promise

Kind: static method of settings Summary: Get all settings Only implemented in Node.js Access: public Fulfil: Object - settings Example

hashtag
balena.utils : object

Kind: static namespace of balena

hashtag
listImagesFromTargetState(targetState) ⇒

Kind: global function Returns: array containing all images for all services for all releases for all apps for the device

Param

targetState

Previousv22.4.9Nextv20.9.1 (DEPRECATED)

Last updated

Was this helpful?