HomeyAPI

An authenticated Homey API. Do not construct this class manually.

Classes

Static Properties

DISCOVERY_STRATEGIES

(static) DISCOVERY_STRATEGIES

Discovery Strategies

Properties

Name Type Description
DISCOVERY_STRATEGIES 		object
CLOUD 		string

Cloud HTTPS, e.g. https://abcdef.connect.athom.com.
MDNS 		string

Local HTTP, e.g. http://homey-abcdef.local
LOCAL 		string

Local HTTP, e.g. http://192.168.1.100.
LOCAL_SECURE 		string

Local HTTPS, e.g. https://192-168-1-100.homey.homeylocal.com.
REMOTE_FORWARDED 		string

Remote HTTPS, e.g. https://12-34-56-78.homey.homeylocal.com:12345.
}

PLATFORMS

(static) PLATFORMS

Platforms

Properties

Name Type Description
PLATFORMS 		object
LOCAL 		string

Homey (2016 — 2019) & Homey Pro (2019 — 2023)
CLOUD 		string

Homey Cloud
}

Static Methods

createAppAPI

(async, static) createAppAPI(opts)

Creates a HomeyAPIV3Local or HomeyAPIV2 instance for use in the Apps SDK.

Parameters

Name Type Description
opts 		Object
homey 		Homey

— Homey (Apps SDK) instance.
debug 		function | null <optional>
default:null

— Debug function, defaults to null.
}

Example

const { HomeyAPI } = require('homey-api');

module.exports = class MyApp extends Homey.App {

  async onInit() {
    // Create a HomeyAPI instance. Ensure your app has the `homey:manager:api` permission.
    this.homeyApi = await HomeyAPI.createAppAPI({
      homey: this.homey,
    });

    // Get all the devices, and log their names.
    const devices = await this.homeyApi.devices.getDevices();
    for(const device of Object.values(devices)) {
      this.log(device.name);
    }
  }

}

createLocalAPI

(async, static) createLocalAPI(opts)

Creates a HomeyAPIV3Local instance for use in a project.

Parameters

Name Type Description
opts 		Object
address 		String

— The address of the Homey, e.g. http://192.168.1.123:80.
token 		String

— A Personal Access Token created in the Homey Web App.
debug 		function | null

— Debug function, defaults to null.
}

Example

import { HomeyAPI } from 'homey-api';
const homeyApi = await HomeyAPI.createLocalAPI({
  address: 'http://192.169.1.123',
  token: '<my_personal_access_token>',
});
const devices = await homeyApi.devices.getDevices();

Instance Methods

__

__(input): string|null

Translates an i18n-object (e.g. { en: 'My String', nl: 'Mijn tekst' } to a string. Uses the language of Homey as defined in Homey.

Parameters

Name Type Description
input 		object
en 		string

English translation
nl 		string

Dutch translation
}

Returns

  • The translated string, or null
string | null

Example

homeyApi.__({
  en: 'Hello',
  nl: 'Hallo',
  fr: 'Bonjour',
}); // returns "Hello" if Homey is set to English

hasRole

hasRole(roleId)

Check the current role.

Parameters

Name Type Description
roleId 		string

The role ID, e.g. owner, manager, user or guest.