Homey RESTApps API

Introduction

This API is written for apps that run on Homey. They are their own Node.js processes, and communicate to the Homey core using the methods documented here.


{{::section.name}}

Homey.{{::section.type}}( '{{::item.name}}' )

The {{::item.name}} {{::section.type}} has no methods or events.

methods

// {{::method.desc}}
// returns: {{::method.returns.type}} ({{::method.returns.desc}})

homey:{{section.type}}:{{item.name}}

.{{::method.name}}(
{{::arg.type}} {{::arg.name}} {{::arg.name}}(  // {{::arg.desc}}
{{::arg_.type}} {{::arg_.name}} ,  // {{::arg_.desc}}

)  // {{::arg.desc}}
{{::arg.name}}
,  // {{::arg.desc}}

)

events

// {{::event.desc}}

homey:{{section.type}}:{{item.name}}

.on( '', function(
{{::arg.type}} {{::arg.name}}(  // {{::arg.desc}}
{{::arg_.type}} {{::arg_.name}} ,  // {{::arg_.desc}}

)
{{::arg.name}}
,  // {{::arg.desc}}

) )

Introduction

Warning: this API documentation is outdated! It will be updated soon.

With the REST API, you can interact with Homey from outside the ecosystem by making HTTP requests.

Usage

URL
The base url of the API is your Homey's url on port 80, followed by /api/. For example http://homey.local/api/.

Encoding
All requests and results are JSON encoded, so set the correct header:

Content-Type: application/json

Authorization
All endpoints require authorization. Set the following header to authorize yourself:

Authorization: Bearer youruniquetoken

Obtaining your authorization token
In Homey, go to Settings → Developer → API Keys to generate an API key.

Permissions
Some endpoints require specific permissions. Your API key can been granted these permissions. Without the correct permissions, you will receive an 403 Unauthorized.

Example

Make Homey speak Hello world:

POST /api/managers/speech-output/ HTTP/1.1
Authorization: Bearer 3d80d516-82b9-4587-8140-4fefb383fec8
Content-Type: application/json
Host: homey.local:8000
Connection: close
Content-Length: 26

{
	"text": "Hello world"
}

{{::section.name}}

{{::section.desc}}

{{::item.path}}

{{::item.desc}}
{{::endpoint.method}}
/{{::section.path}}/{{::item.path}}{{::endpoint.path}}

{{::endpoint.description}}

permissions

{{::permission}}

input

params

query

body

output