====== Indigo REST API ======

<color red>**//NOTE//**</color> : this API was **deprecated in Indigo v2022.2**.

These REST semantics are loosely based [[http://microformats.org/wiki/rest/urls|RoR's use of RESTful URLs.]]

====== Devices Access ======
Examples to get HTML, JSON (new in Indigo 6), XML, and TXT versions of the device list:
<code>
http://127.0.0.1:8176/devices/
http://127.0.0.1:8176/devices.json/
http://127.0.0.1:8176/devices.xml/
http://127.0.0.1:8176/devices.txt/
</code>

Examples to get HTML, XML, and TXT versions of device "office-lamp":
<code>
http://127.0.0.1:8176/devices/office-lamp.html
http://127.0.0.1:8176/devices/office-lamp.json
http://127.0.0.1:8176/devices/office-lamp.xml
http://127.0.0.1:8176/devices/office-lamp.txt
</code>

Example of editing using HTML form to modify office-lamp editable properties; Form submit will do a virtual PUT to update the properties:
<code>
http://127.0.0.1:8176/devices/office-lamp/edit
</code>

Example use of curl and virtual HTTP PUT call to change brightness to 27; HTTP result is a 303 redirect back to the device resource after the update is complete:
<code>
curl -X PUT -d brightness=27 http://127.0.0.1:8176/devices/office-lamp
http://127.0.0.1:8176/devices/office-lamp?brightness=27&_method=put
</code>

Example use of curl and virtual HTTP PUT call to change office-lamp's isOn to False and True:
<code>
curl -X PUT -d isOn=0 http://127.0.0.1:8176/devices/office-lamp
curl -X PUT -d isOn=1 http://127.0.0.1:8176/devices/office-lamp
http://127.0.0.1:8176/devices/office-lamp?isOn=0&_method=put
http://127.0.0.1:8176/devices/office-lamp?isOn=1&_method=put
</code>

Example use of curl and virtual HTTP PUT call to toggle office-lamp's state:
<code>
curl -X PUT -d toggle=1 http://127.0.0.1:8176/devices/office-lamp
http://127.0.0.1:8176/devices/office-lamp?toggle=1&_method=put
</code>

Example use of curl and virtual HTTP PUT call to change speedIndex to 0 (off), 3 (high), then decrease back to 0 (off):
<code>
curl -X PUT -d speedIndex=0 http://127.0.0.1:8176/devices/office-ceiling-fan
curl -X PUT -d speedIndex=3 http://127.0.0.1:8176/devices/office-ceiling-fan
curl -X PUT -d speedIndex=dn http://127.0.0.1:8176/devices/office-ceiling-fan
curl -X PUT -d speedIndex=dn http://127.0.0.1:8176/devices/office-ceiling-fan
curl -X PUT -d speedIndex=dn http://127.0.0.1:8176/devices/office-ceiling-fan
http://127.0.0.1:8176/devices/office-ceiling-fan?speedIndex=0&_method=put
http://127.0.0.1:8176/devices/office-ceiling-fan?speedIndex=3&_method=put
http://127.0.0.1:8176/devices/office-ceiling-fan?speedIndex=dn&_method=put
http://127.0.0.1:8176/devices/office-ceiling-fan?speedIndex=dn&_method=put
http://127.0.0.1:8176/devices/office-ceiling-fan?speedIndex=dn&_method=put
</code>

Example use of curl and virtual HTTP PUT call to change device "irrmaster-pro" active sprinkler zone to 3 and all off:
<code>
curl -X PUT -d activeZone=3 http://127.0.0.1:8176/devices/irrmaster-pro
curl -X PUT -d activeZone=0 http://127.0.0.1:8176/devices/irrmaster-pro
http://127.0.0.1:8176/devices/irrmaster-pro?activeZone=3&_method=put
http://127.0.0.1:8176/devices/irrmaster-pro?activeZone=0&_method=put
</code>

Example use of curl and virtual HTTP PUT call to change device "irrmaster-pro" sprinkler mode:
<code>
curl -X PUT -d activeZone=stop http://127.0.0.1:8176/devices/irrmaster-pro
curl -X PUT -d activeZone=run http://127.0.0.1:8176/devices/irrmaster-pro
curl -X PUT -d activeZone=pause http://127.0.0.1:8176/devices/irrmaster-pro
curl -X PUT -d activeZone=resume http://127.0.0.1:8176/devices/irrmaster-pro
curl -X PUT -d activeZone=next http://127.0.0.1:8176/devices/irrmaster-pro
curl -X PUT -d activeZone=prev http://127.0.0.1:8176/devices/irrmaster-pro
http://127.0.0.1:8176/devices/irrmaster-pro?activeZone=stop&_method=put
http://127.0.0.1:8176/devices/irrmaster-pro?activeZone=run&_method=put
http://127.0.0.1:8176/devices/irrmaster-pro?activeZone=pause&_method=put
http://127.0.0.1:8176/devices/irrmaster-pro?activeZone=resume&_method=put
http://127.0.0.1:8176/devices/irrmaster-pro?activeZone=next&_method=put
http://127.0.0.1:8176/devices/irrmaster-pro?activeZone=prev&_method=put
</code>

Example use of curl and virtual HTTP PUT call to change device "thermostat" heat and cool setpoints:
<code>
curl -X PUT -d setpointCool=68 -d setpointHeat=84 http://127.0.0.1:8176/devices/thermostat
curl -X PUT -d setpointCool=72 -d setpointHeat=78 http://127.0.0.1:8176/devices/thermostat
curl -X PUT -d setpointCool=up -d setpointHeat=up http://127.0.0.1:8176/devices/thermostat
curl -X PUT -d setpointCool=dn -d setpointHeat=dn http://127.0.0.1:8176/devices/thermostat
http://127.0.0.1:8176/devices/thermostat?_method=put&setpointCool=68&setpointHeat=84
http://127.0.0.1:8176/devices/thermostat?_method=put&setpointCool=72&setpointHeat=78
http://127.0.0.1:8176/devices/thermostat?_method=put&setpointCool=up&setpointHeat=up
http://127.0.0.1:8176/devices/thermostat?_method=put&setpointCool=dn&setpointHeat=dn
</code>

Example use of curl and virtual HTTP PUT call to change device "thermostat" hvac mode to "cool on" and "auto on":
<code>
curl -X PUT -d hvacCurrentMode="cool on" http://127.0.0.1:8176/devices/thermostat
curl -X PUT -d hvacCurrentMode="auto on" http://127.0.0.1:8176/devices/thermostat
http://127.0.0.1:8176/devices/thermostat?_method=put&hvacCurrentMode=cool%20on
http://127.0.0.1:8176/devices/thermostat?_method=put&hvacCurrentMode=auto%20on
</code>

Example use of curl and virtual HTTP PUT call to change device "thermostat" hvac fan mode to "always on" and "auto on":
<code>
curl -X PUT -d hvacFanMode="always on" http://127.0.0.1:8176/devices/thermostat
curl -X PUT -d hvacFanMode="auto on" http://127.0.0.1:8176/devices/thermostat
http://127.0.0.1:8176/devices/thermostat?_method=put&hvacFanMode=always%20on
http://127.0.0.1:8176/devices/thermostat?_method=put&hvacFanMode=auto%20on
</code>

Example use of curl and virtual HTTP PUT call to change binary output state of an EZIO module device "garage-io":
<code>
curl -X PUT -d outputBinaryStates="0,0,0,0,1,1,1,1" http://127.0.0.1:8176/devices/garage-io
curl -X PUT -d outputBinaryStates="1,0,1,0,0,0,0,0" http://127.0.0.1:8176/devices/garage-io
curl -X PUT -d outputBinaryStates="set4" http://127.0.0.1:8176/devices/garage-io
curl -X PUT -d outputBinaryStates="clear4" http://127.0.0.1:8176/devices/garage-io
http://127.0.0.1:8176/devices/garage-io?_method=put&outputBinaryStates=0,0,0,0,1,1,1,1
http://127.0.0.1:8176/devices/garage-io?_method=put&outputBinaryStates=1,0,1,0,0,0,0,0
http://127.0.0.1:8176/devices/garage-io?_method=put&outputBinaryStates=set4
http://127.0.0.1:8176/devices/garage-io?_method=put&outputBinaryStates=clear4
</code>
====== Variable Access ======
Examples to get HTML, JSON (new in Indigo 6), XML, and TXT versions of the variable list:
<code>
http://127.0.0.1:8176/variables/
http://127.0.0.1:8176/variables.json/
http://127.0.0.1:8176/variables.xml/
http://127.0.0.1:8176/variables.txt/
</code>

Examples to get HTML, JSON (new in Indigo 6), XML, and TXT versions of variable "sprinklerDurationMultiplier":
<code>
http://127.0.0.1:8176/variables/sprinklerDurationMultiplier.html
http://127.0.0.1:8176/variables/sprinklerDurationMultiplier.json
http://127.0.0.1:8176/variables/sprinklerDurationMultiplier.xml
http://127.0.0.1:8176/variables/sprinklerDurationMultiplier.txt
</code>

Example use of curl and virtual HTTP PUT call to change variable "sprinklerDurationMultiplier" value to 1.23; HTTP result is a 303 redirect back to the variable resource after the update is complete:
<code>
curl -X PUT -d value=1.23 http://127.0.0.1:8176/variables/sprinklerDurationMultiplier
http://127.0.0.1:8176/variables/sprinklerDurationMultiplier?_method=put&value=1.23
</code>

And, while not exactly RESTful, here's the URL you can use in your custom control pages to link to an editor page for a variable (select "Link to External URL" on the "Client action" popup and insert the following):

<code>/editvarpage?name=SOME_VARIABLE_NAME&redirectPage=RETURN_PAGE_NAME</code>

That replaces the variable plugin that's in the user contribution library.

====== Action Group Access and Execution ======

Examples to get HTML, JSON (new in Indigo 6), XML, and TXT versions of the action group list:
<code>
http://127.0.0.1:8176/actions/
http://127.0.0.1:8176/actions.json/
http://127.0.0.1:8176/actions.xml/
http://127.0.0.1:8176/actions.txt/
</code>

Examples to get HTML, JSON (new in Indigo 6), XML, and TXT versions of action group "cooking scene":
<code>
http://127.0.0.1:8176/actions/cooking%20scene.html
http://127.0.0.1:8176/actions/cooking%20scene.json
http://127.0.0.1:8176/actions/cooking%20scene.xml
http://127.0.0.1:8176/actions/cooking%20scene.txt
</code>

Example use of curl and virtual HTTP execute call to execute action group "party scene":
<code>
curl -X EXECUTE http://127.0.0.1:8176/actions/party%20scene
http://127.0.0.1:8176/actions/party%20scene?_method=execute
</code>

====== INSTEON Links Retrieval ======
Example to get XML version (HTML, JSON and TXT not available) of the INSTEON links:
<code>
http://127.0.0.1:8176/insteonlinks/
</code>

Example to get XML INSTEON links for device "office-lamp":
<code>
http://127.0.0.1:8176/insteonlinks/office-lamp
</code>

Example to get XML INSTEON links for the PowerLinc:
<code>
http://127.0.0.1:8176/insteonlinks/PowerLinc%20Interface
</code>

====== Authentication ======

As of v2021.1, Indigo now supports both basic and digest HTTP authentication simultaneously, and offers a new API key feature for use with the API. To use either of the HTTP authentication methods, you must have a username/password set in the Start Local Server dialog. 
===== HTTP Authentication =====

**HTTP Digest** authentication is the default authentication method for the REST API. To use it in the curl examples above, you can specify your authentication like this:

<code>curl -u user:password --digest [other options here]</code>

In Python, we recommend using the [[https://docs.python-requests.org/en/master/|requests library]] (included with Indigo and available to Indigo Python scripts):

<code>import requests
from requests.auth import HTTPDigestAuth
reply = requests.get('https://myreflector.indigodomo.net/', auth=HTTPDigestAuth('username', 'password'))
</code>

Of course, you would use the full REST URL. That will allow your scripts to successfully authenticate and execute against a protected server.

If you have **HTTP Basic** authentication enabled in the Start Local Server dialog, you can pass the username and password on the URL itself (note that this is less secure and should only be used on HTTPS connections since the password is sent in clear text on non-HTTPS URLs):

https://username:password@myreflector.indigodomo.net/

We don't enable Basic auth by default because it is less secure than Digest auth, but we make it available when you have no other option to integrate from an outside source.



===== API Key =====

In Indigo 2021.1 or later, you can use an even more secure API token to authenticate your REST requests. 

<color blue>**Note**</color>: To use API Keys with the REST API, you must have an active Indigo Up-to-Date subscription.

To use keys to authenticate REST calls, you must first generate an API Key in your Indigo Account. Log in and select the Authorizations item in the navigation menu on the left. This will show you a page that looks something like this:

{{:authorizations.png?nolink|}}

The lower section of the page shows your API Keys. You can generate a new key by selecting your license from the popup at the bottom and clicking the Add API Key button. This will generate a key that is valid on the license specified (most users just have a single license, but some have multiple).

Next, when you make a call to the REST API, you will include the Authorization header with the value of 'Bearer API_KEY_HERE'. In curl:

<code>curl -H "Authorization: Bearer API_KEY_HERE" [other options here]</code>

In Python:

<code>import requests
my_headers = {"Authorization": "Bearer API_KEY_HERE"}
reply = requests.get('https://myreflector.indigodomo.net/', headers=my_headers)
</code>

Again, you would use the full REST URL rather than just the host.
====== AppleScript & the RESTful API ======

To work around the Mac OS X "application isn't running" bug (error -600) that seems to be getting worse with each OS release, you can communicate between an external AppleScript (or app that runs AppleScripts) by using the curl command in a **do shell script** AppleScript call with the commands above to set (and get) information from the Indigo server. 

For example, here's a simple AppleScript that will turn an Indigo device ON and then OFF:

<code>
set indigoServerIPandPort to "192.168.1.123:8176"
set indigoServerUsername to "username here"
set indigoServerPassword to "password here"
set devName to "office%20lamp" -- note spaces have to escaped by substituting with %20
set turnOffCommand to "curl -u " & indigoServerUsername & ":" & indigoServerPassword & " --digest -X PUT -d isOn=0 http://" & indigoServerIPandPort & "/devices/" & devName
set turnOnCommand to "curl -u " & indigoServerUsername & ":" & indigoServerPassword & " --digest -X PUT -d isOn=1 http://" & indigoServerIPandPort & "/devices/" & devName
do shell script turnOnCommand
do shell script turnOffCommand
</code>

And here's a simple AppleScript that will set the value of an Indigo variable:

<code>
set indigoServerIPandPort to "192.168.1.123:8176"
set indigoServerUsername to "username here"
set indigoServerPassword to "password here"
set varName to "someVariable"
set varValue to "hello"
set commandString to "curl -u " & indigoServerUsername & ":" & indigoServerPassword & " --digest -X PUT -d value=varValue http://" & indigoServerIPandPort & "/variables/" & varName
do shell script commandString
</code>

Here's an example of getting a variable value:

<code>
set varValueJson to do shell script "curl -u username:password --digest http://127.0.0.1:8176/variables/someVariable.json"

tell application "JSON Helper"
	set varValueRecord to read JSON from varValueJson
	set varValue to value of varValueRecord
end tell
</code>

Note, to use this script you need the Mac App called [[https://itunes.apple.com/WebObjects/MZStore.woa/wa/viewSoftware?id=453114608&mt=12 |JSON Helper]], which is free from the Mac App Store. This free app does a fantastic job of converting JSON formatted data into AppleScript native data types (like lists and records).

This approach has the advantage of running from any Mac anywhere, whether on the same Mac as your server, another Mac on your local network, or a Mac somewhere out on the internet (use your reflector URL if you're doing the latter).

You can also have AppleScript directly communicate with Indigo's python scripting engine [[https://github.com/IndigoDomotics/indigo-basic-applescript-control|as shown here]]. That is a slower technique but doesn't use Indigo's Web server and thus doesn't need the username or password embedded in the script.