HTTP API Command List

HTTP API Overview

The HTTP API is only available for the Primary Controller

The API allows for “headless” control of the primary controller via simple HTTP requests. It’s essentially a remote control that lives in your browser’s address bar or your favorite automation script. Unlike MQTT, the API does not require third-party intermediaries (like a broker) or complex configuration. Commands are issued as standard URLs:

http://[your-controller-ip]/api?...

⚠️ Assign a Static or Reserved IP Address to the Controller
As covered in the Onboarding topic, it is recommended that you assign a static or reserved IP address to the primary controller. Otherwise, if you create HTTP API calls in a third-party system (such as Home Assistant) and the controller’s IP address changes, these automations will break and require an updating of the automation to use the new IP.

Even though the method to send commands is different, the HTTP API has many of the same caveats and restrictions as using a similar MQTT command. Some of those limitations are listed here, but a review of the MQTT commands may be helpful even if you aren’t planning on using MQTT.

💡 Additional Notes on Using the HTTP API
- Unless otherwise noted, all settings changes are only applied to the ACTIVE system settings and will be lost upon a controller restart.

- Commands sent to non-defined hardware are discarded (e.g. sending a ToF command when PIR sensors are defined in the hardware settings or sending a command for Sensor2 when only one sensor has been configured.)

Command Types

The HTTP API consists of two different types of commands:

SET Commands: These ‘set’ a value or paremter on the system. They return a simple “OK” to the browser if the command is valid and accepted. Otherwise, they return a invalid command or error message.
GET Commands: These do not modify the system, but simply return data from the system back to the calling routine or browser. All GET commands must be issued separately.

Command Chaining (SET Commands)

Some SET commands can be combined into a single HTTP call by concatenating them with an ampersand (&).

Example: http://[primary-ip-address]/api?ledbrightness=120&ledcolor=ff0000

Other commands must be sent as the only command in the URL.

SET Commands

These commands, unless otherwise noted, are used to modify the ACTIVE state of the system. Commands marked NO in the “Multi” column must be sent as standalone requests and cannot be combined with other commands.

Command	Parameter(s)	Returns	Multi	Example / Notes
`sensor1state`	ON (or true/1)	OK	NO	`/api?sensor1state=ON` Send an ON trigger for Sensor1. See notes below
`sensor2state`	ON (or true/1)	OK	NO	`/api?sensor2state=ON` Send an ON trigger for Sensor2. See notes below
`sensoroverride`	ON or OFF	OK	Yes	`/api?sensoroverride=ON` Overrides the sensors for manual LED control. Set to OFF to return system to normal operation. See notes below
`ledbrightness`	number (0-255)	OK	Yes	`/api?ledbrightness=96` Sets the master brightness for the LED strip(s).
`sensor1toggle`	ON or OFF	OK	Yes	`/api?sensor1toggle=ON` Sets the Toggle OFF setting for Sensor1.
`sensor2toggle`	ON or OFF	OK	Yes	`/api?sensor2toggle=ON` Sets the Toggle OFF setting for Sensor2.
`sensor1dist`	number (50-1200)	OK	Yes	`/api?ledbrightness=96` Sets the master brightness for the LED strip(s).
`effect1`	Effect Name	OK	Yes	`/api?effect1=CrissCross` Sets the LED effect used by Sensor1. Must specify a predefined effect name.
`effect1speed`	number (1-10)	OK	Yes	`/api?effect1speed=5` Sets the speed for Effect1. Ignored if effect does not implement speed (e.g. Solid effect)
`effect1color1`	RGB or Hex	OK	Yes	`/api?effect1color1=ff00ff` or `?effectc1color1=255,0,255` Sets the primary color for Effect1.
`effect1color2`	RGB or Hex	OK	Yes	`/api?effect1color2=0000ff` or `?effect1color2=0,0,255` Sets the secondary color for Effect1. Ignored if effect only uses one color.
`effect2`	Effect Name	OK	Yes	`/api?effect2=Segments` Sets the LED effect used by Sensor2. Must specify a predefined effect name.
`effect2speed`	number (1-10)	OK	Yes	`/api?effect2speed=8` Sets the speed for Effect2. Ignored if effect does not implement speed
`effect2color1`	RGB or Hex	OK	Yes	`/api?effect2color1=00ff00` or `?effectc1color1=0,255,0` Sets the primary color for Effect1.
`effect2color2`	RGB or Hex	OK	Yes	`/api?effect2color2=ff0000` or `?effectc1color1=255,0,0` Sets the secondary color for Effect2. Ignored if effect only uses one color.
`ledstate`*	ON or OFF	OK	Yes	`/api?ledstate=ON` Turns the LEDs on or off.
`ledeffect`*	Effect Name	OK	Yes	`/api?effect1=CrissCross` Sets the LED effect used by Sensor1. Must specify a predefined effect name.
`ledspeed`*	number (1-10)	OK	Yes	`/api?ledspeed=5` Sets the speed for `ledeffect`. Ignored if effect does not implement speed (e.g. Solid effect)
`ledcolor`*	RGB or Hex	OK	Yes	`/api?ledcolor=ff00ff` or `?ledcolor=255,0,255` Sets the primary color for `ledeffect` when manually controlling the LEDs.
`ledcolor2`*	RGB or Hex	OK	Yes	`/api?ledcolor2=ff0000` or `?ledcolor2=255,0,0` Sets the secondary color for `ledeffect`. Ignored if effect only uses one color.

Commands marked with (*) are used when manually controlling the LEDs. These are independent of the same settings for Sensor1 and Sensor2 and are only used when sensoroverride = ON and the parameters are updated via API (or MQTT).

Manually Controlling the LEDs

If you are attempting to manually control the LEDs or certain other features, you should first enable the sensor override feature via the ?sensoroverride=ON command. Otherwise, the normal sensor processing may immediately be overwritten by the sensor states. For example, if you attempt to manually turn the LEDs on via the API when the sensors are still active, the LEDs will immediately turn off again. Just be sure to disable the sensor override, ?sensoroveride=OFF, when you want to return the system to normal operation.

LED Behavior During Manual Control

If the LEDs are on, then sending any changes to effect, colors or speed will ‘redraw’ the LEDs using the new properties. If the LEDs are off, then the active settings are changed and will be used the next time the LEDs are manaully toggled on. For example, say the current manual parameters are as following:

ledeffect: CrissCross
ledcolor: 255,0,0 (Red)
ledcolor2: 0,0,255 (Blue)

Now an API command is sent to change the colors:

If LEDs are on, system redraws If LEDS are off, the new values are used the next time the LEDs are manually set to on. But you can use command “chaining” to set the properties and the state in one command:

http://your_ip_address/api?ledeffect=Segments2&ledcolor=255,0,0&ledcolor2=0,0,255&ledspeed=5&ledstate=on

The above example, would turn on the LEDs, using the “Segments2” effect with red and blue colors and a speed of 5. So you can use a single command to set the properties as part of setting the LED state to ON.

Manually Sending a Sensor Trigger

When the system is in ‘normal’ mode (/sensoroverride: OFF), you can send a command to simulate a sensor trigger. This causes the system to act exactly as it would if the actual sensor was triggered. The only exceptions are that any debounce or cooldown settings are ignored and the command immediately exceutes the trigger operation on the primary controller. As soon as “ON” command is received, the sensor operation returns to use of the regular sensors.

Therefore, there is no need to send a separate “OFF” command. As soon as the “ON” command is processed, additional state reading revert back to the actual sensor, which will have an ON or OFF state.

Manual triggers sent when the sensor override is on (/sensoroverride: ON) are ignored since all sensor processing is bypassed in override mode.

GET Commands

These commands retrieve data and do not modify settings. They must be sent individually.

Command	Parameter(s)	Returns	Example / Notes
`ping`	1	OK or -48 / Timeout	`/api?ping=1` Returns `OK` if successful. Returns `ERR_CONNECTION_TIMED_OUT` if not found.
`ipaddress`	1	IP Address	`/api?ipaddr=1` Returns IP address of primary controller.
`macaddress`	1	MAC Address	Returns MAC of primary controller.

DIRECT Commands

These are shortcut commands typically sent to a specific controller. Note the omission of /api in the URL.

Controller-Specific Direct Calls

Command	Parameter(s)	Returns	Notes
`/restart`	none	Web Page	Reboots the targeted controller.
`/otaupdate`	none	Web Page	Places targeted unit in OTA Update mode.

<- Previous: MQTT Setup & Topics Next: Home Assistant Discovery ->