Introducing the Innerscene Developer API

The HTTP interface that has been driving Innerscene Studio for years is now publicly documented. The Innerscene Developer API lets you control any Circadian Sky or Virtual Sun fixture directly from your local network. No SDK, no cloud round-trip, no account.

Every fixture has shipped with this HTTP server since launch. Innerscene Studio uses it. The Wi-Fi configuration UI uses it. What is new is that we are now publishing it as a stable public surface, with parameters, return values, and worked examples in Node.js, Python, and Home Assistant.

Once a fixture is on Wi-Fi it serves a small HTTP server on port 80. Any device on the same LAN can read its full state and drive its color, brightness, and schedule with simple GET requests. The protocol is JSON, and the surface area is intentionally small so your integration stays maintainable as firmware evolves.

What you can build with it

The published surface covers 27 endpoints across six categories:

• Light control. /setCCT, /previewCCT, /setSchedule, /setFade, /identify. Drive color temperature in Kelvin and brightness as a 0-1 normalised value or an absolute lux target.
• Status and identity. /getStatus returns a compact JSON snapshot suitable for polling: time, CCT, lux, MAC, mode flags, peer count, weather modulation, daughterboard state, and more.
• Time and schedule. /setTimezone and /readClock for the schedule engine.
• External inputs. Live readings and configuration for the 0-10 V, DALI, DMX, and Casambi daughterboards.
• Network and peers. /getIPs, /getAPInfo, and /getPeerInfo for discovering the fixture and the rest of its wireless group.
• Direct channel control (Circadian Sky). /getChannels and /setChannels expose raw 12-bit PWM duty per LED channel for spectral research and sensor calibration. Photometric calibration is bypassed, so this endpoint is intentionally separated from normal control.

Who it is for

• System integrators wire fixtures into Crestron, Lutron, Savant, BMS controllers, and AV processors using HTTP - the same primitive every modern control system already speaks.
• Home automation enthusiasts add fixtures to Home Assistant, Node-RED, openHAB, or HomeKit-via-Homebridge for scenes, schedules, and voice-triggered automations.
• Researchers drive precise CCT and lux for circadian-rhythm, vision-science, and chronobiology studies. Channel-level control unlocks spectral tuning for stimulus delivery.
• Show-control and demo developers script time-lapse demos, retail experiences, and installations from Python, JavaScript, TouchDesigner, or any HTTP-capable environment.

A taste of the API

The whole protocol is HTTP. Set the fixture to 4500 K at 50% from a Node.js script:

// Set 4500 K at 50% brightness from a Node.js script
import fetch from "node-fetch";
const ip = "192.168.1.42";
await fetch(`http://${ip}/setSchedule?mode=0`);
await fetch(`http://${ip}/setCCT?cct=4500&i=0.5`);

Poll its live state from Python:

# Poll the fixture's live state once per second
import time, requests
ip = "192.168.1.42"
while True:
    s = requests.get(f"http://{ip}/getStatus", timeout=2).json()
    print(s["cct"], "K  ", s["lux"], "lux")
    time.sleep(1)

Or wire it straight into Home Assistant with no custom integration:

# Home Assistant configuration.yaml
rest_command:
  fixture_set_cct:
    url: "http://192.168.1.42/setCCT?cct={{ cct }}&i={{ intensity }}"
    method: GET

sensor:
  - platform: rest
    name: Office Fixture
    resource: "http://192.168.1.42/getStatus"
    value_template: "{{ value_json.cct }}"
    json_attributes: [cct, lux, flags, ls]

The full reference documents every parameter, return value, and decoding rule, with worked examples in Node.js, Python, and Home Assistant.

What is stable, what may evolve

The core control endpoints have been driving Innerscene Studio unchanged for years. They are stable and we do not expect to change them in a backwards-incompatible way:

• /setCCT, /getCCT, /previewCCT, /setSchedule, /setFade, /identify, /restart
• /getStatus, /getVersion, /getDeviceCapabilities, /getIPs, /getAPInfo

Newer or hardware-adjacent endpoints - the daughterboard configurators, direct channel control, peer info, and weather modulation - may gain parameters or new fields as we extend hardware support. Field names will be additive where possible. If your integration is shipping in production, lock your fixtures to a known firmware version and watch our blog for change notes.

Local-first, by design

The API runs on the fixture itself. There is no Innerscene cloud in the path, no telemetry siphon, and no account binding required. Your automations keep working when your internet goes down. Your research data stays inside your VLAN.

The trade-off is that the HTTP server is unauthenticated on the LAN - any device on the same network can issue commands. We treat that the same way every other smart-home device on your network treats it: trust your LAN, do not port-forward, segment fixtures onto an IoT VLAN if your organisation prefers strict zoning.

Get started

1. Update each fixture to the latest firmware using Innerscene Studio.
2. Connect the fixture to your 2.4 GHz Wi-Fi network from Settings → Wi-Fi in Innerscene Studio.
3. Find the fixture's IP from the same screen, or look it up in your router's client list by MAC.
4. Open the Developer API documentation and copy a snippet to confirm the fixture is reachable.

Building something with the Developer API? We would love to hear about it. Email [email protected] and we will share the most interesting integrations on our blog.