With our URL Scheme, you can create links to content in Controller for HomeKit. It's also possible to execute Scenes and Workflows with a link.

Quick Start

After installing Controller for HomeKit on a device, all links starting with controllerforhomekit:// will open the app.

You can open specific screens from the main menu like this:

controllerforhomekit://v1/cameras
controllerforhomekit://v1/accessories
controllerforhomekit://v1/scenes

By default, all links refer to the currently selected Home in Controller. However, you can append a URL parameter 'home' to open a specific Home:

controllerforhomekit://v1/scenes?home=Example%20Home

You can open specific detail views, like one particular Scene, by appending its name and including a Home name:

controllerforhomekit://v1/cameras/Example%20Camera?home=Example%20Home

You can open a view with a Smart Folder pre-selected by using the URL parameter 'folder':

controllerforhomekit://v1/scenes?home=Example%20Home&folder=My%20Lights

For Scenes and Workflows, you can use the parameter 'action' to make the app execute them.

controllerforhomekit://v1/scenes/Example%20Scene?home=Example%20Home&action=execute

Tip: When you create a Widget in Controller for HomeKit, you can touch and hold an action to copy the URL it uses to the clipboard.

URL Pattern

The general pattern for links to Controller looks like this:

controllerforhomekit://<api-version>/<view>/<target>?home=<home>&folder=<folder>?action=<action>

API Version

Currently, the only valid value for api-version is 'v1'.

View

The view parameter allows you to specify the views you can access from the app's main menu and zones. Valid values are:

cameras, accessories, scenes, automations, workflows, rooms, zones, backups, logs, maintenance, serviceGroups, widgets, watchScreens, nfcTags, settings

Target

The target parameter lets you specify a particular detail view in one of the main views. E.g., a specific Scene. You can set a target for the following views:

cameras, accessories, scenes, automations, workflows, rooms, zones, widgets

The value for the target is the name of the object you want to open. If the name contains a space or special characters, you need to percent-encode them. See Special Characters.

When you specify a target, you always need to provide a home.

To open the workflow "Check Windows" in the Home "My Home" the URL needs to look like this:

controllerforhomekit://v1/workflows/Check%20Windows?home=My%20Home

Home

The home parameter is optional, but it becomes mandatory when a target or folder is specified. It defines what Home Controller will select. If you provide no Home, the currently selected Home remains selected.

You need to percent-encode spaces and special characters in the Home name. See Special Characters.

Folder

The folder parameter lets you open a main view with a selected Smart Folder. You can specify a folder for the following views:

accessories, scenes, automations, logs

You need to percent-encode spaces and special characters in the folder name. See Special Characters.

When you specify a folder, you always need to provide a home.

To open the Smart Folder "Motion Sensors" in the Home "My Home" the URL needs to look like this:

controllerforhomekit://v1/accessories?home=My%20Home&folder=Motion%20Sensors

Action

The action parameter allows you to tell Controller for HomKit what action the URL should trigger. The app will open the URL target if no action is specified.

There are currently two options supported:

open, execute

The action execute can only be used if the target parameter is a Scene or a Workflow. It will apply the Scene or run the Workflow immediately instead of opening its detail view.

Special Characters

URLs cannot contain spaces or special characters like exclamation marks, question marks, or ampersands. If your target, folder, or Home includes a special character, you must percent-encode it.

For example, you must replace each space with %20. That means if you want to open a Scene 'Late Night' in your Home 'My Home', the URL needs to look like this:

controllerforhomekit://v1/scenes/Late%20Night?home=My%20Home

You can learn more about percent-encoding and the codes for different characters here: https://www.w3schools.com/tags/ref_urlencode.ASP