Homey Web API
๐Ÿ“– Web API Reference๐Ÿš€ Apps SDK๐Ÿ›  Developer Tools
  • Welcome to the Web API documentation ๐Ÿ‘‹
Powered by GitBook
On this page
  • Creating a Web API Client
  • Example
  • ๐Ÿ‘ฅ Community

Was this helpful?

Welcome to the Web API documentation ๐Ÿ‘‹

๐ŸŒ Learn how to build great integrations.

Last updated 4 days ago

Was this helpful?

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 , , , , 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 , integrating with the Homey Web API requires your own server or front-end.

The Web API can also used from within a HomeyScript.

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

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 .

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, , to take care of the heavy lifting by authenticating & connecting to a customer's Homey Pro or Homey Cloud.

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 with the homey tag.

Please report any issues you find in the .

Homey Mobile App
Homey Web App
Alexa
Google Assistant
Homey Apps SDK
Learn more ยป
Learn more ยป
Homey Developer Tools
node-homey-api
Stack Overflow
Web API Issue Tracker