Welcome to the Web API documentation 👋

🌍 Learn how to build great integrations for Homey Pro & Homey Cloud.

The Homey Web API is a HTTP + Socket.IO API to control Devices, start Flows, view Insights and more. It is used by Athom internally for the Homey Mobile App, Homey Web App, Alexa, Google Assistant, and is available to 3rd party developers to create their own integrations.

As opposed to the apps running on Homey Pro or Homey Cloud, using the Homey Apps SDK, integrating with the Homey Web API requires your own server or front-end.

The Web API can also used from within a HomeyScript. Learn more »

Homey Pro apps with the homey:manager:api permission can also use some endpoints from within their app. Learn more »

Creating a Web API Client

Before you can get started, you need to create your own Web API Client, to receive your Client ID & Secret.

Customers must authenticate using OAuth2 with your application, before you can make API calls on their behalf.

Create your own API Client in the Homey Developer Tools.

New API Clients are limited to a maximum of 100 Homey Pro users. To remove this limit, and optionally connect to Homey Cloud, click the Request Limit Increase link in the Developer Tools. We will try to handle your request as soon as possible.

Example

We provide a JavaScript & Node.js library, node-homey-api, to take care of the heavy lifting by authenticating & connecting to a customer's Homey Pro or Homey Cloud.

If you're not developing within a JavaScript environment, please visit HTTP Specification.

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.