Design partners wanted for a verified spatial-policy layer

Developers
1

I am building Spatial OS, a platform-neutral layer that separates natural-language intent from physical device execution through a spatial graph, typed actions, shadow simulation, explicit approval and post-action verification.

Home Assistant is the only live connector today. There is no Homey app or compatibility claim yet.

Before writing a Homey adapter, I would value feedback from Homey developers:

  • Is Homey Web API the right boundary for reading devices, issuing commands and verifying observed state?
  • Which Flow or device actions should always require explicit approval?
  • Would a separate preview and evidence layer be useful, or would it add too much ceremony to the Homey experience?
  • Should this be an App SDK integration, an external service, or both?

Architecture and virtual-home demo:

I am looking for two design partners before writing the adapter. Blunt technical criticism is welcome.

  • Spatial OS Team
2

Yes. You can use it to receive real-time state updates and control devices, start Flows, etc. Note that not all Homey features are available in the API. The API works via OAuth, so it should be easy to integrate into your website/app.

Web API clients can’t perform any destructive actions like deleting devices or Flows, and they also can’t edit them. So there’s not much risk.

Remote access is easier using an external service, and it’s supported on Homey Cloud as well.

3

Thank you — this is exactly the boundary clarification I needed. I’ll treat Homey as an external OAuth/Web API adapter, use real-time state updates for post-action verification, and keep unsupported or destructive operations explicitly out of scope rather than adding redundant approval steps.

The remaining question I want to validate is which non-destructive commands still benefit from preview and evidence, for example locks, alarm modes, or high-impact Flows. If you are open to it, I would be glad to share a short read-only adapter specification for technical review before implementation.

4

Homey has a locked-down Web API, so you can’t run any destructive actions even if you wanted to. Currently possible:

  • Read zones
  • Read devices
  • Read Flows
  • Read Moods
  • Read user info
  • Read user presence
  • Read Insights
  • Read apps
  • Read Timeline notifications
  • Read Energy info
  • Control devices
  • Set Moods
  • Start Flows
  • Set current user presence
  • Read and write Logic variables

You can’t change any settings, create or delete Flows, etc.

5

To get started with an API integration, create a Web API client here:

There are API docs:

And an API reference:

Note that not all functions listed in the reference are available, since Homey has secured their API to only allow the scopes I listed above.

6

Thank you, this is exactly the boundary clarification I needed. I will prototype the Homey adapter as an external OAuth service, using Web API for real-time state, device commands, and Flow starts, while avoiding claims around features the API does not expose.

Your note about destructive and editing operations also sharpens the policy model: explicit approval can focus on consequential physical actions, such as locks, heating, access, and multi-device Flows, rather than platform administration.

When the read-only connection plus preview and post-action verification loop is ready, would you be open to testing it against a real Homey setup? It will use OAuth only; no credentials would be shared.

7

It’s not entirely read-only, you can still control the devices of course. But you can’t create devices or Flows, or edit/delete them.

Yes, of course!

8

Thank you — confirmed. I will treat this as constrained control access rather than a read-only connection.

The first real-home test will cover four steps only: OAuth discovery, action preview, one explicitly approved device or Flow command, and observed-state verification. I will send you a private test link when that end-to-end loop is ready.

For privacy and security, please do not share credentials, private Homey URLs, exports, or household data in the forum. The connection will use scoped OAuth and a disconnect/revoke path.

Your API boundary guidance has already materially improved the adapter design. Thank you for volunteering a real setup.

9

@smarthomesven — the short mobile preview I promised is now available:

To be precise, this validates the approval and observed-state verification UX; it does not connect to Homey yet. The Homey OAuth adapter remains the next implementation step.

The single decision that would help most is: should the first Homey prototype validate a direct device command or a Flow start, and what real example would you choose? No credentials, private URLs, exports or household data are needed for this preview.

10

I’m not sure what I’m meant to do here, I get linked to a feedback form and don’t see anything else. Is this a bug?

I don’t think that’s possible with Homey to reliably detect that a command got received correctly. It highly depends on how the app developer implemented the capability changes.

In some cases, the capability listener throws when an error occurs (e.g. HTTP request to the device failed). When this happens, the error will get returned. But the error can also get catched by a catch block that only logs the error and then does nothing, which means it looks like the capability change got accepted, until the next poll or change where the app changes it back.

Also, for example a WebSocket-based connection where the Homey app sends a message to the manufacturer’s server, that will always return correctly when the message got sent. But that doesn’t mean that the device itself is online, it can just fail a few seconds later and then the app changes it back to the previous state.

Devices can also be marked is offline with setUnavailable(), optionally with a custom (translated) message that will show in the Homey mobile app and Web App. These are also readable from the Homey API.

image
image1085×927 90.2 KB

Response from API:
image
image712×897 26.8 KB

You can see available is set to false, and there is also the custom message.

In my own apps, I usually mark the device as unavailable if it’s reported as offline on the manufacturer’s server, or if the app can’t connect to the manufacturer’s server. Often with a custom message like “The (manufacturer name) server is unreachable, please check your internet connection.” or when the device itself is offline “The device is unreachable. Is it powered up and connected to the internet?”. But not all app developers do this, there are also many apps that don’t mark devices as unavailable, it’s not a requirement to publish to the Homey App Store at least.

So there are many ways that something can fail, sometimes even silently. However, there is 1 way to determine when an action failed later on: with the homey.insights.readonly scope, you can get the logs for the device.

image
image793×596 85.3 KB

(the many Turned on/off in this case were just tests with the app since I was developing the app)

And that contains the sources as well, it can be the mobile app, web app, a Flow or Google/Alexa, which also show the user who controlled the device. There is also the Homey app, in that case the Homey app that the device is connected through switched the device, this usually happens when an action got triggered from an external source (using the manufacturer’s own mobile app or physically on the device using a button, etc.). If the device gets switched back off by the Homey app shortly after turning it on, it’s probably because the request failed. But this does not work for all actions (dimming, setting color, setting temperature, etc. are not logged there).

Also, Flow starts can’t be verified, those don’t return any errors when you start them the regular way. You can also run it in “test” mode, there you can see everything, but for Advanced Flows this deliberately slows down the Flow since it’s meant to show in the web editor where you can then “follow” the Flow. And I don’t think that’s available in the homey.flow.start scope either.

11

You are right — linking you to the beta form as a “mobile preview” was a mistake. It is a feedback form, not a usable preview, and I should not have described it otherwise.

Your verification details are extremely useful. Capability acceptance is not physical-state confirmation; availability and Insights can provide partial evidence, while generic Flow starts cannot be reliably verified. That means an initial Homey adapter should stay read-only or shadow-only, and only claim verification for device classes where a post-command observation is actually available.

I will not ask you to test anything else until there is a real Homey-specific workflow to inspect. Thank you for the concrete examples.