# Welcome to the Web API documentation 👋

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](https://get.homey.app), [Homey Web App](https://my.homey.app), [Alexa](https://www.amazon.com/Athom-B-V-Homey/dp/B078RQSFKB), [Google Assistant](https://assistant.google.com/services/a/uid/000000ff72e71f6d), 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](https://apps.developer.homey.app/), 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 »](https://homey.app/a/com.athom.homeyscript)

Homey Pro apps with the `homey:manager:api` permission can also use some endpoints from within their app. [Learn more »](https://athombv.github.io/node-homey-api/HomeyAPI.html#.createAppAPI)

### 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.

{% hint style="success" %}
Create your own API Client in the [Homey Developer Tools](https://tools.developer.homey.app/api/clients).
{% endhint %}

{% hint style="warning" %}
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.
{% endhint %}

### Example

We provide a JavaScript & Node.js library, [node-homey-api](https://www.npmjs.com/package/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](https://api.developer.homey.app/http-and-socket.io/http-specification). 

```javascript
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](https://stackoverflow.com/questions/ask?tags=homey) with the `homey` tag.
* Please report any issues you find in the [Web API Issue Tracker](https://github.com/athombv/homey-web-api-issues/issues).