1. Reference
  2. SDKs
  3. Node.js SDK
Improve this doc
balena SDK version

Balena Node.js SDK v20.8.1 Documentation

Installation

Install the balena SDK by running:

$ npm install --save balena-sdk

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

Bundling with pkg

The balena SDK includes builds for various ECMAScript versions that are dynamically selected at runtime (using @balena/es-version). For this reason, packagers like pkg 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 project.

Trying balenaSDK in the browser

BalenaSDK is widely utilized in the balenaCloud dashboard 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 dashboard and open the browser developer console. 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 GitHub, we'll be happy to help.

Modules

balena-sdk

Objects

balena : object

Functions

listImagesFromTargetState(targetState) ⇒

balena-sdk

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 

// with es6 imports
import { getSdk } from 'balena-sdk';
// or with node require
const { getSdk } = require('balena-sdk');

const balena = getSdk({
    apiUrl: "https://api.balena-cloud.com/",
    dataDirectory: "/opt/local/balena"
});

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 false when enabled the sdk will retry requests that are failing with a 429 Too Many Requests status code and that include a numeric Retry-After response header.
[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 

import { setSharedOptions } from 'balena-sdk';
setSharedOptions({
    apiUrl: 'https://api.balena-cloud.com/',
    builderUrl: 'https://builder.balena-cloud.com/',
    isBrowser: true,
});

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 

import { fromSharedOptions } from 'balena-sdk';
const sdk = fromSharedOptions();

balena : object

Kind: global namespace

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 

balena.interceptors.push({
    responseError: function (error) {
        console.log(error);
        throw error;
    })
});

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.

balena.utils : Object

The utils instance offers some convenient features for clients.

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

balena.utils.mergePineOptions(
 { $expand: { device: { $select: ['id'] } } },
 { $expand: { device: { $select: ['name'] } } },
);

Example 

// Creating a new WebResourceFile in case 'File' API is not available.
new balena.utils.BalenaWebResourceFile(
  [fs.readFileSync('./file.tgz')],
  'file.tgz'
);

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 

balena.request.send({ url: 'http://api.balena-cloud.com/ping' });

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 

balena.pine.get({
    resource: 'release',
    options: {
        $count: {
            $filter: { belongs_to__application: applicationId }
        }
    }
});

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 

balena.models.device.get(123).catch(function (error) {
  if (error.code === balena.errors.BalenaDeviceNotFound.prototype.code) {
    ...
  } else if (error.code === balena.errors.BalenaRequestError.prototype.code) {
    ...
  }
});

balena.models : object

Kind: static namespace of balena

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 

balena.models.application.tags.getAllByApplication('myorganization/myapp').then(function(tags) {
    console.log(tags);
});

Example 

balena.models.application.tags.getAllByApplication(999999).then(function(tags) {
    console.log(tags);
});

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 

balena.models.application.tags.set('myorganization/myapp', 'EDITOR', 'vim');

Example 

balena.models.application.tags.set(123, 'EDITOR', 'vim');

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 

balena.models.application.tags.remove('myorganization/myapp', 'EDITOR');

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 

balena.models.application.configVar.getAllByApplication('myorganization/myapp').then(function(vars) {
    console.log(vars);
});

Example 

balena.models.application.configVar.getAllByApplication(999999).then(function(vars) {
    console.log(vars);
});

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 

balena.models.application.configVar.get('myorganization/myapp', 'BALENA_VAR').then(function(value) {
    console.log(value);
});

Example 

balena.models.application.configVar.get(999999, 'BALENA_VAR').then(function(value) {
    console.log(value);
});

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 

balena.models.application.configVar.set('myorganization/myapp', 'BALENA_VAR', 'newvalue').then(function() {
    ...
});

Example 

balena.models.application.configVar.set(999999, 'BALENA_VAR', 'newvalue').then(function() {
    ...
});

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 

balena.models.application.configVar.remove('myorganization/myapp', 'BALENA_VAR').then(function() {
    ...
});

Example 

balena.models.application.configVar.remove(999999, 'BALENA_VAR').then(function() {
    ...
});

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 

balena.models.application.envVar.getAllByApplication('myorganization/myapp').then(function(vars) {
    console.log(vars);
});

Example 

balena.models.application.envVar.getAllByApplication(999999).then(function(vars) {
    console.log(vars);
});

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 

balena.models.application.envVar.get('myorganization/myapp', 'VAR').then(function(value) {
    console.log(value);
});

Example 

balena.models.application.envVar.get(999999, 'VAR').then(function(value) {
    console.log(value);
});

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 

balena.models.application.envVar.set('myorganization/myapp', 'VAR', 'newvalue').then(function() {
    ...
});

Example 

balena.models.application.envVar.set(999999, 'VAR', 'newvalue').then(function() {
    ...
});

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 

balena.models.application.envVar.remove('myorganization/myapp', 'VAR').then(function() {
    ...
});

Example 

balena.models.application.envVar.remove(999999, 'VAR').then(function() {
    ...
});

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 

balena.models.application.buildVar.getAllByApplication('myorganization/myapp').then(function(vars) {
    console.log(vars);
});

Example 

balena.models.application.buildVar.getAllByApplication(999999).then(function(vars) {
    console.log(vars);
});

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 

balena.models.application.buildVar.get('myorganization/myapp', 'VAR').then(function(value) {
    console.log(value);
});

Example 

balena.models.application.buildVar.get(999999, 'VAR').then(function(value) {
    console.log(value);
});

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 

balena.models.application.buildVar.set('myorganization/myapp', 'VAR', 'newvalue').then(function() {
    ...
});

Example 

balena.models.application.buildVar.set(999999, 'VAR', 'newvalue').then(function() {
    ...
});

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 

balena.models.application.buildVar.remove('myorganization/myapp', 'VAR').then(function() {
    ...
});

Example 

balena.models.application.buildVar.remove(999999, 'VAR').then(function() {
    ...
});

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 

balena.models.application.membership.get(5).then(function(memberships) {
    console.log(memberships);
});

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 

balena.models.application.membership.getAllByApplication('myorganization/myapp').then(function(memberships) {
    console.log(memberships);
});

Example 

balena.models.application.membership.getAllByApplication(123).then(function(memberships) {
    console.log(memberships);
});

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 

balena.models.application.membership.getAllByUser('balena_os').then(function(memberships) {
    console.log(memberships);
});

Example 

balena.models.application.membership.getAllByUser(123).then(function(memberships) {
    console.log(memberships);
});

membership.create(options) ⇒ Promise

This method adds a user to an application by their username.

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 

balena.models.application.membership.create({ application: "myApp", username: "user123", roleName: "member" }).then(function(membership) {
    console.log(membership);
});

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 

balena.models.application.membership.changeRole(123, "member").then(function() {
    console.log('OK');
});

Example 

balena.models.application.membership.changeRole({
    user: 123,
    is_member_of__application: 125,
}, "member").then(function() {
    console.log('OK');
});

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 

balena.models.application.membership.remove(123);

Example 

balena.models.application.membership.remove({
    user: 123,
    is_member_of__application: 125,
});

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 

balena.models.application.invite.getAll().then(function(invites) {
    console.log(invites);
});

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 

balena.models.application.invite.getAllByApplication('myorganization/myapp').then(function(invites) {
    console.log(invites);
});

Example 

balena.models.application.invite.getAllByApplication(123).then(function(invites) {
    console.log(invites);
});

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 

balena.models.application.invite.create('myorganization/myapp', { invitee: "[email protected]", roleName: "developer", message: "join my app" }).then(function(invite) {
    console.log(invite);
});

invite.revoke(id) ⇒ Promise

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

Param Type Description
id Number application invite id

Example 

balena.models.application.invite.revoke(123);

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 

balena.models.application.invite.accept("qwerty-invitation-token");

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 

balena.models.application.get('myorganization/myapp').then(function(application) {
    const dashboardApplicationUrl = balena.models.application.getDashboardUrl(application.id);
    console.log(dashboardApplicationUrl);
});

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 

balena.models.application.getAll().then(function(applications) {
    console.log(applications);
});

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 

balena.models.application.getAllDirectlyAccessible().then(function(applications) {
    console.log(applications);
});

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 

balena.models.application.getAllByOrganization().then(function(applications) {
    console.log(applications);
});

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 

balena.models.application.get('myorganization/myapp').then(function(application) {
    console.log(application);
});

Example 

balena.models.application.get('1bf99a68cf9e4266986e6dec7a6e8f46').then(function(application) {
    console.log(application);
});

Example 

balena.models.application.get(123).then(function(application) {
    console.log(application);
});

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 

balena.models.application.getDirectlyAccessible('myorganization/myapp').then(function(application) {
    console.log(application);
});

Example 

balena.models.application.getDirectlyAccessible(123).then(function(application) {
    console.log(application);
});

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 

balena.models.application.getWithDeviceServiceDetails('myorganization/myapp').then(function(device) {
    console.log(device);
})

Example 

balena.models.application.getWithDeviceServiceDetails(123).then(function(device) {
    console.log(device);
})

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 

balena.models.application.getAppByName('MyApp').then(function(application) {
    console.log(application);
});

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 

balena.models.application.has('myorganization/myapp').then(function(hasApp) {
    console.log(hasApp);
});

Example 

balena.models.application.has(123).then(function(hasApp) {
    console.log(hasApp);
});

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 

balena.models.application.hasAny().then(function(hasAny) {
    console.log('Has any?', hasAny);
});

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 

balena.models.application.create({ name: 'My App', deviceType: 'raspberry-pi' }).then(function(application) {
    console.log(application);
});

Example 

balena.models.application.create({ name: 'My Block', applicationClass: 'block', deviceType: 'raspberry-pi' }).then(function(application) {
    console.log(application);
});

Example 

balena.models.application.create({ name: 'My App', deviceType: 'raspberry-pi', parent: 'ParentApp' }).then(function(application) {
    console.log(application);
});

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 

balena.models.application.remove('myorganization/myapp');

Example 

balena.models.application.remove(123);

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 

balena.models.application.rename('myorganization/myapp', 'MyRenamedApp');

Example 

balena.models.application.rename(123, 'MyRenamedApp');

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 

balena.models.application.restart('myorganization/myapp');

Example 

balena.models.application.restart(123);

application.generateApiKey(slugOrUuidOrId) ⇒ Promise

Deprecated

Generally you shouldn't use this method: if you're provisioning a recent BalenaOS version (2.4.0+) then generateProvisioningKey should work just as well, but be more secure.

Kind: static method of application
Summary: Generate an API key for a specific application
Access: public
Fulfil: String - api key

Param Type Description
slugOrUuidOrId String | Number application slug (string), uuid (string) or id (number)

Example 

balena.models.application.generateApiKey('myorganization/myapp').then(function(apiKey) {
    console.log(apiKey);
});

Example 

balena.models.application.generateApiKey(123).then(function(apiKey) {
    console.log(apiKey);
});

application.generateProvisioningKey(slugOrUuidOrId, [keyName], [keyDescription], [keyExpiryDate]) ⇒ 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
slugOrUuidOrId String | Number application slug (string), uuid (string) or id (number)
[keyName] String Provisioning key name
[keyDescription] String Description for provisioning key
[keyExpiryDate] String Expiry Date for provisioning key

Example 

balena.models.application.generateProvisioningKey('myorganization/myapp').then(function(key) {
    console.log(key);
});

Example 

balena.models.application.generateProvisioningKey(123).then(function(key) {
    console.log(key);
});

Example 

balena.models.application.generateProvisioningKey(123, 'api key name', 'api key long description', '2030-01-01T00:00:00Z').then(function(key) {
    console.log(key);
});

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 

balena.models.application.purge(123);

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 

balena.models.application.shutdown(123);

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 

balena.models.application.reboot(123);

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 

balena.models.application.willTrackNewReleases('myorganization/myapp').then(function(isEnabled) {
    console.log(isEnabled);
});

Example 

balena.models.application.willTrackNewReleases(123).then(function(isEnabled) {
    console.log(isEnabled);
});

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 

balena.models.application.isTrackingLatestRelease('myorganization/myapp').then(function(isEnabled) {
    console.log(isEnabled);
});

Example 

balena.models.application.isTrackingLatestRelease(123).then(function(isEnabled) {
    console.log(isEnabled);
});

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 

balena.models.application.pinToRelease('myorganization/myapp', 'f7caf4ff80114deeaefb7ab4447ad9c661c50847').then(function() {
    ...
});

Example 

balena.models.application.pinToRelease(123, 'f7caf4ff80114deeaefb7ab4447ad9c661c50847').then(function() {
    ...
});

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 

balena.models.application.getTargetReleaseHash('myorganization/myapp').then(function(release) {
    console.log(release);
});

Example 

balena.models.application.getTargetReleaseHash(123).then(function(release) {
    console.log(release);
});

Example 

balena.models.application.getTargetReleaseHash('myorganization/myapp', function(release) {
    console.log(release);
});

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 

balena.models.application.trackLatestRelease('myorganization/myapp').then(function() {
    ...
});

Example 

balena.models.application.trackLatestRelease(123).then(function() {
    ...
});

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 

balena.models.application.enableDeviceUrls('myorganization/myapp');

Example 

balena.models.application.enableDeviceUrls(123);

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 

balena.models.application.disableDeviceUrls('myorganization/myapp');

Example 

balena.models.application.disableDeviceUrls(123);

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 

balena.models.application.grantSupportAccess('myorganization/myapp', Date.now() + 3600 * 1000);

Example 

balena.models.application.grantSupportAccess(123, Date.now() + 3600 * 1000);

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 

balena.models.application.revokeSupportAccess('myorganization/myapp');

Example 

balena.models.application.revokeSupportAccess(123);

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 

balena.models.device.tags.getAllByApplication('myorganization/myapp').then(function(tags) {
    console.log(tags);
});

Example 

balena.models.device.tags.getAllByApplication(999999).then(function(tags) {
    console.log(tags);
});

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 

balena.models.device.tags.getAllByDevice('7cf02a6').then(function(tags) {
    console.log(tags);
});

Example 

balena.models.device.tags.getAllByDevice(123).then(function(tags) {
    console.log(tags);
});

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 

balena.models.device.tags.set('7cf02a6', 'EDITOR', 'vim');

Example 

balena.models.device.tags.set(123, 'EDITOR', 'vim');

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 

balena.models.device.tags.remove('7cf02a6', 'EDITOR');

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 

balena.models.device.configVar.getAllByDevice('7cf02a6').then(function(vars) {
    console.log(vars);
});

Example 

balena.models.device.configVar.getAllByDevice(999999).then(function(vars) {
    console.log(vars);
});

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 

balena.models.device.configVar.getAllByApplication('myorganization/myapp').then(function(vars) {
    console.log(vars);
});

Example 

balena.models.device.configVar.getAllByApplication(999999).then(function(vars) {
    console.log(vars);
});

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 

balena.models.device.configVar.get('7cf02a6', 'BALENA_VAR').then(function(value) {
    console.log(value);
});

Example 

balena.models.device.configVar.get(999999, 'BALENA_VAR').then(function(value) {
    console.log(value);
});

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 

balena.models.device.configVar.set('7cf02a6', 'BALENA_VAR', 'newvalue').then(function() {
    ...
});

Example 

balena.models.device.configVar.set(999999, 'BALENA_VAR', 'newvalue').then(function() {
    ...
});

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 

balena.models.device.configVar.remove('7cf02a6', 'BALENA_VAR').then(function() {
    ...
});

Example 

balena.models.device.configVar.remove(999999, 'BALENA_VAR').then(function() {
    ...
});

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 

balena.models.device.envVar.getAllByDevice('7cf02a6').then(function(vars) {
    console.log(vars);
});

Example 

balena.models.device.envVar.getAllByDevice(999999).then(function(vars) {
    console.log(vars);
});

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 

balena.models.device.envVar.getAllByApplication('myorganization/myapp').then(function(vars) {
    console.log(vars);
});

Example 

balena.models.device.envVar.getAllByApplication(999999).then(function(vars) {
    console.log(vars);
});

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 

balena.models.device.envVar.get('7cf02a6', 'VAR').then(function(value) {
    console.log(value);
});

Example 

balena.models.device.envVar.get(999999, 'VAR').then(function(value) {
    console.log(value);
});

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 

balena.models.device.envVar.set('7cf02a6', 'VAR', 'newvalue').then(function() {
    ...
});

Example 

balena.models.device.envVar.set(999999, 'VAR', 'newvalue').then(function() {
    ...
});

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 

balena.models.device.envVar.remove('7cf02a6', 'VAR').then(function() {
    ...
});

Example 

balena.models.device.envVar.remove(999999, 'VAR').then(function() {
    ...
});

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 

balena.models.device.serviceVar.getAllByDevice('7cf02a6').then(function(vars) {
    console.log(vars);
});

Example 

balena.models.device.serviceVar.getAllByDevice(999999).then(function(vars) {
    console.log(vars);
});

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 

balena.models.device.serviceVar.getAllByApplication('myorganization/myapp').then(function(vars) {
    console.log(vars);
});

Example 

balena.models.device.serviceVar.getAllByApplication(999999).then(function(vars) {
    console.log(vars);
});

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 

balena.models.device.serviceVar.get('7cf02a6', 123, 'VAR').then(function(value) {
    console.log(value);
});

Example 

balena.models.device.serviceVar.get('7cf02a6', 'myservice', 'VAR').then(function(value) {
    console.log(value);
});

Example 

balena.models.device.serviceVar.get(999999, 123, 'VAR').then(function(value) {
    console.log(value);
});

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 

balena.models.device.serviceVar.set('7cf02a6', 123, 'VAR', 'override').then(function() {
    ...
});

Example 

balena.models.device.serviceVar.set('7cf02a6', 'myservice', 'VAR', 'override').then(function() {
    ...
});

Example 

balena.models.device.serviceVar.set(999999, 123, 'VAR', 'override').then(function() {
    ...
});

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 

balena.models.device.serviceVar.remove('7cf02a6', 123, 'VAR').then(function() {
    ...
});

Example 

balena.models.device.serviceVar.remove('7cf02a6', 'myservice', 'VAR').then(function() {
    ...
});

Example 

balena.models.device.serviceVar.remove(999999, 123, 'VAR').then(function() {
    ...
});

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 

balena.models.device.history.getAllByDevice('7cf02a687b74206f92cb455969cf8e98').then(function(entries) {
    console.log(entries);
});

Example 

balena.models.device.history.getAllByDevice(999999).then(function(entries) {
    console.log(entries);
});

Example 

// get all device history entries between now - 20 days and now - 10 days
balena.models.device.history.getAllByDevice(999999, { fromDate: subDays(new Date(), 20), toDate: subDays(new Date(), 10)})

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 

balena.models.device.history.getAllByApplication('myorganization/myapp').then(function(entries) {
    console.log(entries);
});

Example 

balena.models.device.history.getAllByApplication(999999).then(function(entries) {
    console.log(entries);
});

Example 

// get all device history entries between now - 20 days and now - 10 days
balena.models.device.history.getAllByApplication(999999, { fromDate: subDays(new Date(), 20), toDate: subDays(new Date(), 10)})

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 

dashboardDeviceUrl = balena.models.device.getDashboardUrl('a44b544b8cc24d11b036c659dfeaccd8')

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 

balena.models.device.getAllByApplication('myorganization/myapp').then(function(devices) {
    console.log(devices);
});

Example 

balena.models.device.getAllByApplication(123).then(function(devices) {
    console.log(devices);
});

Example 

balena.models.device.getAllByApplication('myorganization/myapp', { $select: ['overall_status', 'overall_progress'] }).then(function(device) {
    console.log(device);
})

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 

balena.models.device.getAllByOrganization('myorganization').then(function(devices) {
    console.log(devices);
});

Example 

balena.models.device.getAllByOrganization(123).then(function(devices) {
    console.log(devices);
});

Example 

balena.models.device.getAllByOrganization('myorganization', { $select: ['overall_status', 'overall_progress'] }).then(function(device) {
    console.log(device);
})

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 

balena.models.device.get('7cf02a6').then(function(device) {
    console.log(device);
})

Example 

balena.models.device.get(123).then(function(device) {
    console.log(device);
})

Example 

balena.models.device.get('7cf02a6', { $select: ['overall_status', 'overall_progress'] }).then(function(device) {
    console.log(device);
})

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 

balena.models.device.getWithServiceDetails('7cf02a6').then(function(device) {
    console.log(device);
})

Example 

balena.models.device.getWithServiceDetails(123).then(function(device) {
    console.log(device);
})

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 

balena.models.device.getByName('MyDevice').then(function(devices) {
    console.log(devices);
});

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 

balena.models.device.getName('7cf02a6').then(function(deviceName) {
    console.log(deviceName);
});

Example 

balena.models.device.getName(123).then(function(deviceName) {
    console.log(deviceName);
});

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 

balena.models.device.getApplicationName('7cf02a6').then(function(applicationName) {
    console.log(applicationName);
});

Example 

balena.models.device.getApplicationName(123).then(function(applicationName) {
    console.log(applicationName);
});

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 

balena.models.device.has('7cf02a6').then(function(hasDevice) {
    console.log(hasDevice);
});

Example 

balena.models.device.has(123).then(function(hasDevice) {
    console.log(hasDevice);
});

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 

balena.models.device.isOnline('7cf02a6').then(function(isOnline) {
    console.log('Is device online?', isOnline);
});

Example 

balena.models.device.isOnline(123).then(function(isOnline) {
    console.log('Is device online?', isOnline);
});

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 

balena.models.device.getLocalIPAddresses('7cf02a6').then(function(localIPAddresses) {
    localIPAddresses.forEach(function(localIP) {
        console.log(localIP);
    });
});

Example 

balena.models.device.getLocalIPAddresses(123).then(function(localIPAddresses) {
    localIPAddresses.forEach(function(localIP) {
        console.log(localIP);
    });
});

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 

balena.models.device.getMACAddresses('7cf02a6').then(function(macAddresses) {
    macAddresses.forEach(function(mac) {
        console.log(mac);
    });
});

Example 

balena.models.device.getMACAddresses(123).then(function(macAddresses) {
    macAddresses.forEach(function(mac) {
        console.log(mac);
    });
});

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 

balena.models.device.getMetrics('7cf02a6').then(function(deviceMetrics) {
    console.log(deviceMetrics);
});

Example 

balena.models.device.getMetrics(123).then(function(deviceMetrics) {
    console.log(deviceMetrics);
});

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 

balena.models.device.remove('7cf02a6');

Example 

balena.models.device.remove(123);

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 

balena.models.device.deactivate('7cf02a6');

Example 

balena.models.device.deactivate(123);

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 

balena.models.device.rename('7cf02a6', 'NewName');

Example 

balena.models.device.rename(123, 'NewName');

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 

balena.models.device.setNote('7cf02a6', 'My useful note');

Example 

balena.models.device.setNote(123, 'My useful note');

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 

balena.models.device.setCustomLocation('7cf02a6', { latitude: 123, longitude: 456 });

Example 

balena.models.device.setCustomLocation(123, { latitude: 123, longitude: 456 });

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 

balena.models.device.unsetCustomLocation('7cf02a6');

Example 

balena.models.device.unsetCustomLocation(123);

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 

balena.models.device.move('7cf02a6', 'myorganization/myapp');

Example 

balena.models.device.move(123, 'myorganization/myapp');

Example 

balena.models.device.move(123, 456);

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 

balena.models.device.getSupervisorTargetState('7cf02a6').then(function(state) {
    console.log(state);
});

Example 

balena.models.device.getSupervisorTargetState(123).then(function(state) {
    console.log(state);
});

Example 

balena.models.device.getSupervisorTargetState(123, 3).then(function(state) {
    console.log(state);
});

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 

balena.models.device.getSupervisorTargetStateForApp('7cf02a6').then(function(state) {
    console.log(state);
});

Example 

balena.models.device.getSupervisorTargetStateForApp(123).then(function(state) {
    console.log(state);
});

Example 

balena.models.device.getSupervisorTargetStateForApp(123, '7cf02a6').then(function(state) {
    console.log(state);
});

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 

randomKey = balena.models.device.generateUniqueKey();
// randomKey is a randomly generated key that can be used as either a uuid or an api key
console.log(randomKey);

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 

var uuid = balena.models.device.generateUniqueKey();
balena.models.device.register('myorganization/myapp', uuid).then(function(registrationInfo) {
    console.log(registrationInfo);
});

Example 

var uuid = balena.models.device.generateUniqueKey();
balena.models.device.register('myorganization/myapp', uuid, 'raspberry-pi').then(function(registrationInfo) {
    console.log(registrationInfo);
});

Example 

var uuid = balena.models.device.generateUniqueKey();
balena.models.device.register(123, uuid).then(function(registrationInfo) {
    console.log(registrationInfo);
});

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 

balena.models.device.generateDeviceKey('7cf02a6').then(function(deviceApiKey) {
    console.log(deviceApiKey);
});

Example 

balena.models.device.generateDeviceKey(123).then(function(deviceApiKey) {
    console.log(deviceApiKey);
});

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 

balena.models.device.hasDeviceUrl('7cf02a6').then(function(hasDeviceUrl) {
    if (hasDeviceUrl) {
        console.log('The device has device URL enabled');
    }
});

Example 

balena.models.device.hasDeviceUrl(123).then(function(hasDeviceUrl) {
    if (hasDeviceUrl) {
        console.log('The device has device URL enabled');
    }
});

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 

balena.models.device.getDeviceUrl('7cf02a6').then(function(url) {
    console.log(url);
});

Example 

balena.models.device.getDeviceUrl(123).then(function(url) {
    console.log(url);
});

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 

balena.models.device.enableDeviceUrl('7cf02a6');

Example 

balena.models.device.enableDeviceUrl(123);

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 

balena.models.device.disableDeviceUrl('7cf02a6');

Example 

balena.models.device.disableDeviceUrl(123);

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 

balena.models.device.enableLocalMode('7cf02a6');

Example 

balena.models.device.enableLocalMode(123);

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 

balena.models.device.disableLocalMode('7cf02a6');

Example 

balena.models.device.disableLocalMode(123);

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 

balena.models.device.isInLocalMode('7cf02a6').then(function(isInLocalMode) {
    if (isInLocalMode) {
        console.log('The device has local mode enabled');
    }
});

Example 

balena.models.device.isInLocalMode(123).then(function(isInLocalMode) {
    if (isInLocalMode) {
        console.log('The device has local mode enabled');
    }
});

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 

balena.models.device.get('7cf02a6').then(function(device) {
    balena.models.device.getLocalModeSupport(device);
})

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 

balena.models.device.enableLockOverride('7cf02a6');

Example 

balena.models.device.enableLockOverride(123);

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 

balena.models.device.disableLockOverride('7cf02a6');

Example 

balena.models.device.disableLockOverride(123);

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 

balena.models.device.hasLockOverride('7cf02a6');

Example 

balena.models.device.hasLockOverride(123);

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 

balena.models.device.getStatus('7cf02a6').then(function(status) {
    console.log(status);
});

Example 

balena.models.device.getStatus(123).then(function(status) {
    console.log(status);
});

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 

balena.models.device.getProgress('7cf02a6').then(function(progress) {
    console.log(progress);
});

Example 

balena.models.device.getProgress(123).then(function(progress) {
    console.log(progress);
});

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 

balena.models.device.grantSupportAccess('7cf02a6', Date.now() + 3600 * 1000);

Example 

balena.models.device.grantSupportAccess(123, Date.now() + 3600 * 1000);

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 

balena.models.device.revokeSupportAccess('7cf02a6');

Example 

balena.models.device.revokeSupportAccess(123);

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 

balena.models.device.get('7cf02a6').then(function(device) {
    balena.models.device.lastOnline(device);
})

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 

balena.models.device.get('7cf02a6').then(function(device) {
    console.log(device.os_version); // => 'balenaOS 2.26.0+rev1'
    console.log(device.os_variant); // => 'prod'
    balena.models.device.getOsVersion(device); // => '2.26.0+rev1.prod'
})

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 

balena.models.device.isTrackingApplicationRelease('7cf02a6').then(function(isEnabled) {
    console.log(isEnabled);
});

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 

balena.models.device.getTargetReleaseHash('7cf02a6').then(function(release) {
    console.log(release);
});

Example 

balena.models.device.getTargetReleaseHash('7cf02a6', function(release) {
    console.log(release);
});

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 

balena.models.device.pinToRelease('7cf02a6', 'f7caf4ff80114deeaefb7ab4447ad9c661c50847').then(function() {
    ...
});

Example 

balena.models.device.pinToRelease(123, 'f7caf4ff80114deeaefb7ab4447ad9c661c50847').then(function() {
    ...
});

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 

balena.models.device.trackApplicationRelease('7cf02a6').then(function() {
    ...
});

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 

balena.models.device.setSupervisorRelease('7cf02a6', '10.8.0').then(function() {
    ...
});

Example 

balena.models.device.setSupervisorRelease(123, '11.4.14').then(function() {
    ...
});

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. Default behaviour is runDetached=false but is DEPRECATED and will be removed in a future release. Use runDetached=true for more reliable updates.

Example 

balena.models.device.startOsUpdate('7cf02a687b74206f92cb455969cf8e98', '2.29.2+rev1.prod').then(function(status) {
    console.log(result.status);
});

device.getOsUpdateStatus(uuid) ⇒ Promise

Deprecated

Kind: static method of device
Summary: Get the OS update status of a device. This will no longer return a useful status for runDetached=true updates.
Access: public
Fulfil: Object - action response

Param Type Description
uuid String full device uuid

Example 

balena.models.device.getOsUpdateStatus('7cf02a687b74206f92cb455969cf8e98').then(function(status) {
    console.log(result.status);
});

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 

balena.models.device.ping('7cf02a6');

Example 

balena.models.device.ping(123);

device.getApplicationInfo(uuidOrId) ⇒ Promise

Deprecated

This is not supported on multicontainer devices, and will be removed in a future major release

Kind: static method of device
Summary: Get application container information
Access: public
Fulfil: Object - application info

Param Type Description
uuidOrId String | Number device uuid (string) or id (number)

Example 

balena.models.device.getApplicationInfo('7cf02a6').then(function(appInfo) {
    console.log(appInfo);
});

Example 

balena.models.device.getApplicationInfo(123).then(function(appInfo) {
    console.log(appInfo);
});

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 

balena.models.device.identify('7cf02a6');

Example 

balena.models.device.identify(123);

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 

balena.models.device.restartApplication('7cf02a6');

Example 

balena.models.device.restartApplication(123);

device.startApplication(uuidOrId) ⇒ Promise

Deprecated

This is not supported on multicontainer devices, and will be removed in a future major release

Kind: static method of device
Summary: Start application on device
Access: public
Fulfil: String - application container id

Param Type Description
uuidOrId String | Number device uuid (string) or id (number)

Example 

balena.models.device.startApplication('7cf02a6').then(function(containerId) {
    console.log(containerId);
});

Example 

balena.models.device.startApplication(123).then(function(containerId) {
    console.log(containerId);
});

device.stopApplication(uuidOrId) ⇒ Promise

Deprecated

This is not supported on multicontainer devices, and will be removed in a future major release

Kind: static method of device
Summary: Stop application on device
Access: public
Fulfil: String - application container id

Param Type Description
uuidOrId String | Number device uuid (string) or id (number)

Example 

balena.models.device.stopApplication('7cf02a6').then(function(containerId) {
    console.log(containerId);
});

Example 

balena.models.device.stopApplication(123).then(function(containerId) {
    console.log(containerId);
});

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 

balena.models.device.reboot('7cf02a6');

Example 

balena.models.device.reboot(123);

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 

balena.models.device.shutdown('7cf02a6');

Example 

balena.models.device.shutdown(123);

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 

balena.models.device.purge('7cf02a6');

Example 

balena.models.device.purge(123);

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 

balena.models.device.update('7cf02a6', {
    force: true
});

Example 

balena.models.device.update(123, {
    force: true
});

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 

balena.models.device.getSupervisorState('7cf02a6').then(function(state) {
    console.log(state);
});

Example 

balena.models.device.getSupervisorState(123).then(function(state) {
    console.log(state);
});

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 

balena.models.device.startService('7cf02a6', 123).then(function() {
    ...
});

Example 

balena.models.device.startService(1, 123).then(function() {
    ...
});

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 

balena.models.device.stopService('7cf02a6', 123).then(function() {
    ...
});

Example 

balena.models.device.stopService(1, 123).then(function() {
    ...
});

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 

balena.models.device.restartService('7cf02a6', 123).then(function() {
    ...
});

Example 

balena.models.device.restartService(1, 123).then(function() {
    ...
});

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 

balena.models.deviceType.get('raspberry-pi').then(function(deviceType) {
    console.log(deviceType);
});

Example 

balena.models.deviceType.get('raspberrypi').then(function(deviceType) {
    console.log('resolved alias:', deviceType);
});

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 

balena.models.deviceType.getAll().then(function(deviceTypes) {
    console.log(deviceTypes);
});

Example 

balena.models.deviceType.getAll({ $select: ['name', 'slug'] }).then(function(deviceTypes) {
    console.log(deviceTypes);
})

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 

balena.models.deviceType.getAllSupported().then(function(deviceTypes) {
    console.log(deviceTypes);
});

Example 

balena.models.deviceType.getAllSupported({ $select: ['name', 'slug'] }).then(function(deviceTypes) {
    console.log(deviceTypes);
})

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 

balena.models.deviceType.getBySlugOrName('raspberry-pi').then(function(deviceType) {
    console.log(deviceType);
});

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 

balena.models.deviceType.getName('raspberry-pi').then(function(deviceTypeName) {
    console.log(deviceTypeName);
    // Raspberry Pi
});

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 

balena.models.deviceType.getSlugByName('Raspberry Pi').then(function(deviceTypeSlug) {
    console.log(deviceTypeSlug);
    // raspberry-pi
});

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 

balena.models.deviceType.getInterpolatedPartials('raspberry-pi').then(function(contract) {
 for (const partial in contract.partials) {
     console.log(`${partial}: ${contract.partials[partial]}`);
 }
    // bootDevice: ["Connect power to the Raspberry Pi (v1 / Zero / Zero W)"]
});

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 

balena.models.deviceType.getInstructions('raspberry-pi').then(function(instructions) {
 for (let instruction of instructions.values()) {
     console.log(instruction);
 }
 // Insert the sdcard to the host machine.
 // Write the BalenaOS file you downloaded to the sdcard. We recommend using <a href="https://etcher.balena.io/">Etcher</a>.
 // Wait for writing of BalenaOS to complete.
 // Remove the sdcard from the host machine.
 // Insert the freshly flashed sdcard into the Raspberry Pi (v1 / Zero / Zero W).
 // Connect power to the Raspberry Pi (v1 / Zero / Zero W) to boot the device.
});

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 

balena.models.deviceType.getInstallMethod('raspberry-pi').then(function(method) {
    console.log(method);
 // externalBoot
});

models.apiKey : object

Kind: static namespace of models

apiKey.create(name, [description]) ⇒ 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
name String the API key name
[description] String the API key description

Example 

balena.models.apiKey.create(apiKeyName).then(function(apiKey) {
    console.log(apiKey);
});

Example 

balena.models.apiKey.create(apiKeyName, apiKeyDescription).then(function(apiKey) {
    console.log(apiKey);
});

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 

balena.models.apiKey.getAll().then(function(apiKeys) {
    console.log(apiKeys);
});

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 

balena.models.apiKey.getAllNamedUserApiKeys().then(function(apiKeys) {
    console.log(apiKeys);
});

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 

balena.models.apiKey.getProvisioningApiKeysByApplication('myorganization/myapp').then(function(apiKeys) {
    console.log(apiKeys);
});

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 

balena.models.apiKey.getDeviceApiKeysByDevice('7cf02a6').then(function(apiKeys) {
    console.log(apiKeys);
});

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 

balena.models.apiKey.update(123, { name: 'updatedName' });

Example 

balena.models.apiKey.update(123, { description: 'updated description' });

Example 

balena.models.apiKey.update(123, { expiryDate: '2022-04-29' });

Example 

balena.models.apiKey.update(123, { name: 'updatedName', description: 'updated description' });

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 

balena.models.apiKey.revoke(123);

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 

balena.models.key.getAll().then(function(keys) {
    console.log(keys);
});

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 

balena.models.key.get(51).then(function(key) {
    console.log(key);
});

key.remove(id) ⇒ Promise

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

Param Type Description
id Number key id

Example 

balena.models.key.remove(51);

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 

balena.models.key.create('Main', 'ssh-rsa AAAAB....').then(function(key) {
    console.log(key);
});

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 

balena.models.organization.membership.get(5).then(function(memberships) {
    console.log(memberships);
});

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 

balena.models.organization.membership.getAllByOrganization('MyOrg').then(function(memberships) {
    console.log(memberships);
});

Example 

balena.models.organization.membership.getAllByOrganization(123).then(function(memberships) {
    console.log(memberships);
});

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 

balena.models.organization.membership.getAllByUser('balena_os').then(function(memberships) {
    console.log(memberships);
});

Example 

balena.models.organization.membership.getAllByUser(123).then(function(memberships) {
    console.log(memberships);
});

membership.create(options) ⇒ Promise

use balena.models.organization.invite.create instead

This method adds a user to an organization by their usename. WARNING: This method is deprecated, use balena.models.organization.invite.create instead.

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

Param Type Default Description
options Object membership creation parameters
options.organization String | Number organization 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 

balena.models.organization.membership.create({ organization: "myorg", username: "user123", roleName: "member" }).then(function(membership) {
    console.log(membership);
});

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 

balena.models.organization.membership.changeRole(123, "member").then(function() {
    console.log('OK');
});

Example 

balena.models.organization.membership.changeRole({
    user: 123,
    is_member_of__organization: 125,
}, "member").then(function() {
    console.log('OK');
});

membership.remove(id) ⇒ Promise

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

Param Type Description
id Number organization membership id

Example 

balena.models.organization.membership.remove(123);

Example 

balena.models.organization.membership.remove({
    user: 123,
    is_member_of__application: 125,
});

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 

balena.models.organization.invite.getAll().then(function(invites) {
    console.log(invites);
});

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 

balena.models.organization.invite.getAllByOrganization('MyOrg').then(function(invites) {
    console.log(invites);
});

Example 

balena.models.organization.invite.getAllByOrganization(123).then(function(invites) {
    console.log(invites);
});

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 

balena.models.organization.invite.create('MyOrg', { invitee: "[email protected]", roleName: "developer", message: "join my org" }).then(function(invite) {
    console.log(invite);
});

invite.revoke(id) ⇒ Promise

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

Param Type Description
id Number organization invite id

Example 

balena.models.organization.invite.revoke(123);

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 

balena.models.organization.invite.accept("qwerty-invitation-token");

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 

balena.models.organization.create({ name:'MyOrganization' }).then(function(organization) {
    console.log(organization);
});

Example 

balena.models.organization.create({
  name:'MyOrganization',
  logo_image: new balena.utils.BalenaWebResourceFile(
    [fs.readFileSync('./img.jpeg')],
    'img.jpeg'
  );
})
.then(function(organization) {
  console.log(organization);
});

Example 

balena.models.organization.create({
  name:'MyOrganization',
  // Only in case File API is avaialable (most browsers and Node 20+)
  logo_image: new File(
    imageContent,
    'img.jpeg'
  );
})
.then(function(organization) {
  console.log(organization);
});

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 

balena.models.organization.getAll().then(function(organizations) {
    console.log(organizations);
});

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 

balena.models.organization.get('myorganization').then(function(organization) {
    console.log(organization);
});

Example 

balena.models.organization.get(123).then(function(organization) {
    console.log(organization);
});

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 

balena.models.organization.remove(123);

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 options to filter the OS releases by
[options.includeDraft] Boolean false Whether pre-releases should be included in the results

Example 

balena.models.os.getAvailableOsVersions('raspberrypi3');

Example 

balena.models.os.getAvailableOsVersions(['fincm3', 'raspberrypi3']);

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 

balena.models.os.getAllOsVersions('raspberrypi3');

Example 

balena.models.os.getAllOsVersions(['fincm3', 'raspberrypi3']);

Example 

balena.models.os.getAllOsVersions(['fincm3', 'raspberrypi3'], { $filter: { is_invalidated: false } });

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 

balena.models.os.getDownloadSize('raspberry-pi').then(function(size) {
    console.log('The OS download size for raspberry-pi', size);
});

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 semver-compatible range specification, in which case the most recent satisfying version is returned if it exists, or null is returned, * 'latest' in which case the most recent version is returned, including pre-releases, * 'recommended' in which case the recommended version is returned, i.e. the most recent version excluding pre-releases, which can be null if only pre-release versions are available, * 'default' in which case the recommended version is returned if available, or latest is returned otherwise. Defaults to 'latest'.
[osType] String can be one of 'default', 'esr' or null to include all types

Example 

balena.models.os.getMaxSatisfyingVersion('raspberry-pi', '^2.11.0').then(function(version) {
    console.log(version);
});

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

Kind: static method of os
Summary: Get the OS image last modified date
Access: public
Fulfil: Date - last modified date

Param Type Description
deviceType String device type slug
[version] String semver-compatible version or 'latest', defaults to 'latest'. Unsupported (unpublished) version will result in rejection. The version must be the exact version number. To resolve the semver-compatible range use balena.model.os.getMaxSatisfyingVersion.

Example 

balena.models.os.getLastModified('raspberry-pi').then(function(date) {
    console.log('The raspberry-pi image was last modified in ' + date);
});

balena.models.os.getLastModified('raspberrypi3', '2.0.0').then(function(date) {
    console.log('The raspberry-pi image was last modified in ' + date);
});

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 

balena.models.os.download({deviceType: 'raspberry-pi'}).then(function(stream) {
    stream.pipe(fs.createWriteStream('foo/bar/image.img'));
});

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 

balena.models.os.getConfig('myorganization/myapp', { version: '2.12.7+rev1.prod' }).then(function(config) {
    fs.writeFile('foo/bar/config.json', JSON.stringify(config));
});

balena.models.os.getConfig(123, { version: '2.12.7+rev1.prod' }).then(function(config) {
    fs.writeFile('foo/bar/config.json', JSON.stringify(config));
});

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 

balena.models.os.isSupportedOsUpgrade('raspberry-pi', '2.9.6+rev2.prod', '2.29.2+rev1.prod').then(function(isSupported) {
    console.log(isSupported);
});

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 

balena.models.os.getOsUpdateType('raspberry-pi', '2.9.6+rev2.prod', '2.29.2+rev1.prod').then(function(osUpdateType) {
    console.log(osUpdateType);
});

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 

balena.models.os.getSupportedOsUpdateVersions('raspberry-pi', '2.9.6+rev2.prod').then(function(isSupported) {
    console.log(isSupported);
});

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 

const result1 = balena.models.os.isArchitectureCompatibleWith('aarch64', 'armv7hf');
console.log(result1);

const result2 = balena.models.os.isArchitectureCompatibleWith('armv7hf', 'amd64');
console.log(result2);

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 

const results = balena.models.os.getSupervisorReleasesForCpuArchitecture('aarch64');

const [result] = balena.models.os.getSupervisorReleasesForCpuArchitecture(
    'aarch64',
    { $filter: { raw_version: '12.11.0' } },
);

const [result] = balena.models.os.getSupervisorReleasesForCpuArchitecture(
    'aarch64',
    {
            $select: ['id', 'raw_version', 'known_issue_list', 'created_at', 'contract'],
            $expand: {
                release_image: {
                    $select: 'id',
                    $expand: {
                        image: {
                            $select: 'is_stored_at__image_location',
                        },
                    },
                },
            },
        $filter: { raw_version: '12.11.0' }
    },
);

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 

balena.models.config.getAll().then(function(config) {
    console.log(config);
});

config.getDeviceTypes() ⇒ Promise

use balena.models.deviceType.getAll

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

balena.models.config.getDeviceTypes().then(function(deviceTypes) {
    console.log(deviceTypes);
});

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 

balena.models.config.getDeviceTypeManifestBySlug('raspberry-pi').then(function(manifest) {
    console.log(manifest);
});

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 

balena.models.config.getDeviceOptions('raspberry-pi').then(function(options) {
    console.log(options);
});

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 

balena.models.config.getConfigVarSchema('raspberry-pi').then(function(options) {
    console.log(options);
});

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 

balena.models.release.tags.getAllByApplication('myorganization/myapp').then(function(tags) {
    console.log(tags);
});

Example 

balena.models.release.tags.getAllByApplication(999999).then(function(tags) {
    console.log(tags);
});

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 

balena.models.release.tags.getAllByRelease(123).then(function(tags) {
    console.log(tags);
});

Example 

balena.models.release.tags.getAllByRelease('7cf02a6').then(function(tags) {
    console.log(tags);
});

Example 

balena.models.release.tags.getAllByRelease({application: 456, rawVersion: '0.0.0'}).then(function(tags) {
    console.log(tags);
});

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 

balena.models.release.tags.set(123, 'EDITOR', 'vim');

Example 

balena.models.release.tags.set('7cf02a6', 'EDITOR', 'vim');

Example 

balena.models.release.tags.set({application: 456, rawVersion: '0.0.0'}, 'EDITOR', 'vim');

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 

balena.models.release.tags.remove(123, 'EDITOR');

Example 

balena.models.release.tags.remove('7cf02a6', 'EDITOR');

Example 

balena.models.release.tags.remove({application: 456, rawVersion: '0.0.0'}, 'EDITOR');

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 

balena.models.release.get(123).then(function(release) {
    console.log(release);
});

Example 

balena.models.release.get('7cf02a6').then(function(release) {
    console.log(release);
});

Example 

balena.models.release.get({application: 456, raw_version: '0.0.0'}).then(function(release) {
    console.log(release);
});

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 

balena.models.release.getWithImageDetails(123).then(function(release) {
    console.log(release);
});

Example 

balena.models.release.getWithImageDetails('7cf02a6').then(function(release) {
    console.log(release);
});

Example 

balena.models.release.getWithImageDetails({application: 456, raw_version: '0.0.0'}).then(function(release) {
    console.log(release);
});

Example 

balena.models.release.getWithImageDetails(123, { image: { $select: 'build_log' } })
.then(function(release) {
    console.log(release.images[0].build_log);
});

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 

balena.models.release.getAllByApplication('myorganization/myapp').then(function(releases) {
    console.log(releases);
});

Example 

balena.models.release.getAllByApplication(123).then(function(releases) {
    console.log(releases);
});

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 

balena.models.release.getLatestByApplication('myorganization/myapp').then(function(releases) {
    console.log(releases);
});

Example 

balena.models.release.getLatestByApplication(123).then(function(releases) {
    console.log(releases);
});

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 

balena.models.release.createFromUrl('myorganization/myapp', { url: 'https://github.com/balena-io-projects/simple-server-node/archive/v1.0.0.tar.gz' }).then(function(releaseId) {
    console.log(releaseId);
});

Example 

balena.models.release.createFromUrl(123, { url: 'https://github.com/balena-io-projects/simple-server-node/archive/v1.0.0.tar.gz' }).then(function(releaseId) {
    console.log(releaseId);
});

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 

balena.models.release.finalize(123).then(function() {
    console.log('finalized!');
});

Example 

balena.models.release.finalize('7cf02a6').then(function() {
    console.log('finalized!');
});

Example 

balena.models.release.finalize({application: 456, raw_version: '0.0.0'}).then(function(release) {
    console.log('finalized!');
});

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 

balena.models.release.setIsInvalidated(123, true).then(function() {
    console.log('invalidated!');
});

Example 

balena.models.release.setIsInvalidated('7cf02a6', true).then(function() {
    console.log('invalidated!');
});

Example 

balena.models.release.setIsInvalidated({application: 456, raw_version: '0.0.0'}).then(function(release) {
    console.log('invalidated!);
});

Example 

balena.models.release.setIsInvalidated(123, false).then(function() {
    console.log('validated!');
});

Example 

balena.models.release.setIsInvalidated('7cf02a6', false).then(function() {
    console.log('validated!');
});

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 

balena.models.release.setNote('7cf02a6', 'My useful note');

Example 

balena.models.release.setNote(123, 'My useful note');

Example 

balena.models.release.setNote({ application: 456, rawVersion: '0.0.0' }, 'My useful note');

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 

balena.models.release.setKnownIssueList('7cf02a6', 'This is an issue');

Example 

balena.models.release.setKnownIssueList(123, 'This is an issue');

Example 

balena.models.release.setKnownIssueList({application: 456, rawVersion: '0.0.0'}, 'This is an issue');

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 

balena.models.service.var.getAllByService(999999).then(function(vars) {
    console.log(vars);
});

Example 

balena.models.service.var.getAllByService({ application: 'myorganization/myapp', service_name: 'myservice' }).then(function(vars) {
    console.log(vars);
});

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 

balena.models.service.var.getAllByApplication('myorganization/myapp').then(function(vars) {
    console.log(vars);
});

Example 

balena.models.service.var.getAllByApplication(999999).then(function(vars) {
    console.log(vars);
});

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 

balena.models.service.var.get(999999, 'VAR').then(function(value) {
    console.log(value);
});

Example 

balena.models.service.var.get({ application: 'myorganization/myapp', service_name: 'myservice' }, 'VAR').then(function(value) {
    console.log(value);
});

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 

balena.models.service.var.set(999999, 'VAR', 'newvalue').then(function() {
    ...
});

Example 

balena.models.service.var.set({ application: 'myorganization/myapp', service_name: 'myservice' }, 'VAR', 'newvalue').then(function() {
    ...
});

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 

balena.models.service.var.remove(999999, 'VAR').then(function() {
    ...
});

Example 

balena.models.service.var.remove({ application: 'myorganization/myapp', service_name: 'myservice' }, 'VAR').then(function() {
    ...
});

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 

balena.models.service.getAllByApplication('myorganization/myapp').then(function(services) {
    console.log(services);
});

Example 

balena.models.service.getAllByApplication(123).then(function(services) {
    console.log(services);
});

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 

balena.models.image.get(123).then(function(image) {
    console.log(image);
});

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 

balena.models.image.getLogs(123).then(function(logs) {
    console.log(logs);
});

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 

balena.models.creditBundle.getAllByOrg(orgId).then(function(creditBundles) {
    console.log(creditBundles);
});

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 

balena.models.creditBundle.create(orgId, featureId, creditsToPurchase).then(function(creditBundle) {
    console.log(creditBundle);
});

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 

balena.models.billing.getAccount(orgId).then(function(billingAccount) {
    console.log(billingAccount);
});

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 

balena.models.billing.getPlan(orgId).then(function(billingPlan) {
    console.log(billingPlan);
});

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 

balena.models.billing.getBillingInfo(orgId).then(function(billingInfo) {
    console.log(billingInfo);
});

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 

balena.models.billing.createSetupIntent(orgId).then(function(setupIntent) {
    console.log(setupIntent);
});

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 

balena.models.billing.updateBillingInfo(orgId, { token_id: 'xxxxxxx' }).then(function(billingInfo) {
    console.log(billingInfo);
});

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 

balena.models.billing.removeBillingInfo(orgId).then(function() {
    console.log("Success");
});

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 Partial.<Pick.<BillingAccountInfo, ('email'|'cc_emails')>> an object containing billing account info

Example 

balena.models.billing.updateAccountInfo(orgId, { email: '[email protected]' })

Example 

balena.models.billing.updateAccountInfo(orgId, { email: '[email protected]' })

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 

balena.models.billing.changePlan(orgId, { billingCode: 'prototype-v2', cycle: 'annual' }).then(function() {
    console.log('Plan changed!');
});

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 

balena.models.billing.getInvoices(orgId).then(function(invoices) {
    console.log(invoices);
});

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 

# Browser
balena.models.billing.downloadInvoice(orgId, '0000').then(function(blob) {
    console.log(blob);
});
# Node
balena.models.billing.downloadInvoice(orgId, '0000').then(function(stream) {
    stream.pipe(fs.createWriteStream('foo/bar/invoice-0000.pdf'));
});

balena.auth : object

Kind: static namespace of balena

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 

balena.auth.twoFactor.isEnabled().then(function(isEnabled) {
    if (isEnabled) {
        console.log('2FA is enabled for this account');
    }
});

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 

balena.auth.twoFactor.isPassed().then(function(isPassed) {
    if (isPassed) {
        console.log('2FA challenge passed');
    }
});

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 

const token = balena.auth.twoFactor.verify('1234');
balena.auth.loginWithToken(token);

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 

const setupKey = balena.auth.twoFactor.getSetupKey();
console.log(setupKey);

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 

const token = balena.auth.twoFactor.enable('1234');
balena.auth.loginWithToken(token);

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 

balena.auth.twoFactor.challenge('1234');

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 

const token = balena.auth.twoFactor.disable('1234');
balena.auth.loginWithToken(token);

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 

balena.auth.whoami().then(function(result) {
    if (!result) {
        console.log('I\'m not logged in!');
    } else {
        console.log('My result is:', result);
    }
});

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 

balena.auth.authenticate(credentials).then(function(token) {
    console.log('My token is:', token);
});

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 

balena.auth.login(credentials);

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 

balena.auth.loginWithToken(authToken);

auth.isLoggedIn() ⇒ Promise

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

balena.auth.isLoggedIn().then(function(isLoggedIn) {
    if (isLoggedIn) {
        console.log('I\'m in!');
    } else {
        console.log('Too bad!');
    }
});

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 

balena.auth.getToken().then(function(token) {
    console.log(token);
});

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 

balena.auth.getUserInfo().then(function(userInfo) {
    console.log(userInfo);
});

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 

balena.auth.getActorId().then(function(actorId) {
    console.log(actorId);
});

auth.logout() ⇒ Promise

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

balena.auth.logout();

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 

balena.auth.register({
    email: '[email protected]',
    password: 'secret'
}).then(function(token) {
    console.log(token);
});

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 

balena.auth.verifyEmail({
    email: '[email protected]',
    token: '5bb11d90eefb34a70318f06a43ef063f'
}).then(function(jwt) {
    console.log(jwt);
});

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 

balena.auth.requestVerificationEmail().then(function() {
    console.log('Requesting verification email operation complete!');
})

balena.logs : object

Kind: static namespace of balena

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')

Example 

balena.logs.subscribe('7cf02a6').then(function(logs) {
    logs.on('line', function(line) {
        console.log(line);
    });
});

Example 

balena.logs.subscribe(123).then(function(logs) {
    logs.on('line', function(line) {
        console.log(line);
    });
});

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')

Example 

balena.logs.history('7cf02a6').then(function(lines) {
    lines.forEach(function(line) {
        console.log(line);
    });
});

Example 

balena.logs.history(123).then(function(lines) {
    lines.forEach(function(line) {
        console.log(line);
    });
});

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 

logs.unsubscribe();

"line"

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

logs.on('line', function(line) {
    console.log(line);
});

"error"

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

logs.on('error', function(error) {
    console.error(error);
});

balena.settings : object

Kind: static namespace of balena

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 

balena.settings.get('apiUrl').then(function(apiUrl) {
    console.log(apiUrl);
});

settings.getAll() ⇒ Promise

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

balena.settings.getAll().then(function(settings) {
    console.log(settings);
});

balena.utils : object

Kind: static namespace of balena

listImagesFromTargetState(targetState) ⇒

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

Param
targetState