Welcome to the Web API documentation 👋

🌍 Learn how to build great integrations.

The Homey Web API is a HTTP + Socket.IO API to control devices, manage Flows etc. It is used by Athom for the Homey Mobile App, Homey Web App, Alexa, Google Assistant etc.

The Web API is also used by HomeyScript and apps using the homey:manager:api permission. Learn more »

Please fill out this form to request your own Web API Client ID & Secret.

Local Development

Until you have your own Client ID & Secret, you can use these credentials to test your project locally.

Key	Value
Client ID	5a8d4ca6eb9f7a2c9d6ccf6d
Client Secret	e3ace394af9f615857ceaa61b053f966ddcfb12a
Callback URL	http://localhost, http://localhost/oauth2/callback
Scopes	homey

It is not allowed to use these credentials for commercial or non-development purposes.

Example

const AthomCloudAPI = require('homey-api/lib/AthomCloudAPI');

// Create a Cloud API instance
const cloudApi = new AthomCloudAPI({
  clientId: '...',
  clientSecret: '...',
});

// Get the logged in user
const user = await cloudApi.getAuthenticatedUser();

// Get the first Homey of the logged in user
const homey = await user.getFirstHomey();

// Create a session on this Homey
const homeyApi = await homey.authenticate();

// Loop all devices
const devices = await homeyApi.devices.getDevices();
for(const device of Object.values(devices)) {
  // Turn device on
  await device.setCapabilityValue({ capabilityId: 'onoff', value: true }); 
}

// Connect to receive realtime events
await homeyApi.devices.connect();
homeyApi.devices.on("device.delete", (device) => {
  // Device deleted
});
homeyApi.devices.on("device.update", (device) => {
  // Device updated
});
homeyApi.devices.on("device.create", (device) => {
  // Device created
});

👥 Community

• Questions? Ask them on Stack Overflow with the homey tag.

• Please report any issues you find in the Web API Issue Tracker.