Exposing API on my Homey for custom GPTs

I’m a developer, but I haven’t developed for the Homey before. I have started diving into the app and Web API documentation, but I’m having some difficulties grasping these concepts. I see there is a web API, and that an app can implement custom routes.

Do apps expose the full API? Or is that only web API? I’ve set up my local test app, and given it permissions homey:manager:api. If that exposes the full API, it seems that that should kind of be all my app would need.

My idea is to allow my Homey to be controlled by custom GPTs. It would be fine to publish an app anyone who wants to allow GPTs to control their home. The GPT must also be fed with the API calls it can use, but that seems managable.

I did find that I can create API keys outside of apps, and I’ve found a URL that can be accessed outside of my local network, but that’s only good for when I’m creating my own GPTs, since I have to use that API key and URL to my homey. My assumption is that I should use the Web API, but given that the local development values won’t work to integrate outside my network, that I’d need a key. But the Web API form asks for the callback url for OAuth, and that will be dynamic for each GPT.

Do these assumption seem correct? Does anyone see a way to do this in a generic way, where you can allow access to your Homey via OAuth with the custom GPT? Or any other way to do it?

I’m not sure if you are confusing the web API with the Homey API (or maybe it is me misunderstanding).
You can create endpoints in your app and decide if they are public or private. If you set them to public then anything can access them, whereas private endpoints can only be accessed by your app, such as an app settings page.

The webAPI on the other hand requires an access token to connect and then can control your entire Homey.

In the SDK documentation, this is called “Web API”:

And this is also called “Web API”:

So I can understand the confusion (especially since you can also use the latter inside apps).

1 Like

Yup. I have to say it is extremely hard as an uninitiated Homey developer to understand the differentiation. That’s why I was wondering if an apps API would extend the web API, but I then understand it that an app will only expose its own endpoints. That’s fair and fine, the call to get all devices returns a list so long I don’t know if any current AI has a context window big enough to handle it. So it seems an app with calls to return a lighter response would be approrpriate anyway.

So let’s just assume an App that gives responses for a GPT, it seems everything could be set? So long as my app can be authorized to via OAuth2? Where do you get clientSecret, clientID etc, for the app? Or am I not thinking correctly here?

Am I thinking correctly with the URL here? https://api.athom.com/api/app/<your_app_id>/?

Asumming you use the Web Api where an app exposes endpoints, the URI you specified is correct and it can be followed by anything you decide to define in your app.
You first create the api.js file in the root of your app which has the endpoint handlers and then define them in the app.json to expose them.
So if you create a handler to return a list of devices in the api.js file and call it getDevices then the URI will be https://api.athom.com/api/app/<your_app_id>/getDevices.
If you want to see an example my Button + app does just that (available on GitHub AdyRock account)

1 Like