1. Summary
The APIs allow people/developers to interact with cloud services and manage resources provided by a cloud provider (in our case Shelly Cloud).
2. Features
With the Shelly Cloud API as for now (6/19/23) you can do the following things:
- get the device's current status
- for relays: switch each output individually
- for covers: open/close/stop commands and set a position
- for color lights: on/off, update color, update gain for each channel
- for white lights: on/off, update brightness for each channel
- groups (multiple relays at the same time/with a single request): only relays as per the documentation
Support requests types:
- GET - when fetching information from the server (no changes are required to the database): for getting the device's status
- POST - when changing/uploading new data into the database: for changing the device's output state, color, or settings
3. How to use
Requests can be sent via many methods like curl, postman, python script, script running on Shelly device and etc.
How to get the device's latest status via Shelly Cloud API and curl
- Path: https://<***server_uri>/device/status
- Supported methods: GET and POST
- Parameters are supplied via the *query or with the request's **body
- Required information to send the request:
- The ID of the target device: key = 'id'
- The account ****authentication key: key = 'auth_key'
- The result is a JSON object with the device's status
How to control the output for a relay device:
- Path: https://<***server_uri>/device/relay/control
- Supported methods: POST
- Parameters are supplied ONLY via the request's **body
- Required information to send the request:
- The ID of the target device: key = 'id'
- The account ****authentication key': key = 'auth_key'
- The channel that should be updated: key = 'channel' (first channel: 0 (single channel devices), second channel: 1)
- The updated state for the output: key = 'turn' (supported values: on and off)
- The result is a JSON with the target device ID
How to open/close a roller shutter device:
- Path: https://<***server_uri>/device/relay/roller/control
- Supported methods: POST
- Parameters are supplied ONLY via the request's **body
- Required information to send the request:
- The ID of the target device: key = 'id'
- The account ****authentication key': key = 'auth_key'
- The direction command: key = 'direction' (supported values: open, close and stop)
- The result is a JSON with the target device ID
How to set a position for a roller shutter device:
- Path: https://<***server_uri>/device/relay/roller/control
- Supported methods: POST
- Parameters are supplied ONLY via the request's **body
- Required information to send the request:
- The ID of the target device: key = 'id'
- The account ****authentication key': key = 'auth_key'
- Position in a percent: key = 'pos' (supported values: every full value from 0 to 100(included))
- The result is a JSON with the target device ID
How to update the output of color controlling device :
- Path: https://<***server_uri>/device/light/control
- Supported methods: POST
- Parameters are supplied ONLY via the request's **body
- Required information to send the request:
- The ID of the target device: key = 'id'
- The account ****authentication key': key = 'auth_key'
- The updated state for the output: key = 'turn' (supported values: on and off)
- The value for the white channel: key= 'white' (supported values: every full value from 0 to 255 (included))
- The value for the red channel: key= 'red' (supported values: every full value from 0 to 255 (included))
- The value for the green channel: key= 'green' (supported values: every full value from 0 to 255 (included))
- The value for the blue channel: key= 'blue' (supported values: every full value from 0 to 255 (included))
- The value for the gain: key= 'gain' (supported values: every full value from 0 to 100 (included))
- The result is a JSON with the target device ID
How to update the output of a dimming device :
- Path: https://<***server_uri>/device/light/control
- Supported methods: POST
- Parameters are supplied ONLY via the request's **body
- Required information to send the request:
- The ID of the target device: key = 'id'
- The account ****authentication key': key = 'auth_key'
- The updated state for the output: key = 'turn' (supported values: on and off)
- The brightness value: key= 'brightness' (supported values: every full value from 0 to 100 (included))
- The result is a JSON with the target device ID
*query: Parameters located after the endpoint stating with the question mark symbol (?) and ends with the hashtag symbol or until the end of the request. The data is formatted as key=value pairs, where the key is before the equal symbol (=) (ex. ivan=petyr, the key is "ivan", and the value is "petyr") and the value is after it. When multiple pairs are needed must be separated with the and symbol (&)
**body: This is part of the request where sensitive information can be sent, hidden from the request URL (not as the query). If using curl to send the request the body data is prefixed with '-d' and the parameters are written the same as the query as key=value pairs and separated with the and symbol
***server_uri: The URL for the server where all client's devices and accounts are located . This can be obtained from the Shelly App > User settings > Authorization cloud key
****Authentication key: Unqie key that's generation is based on the password for the client's account. When password is changed the auth key is changed as well