BXWHzHA2

1Shelly cloud API access
2DIMITAR DIMITROV·WEDNESDAY, MAY 29, 2019·
3 We have added a secure external API to the Shelly cloud, something many customers have requested. This will allow 3rd party programs which you authorize to control your Shelly devices from anywhere through the Shelly cloud.
4To use  3rd party cloud API  you must to create account in Shelly cloud App or http://my.shelly.cloud
5Associate your Shelly devices to it. 
6Generate auth_key in Shelly APP.
7Copy your server location link
8Important: 
9API is limited to 1 request per second at the moment. For professional or comercial usage contact Shelly Team. 
10
11How to generate auth_key in Shelly APP:
12Login in to Shelly APP, go to User Settings. Click on auth_key. Copy and paste the CloudKey. Copy and paste your server location link 
13IMPORTANT: 
14Do not show this auth_key and/or server location to anyone, if anyone else has it, they can control your devices!
15If you change your account password, the auth_key will be changed too.  
16How to use auth_key 
17 You can execute commands using cloud Key and change ANY device settings. 
18
19Check any type device status: 
20You can read the status for any Shelly device using this parameters of the POST command: 
21POST link: https://[server location link]/device/status
22Keys:
23id =[devce ID] - you can check the id from Settigns -> Device information. 
24auth_key=[auth_key]
25Example:
26
27Check device status
28Change status ans send commands to devices
29For Shelly1, Shelly1PM, Shellu2, Shelly2.5, Shelly4pro: 
30The syntax of the parameters of the POST command is:  
31POST link: https://[server location link]/device/relay/control/
32
33Keys:
34channel=[channel number] - you can check the channel from 
35                               Settings->Device informationkey 
36
37turn=[command]
38id=[deviceID] - you can check the channel from  Settings->Device informationkey 
39auth_key=[auth_key]
40Where:
41channel number: 0-3 (0 i channel 1, 3 is channel 4)
42commands:on or off
43deviceID: device id which you want to control. You can copy it from Settings -> Device info
44auth_key: The key which you copy paste from your accoun 
45
46Example: 
47
48Post command Example
49For Shelly2 and 2.5 in roller shutter mode: 
50The syntax of the command for open and close is:  
51POST link: https://[server location link]/device/relay/roller/control/
52Keys: direction=[command]id=[deviceID] - you can check the channel from Settings->Device informationkey auth_key=[auth_key]
53 Where:
54directions: open, close, stop
55deviceID: device id which you want to control. You can copy it from Settings -> Device info auth_key: The key which you copy paste from your account.   
56
57Example: 
58
59Open and Close example
60The syntax of the command for open and close by percentage is:  
61POST link: https://[server location link]/device/relay/roller/settings/toposkey
62
63Keys:
64pos=[value]
65id=[deviceID] - you can check the channel from Settings->Device information
66auth_key=[auth_key]
67 Where:
68pos value: 0-100
69deviceID: device id which you want to control. You can copy it from Settings -> Device info auth_key: The key which you copy paste from your account.  
70Example:
71
72Open/Close by percentage
73For ShellyRGBW2, Bulb and RGBW in color mode
74The syntax of the command is: 
75POST link: https://[server location link]/device/light/control 
76Keys: 
77turn=[command]
78white=[value] 
79red=[value]
80green=[value]
81blue=[value] 
82gain=[value]
83key id=[deviceID] - you can check the channel from Settings->Device information
84key auth_key=[auth_key]
85Where:
86turn: on or off
87optional: 
88white, red, green and blue value: 0 - 255
89gain value: 0 - 100 it’s only for RGB color
90Examples:
91
92Turn device ON with last set values
93
94
95Set white to 30%
96
97
98Turn On and Set white to 30%
99
100
101Turn On and Set all colors + gain of the RGB
102For ShellyRGBW2, Bulb and RGBW in white mode
103The syntax of the command is:  
104POST link: https://[server location link]/device/light/control 
105Keys: 
106channel=[channel number]
107turn=[command]brightness=[value]id=[deviceID] - you can check the channel from Settings->Device informationkey 
108auth_key=[auth_key]
109Where: 
110channel=0-4 
111turn: on or off 
112brightness=0-100 
113Example:
114
115Turn On and set brightenn to 50
116 How to control device from IFTTT Webhook ?
117
118To control Shelly devices from IFTTT you need to set Webhook as result of the conditions. 
119In URL you need to enter the https://[server location link]/[device specific link]Method:POST 
120Content type: application/x-www-form-urlencoded
121Body: all device specific parameters with “&” between them.
122
123Example:  
124
125Webhook example
126Bulk control 
127You can control multiple devices from cloud with just one command. 
128Devices must be from same type, only relays or roller shutters. 
129Bulk control for relays Shelly1, Shelly2, Shelly2.5, Shelly1PM, Shelly4Pro: 
130The syntax of the command is:  
131POST link: https://[server location link]/device/relay/bulk_control 
132
133Keys: 
134turn=[command]
135devices=[{"id"="device ID","channel"="device channel"},{"id"="device ID","channel"="device channel"}....]
136auth_key="authorisation key"
137Where: 
138 turn: on or off 
139devices: [{id="device ID",channel=device channel} - check device ID from the app. 
140auth_key: The key which you copy paste from your account
141Example: 
142
143Control mutiple devices
144IFTT Example: 
145Content type: application/x-www-form-urlencoded 
146Body: turn=on&[{"id":"8015a3","channel":"1"},{"id":"8015a3","channel":0},{"id":"c3682a","channel":0"}] &auth_key=lkjd983jijf0430fj430f430fj...
147
148IFTT bulk control example
149
150Document still updating