> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreflux.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Shelly Cloud Control

> Client-mode REST API connectors for Shelly Gen2+ devices (local RPC over HTTP) and the Shelly Cloud Control API v2: switch, cover, light, power and 3-phase energy meter status, energy history, webhooks, relay and cover control

Technical Preview

## Overview

Client-mode REST API connectors for Shelly Gen2+ devices (local RPC over HTTP) and the Shelly Cloud Control API v2: switch, cover, light, power and 3-phase energy meter status, energy history, webhooks, relay and cover control.

This is one of the templates in the Shelly (Gen2+ local RPC and Shelly Cloud) REST API app (`shelly`). Deploy it alongside the other connectors of that app when they depend on each other (for example a token connector plus an API connector).

> [!NOTE]
>
> Not yet verified against the live vendor API: No Shelly device reachable from the box and no Shelly Cloud auth key: the local connector needs a Gen2+ device on the LAN, and the cloud connector needs an account server uri + Authorization cloud key + a device id. The real cloud endpoint was probed (401 UNAUTHORIZED without a key); no authenticated live call could run.

## Auth

* **schemes**: \["none (local, device auth off)", "auth\_key query parameter (cloud)"]
* **secret**: SHELLY\_CLOUD\_AUTH\_KEY
* **note**: Local HTTP RPC uses SHA-256 Digest (RFC 7616) when auth is enabled; the REST\_API connector cannot answer the per-request nonce challenge, so protected devices return 401 except Shelly.GetDeviceInfo and /shelly. Use the device's native MQTT (\<shelly-id>/rpc) or the cloud connector for protected devices.

## Template parameters

| Placeholder | Type | Description | Required |
| - | - | - | - |
| `RouteName` | string | Name of the Shelly Cloud Control connector | no |
| `BaseUrl` | string | Shelly Cloud Control base URL without trailing slash (e.g. [https://shelly-49-eu.shelly.cloud](https://shelly-49-eu.shelly.cloud)) | yes |

`BASE_ADDRESS` default: `https://shelly-49-eu.shelly.cloud`.

## Events

| Event | Method | Endpoint | Request topic | Response topic | Payload fields |
| - | - | - | - | - | - |
| `CloudGetDevices` | POST | `/v2/devices/api/get?auth_key={value.json.auth_key}` | `energy/shelly/cloud/devices/get` | `energy/shelly/cloud/devices/get/response` | `auth_key`, `body` |
| `CloudSetSwitch` | POST | `/v2/devices/api/set/switch?auth_key={value.json.auth_key}` | `energy/shelly/cloud/switch/set` | `energy/shelly/cloud/switch/set/response` | `auth_key`, `body` |
| `CloudSetCover` | POST | `/v2/devices/api/set/cover?auth_key={value.json.auth_key}` | `energy/shelly/cloud/cover/set` | `energy/shelly/cloud/cover/set/response` | `auth_key`, `body` |
| `CloudSetLight` | POST | `/v2/devices/api/set/light?auth_key={value.json.auth_key}` | `energy/shelly/cloud/light/set` | `energy/shelly/cloud/light/set/response` | `auth_key`, `body` |
| `CloudSetGroups` | POST | `/v2/devices/api/set/groups?auth_key={value.json.auth_key}` | `energy/shelly/cloud/groups/set` | `energy/shelly/cloud/groups/set/response` | `auth_key`, `body` |

## Deploy

Get the template card (JSON with `template` and `metadata`) from the broker, then deploy the connector:

```bash theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
mosquitto_pub -t '$SYS/Coreflux/Command' -m "-routeCode SHELLY_CLOUD_CONTROL"
```

The deployable connector from the REST API app, with `BASE_ADDRESS` already filled in:

```lot theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
DEFINE ROUTE ShellyCloudControl WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://shelly-49-eu.shelly.cloud"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '10'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT CloudGetDevices
        WITH SOURCE_TOPIC "energy/shelly/cloud/devices/get"
        WITH DESTINATION_TOPIC "energy/shelly/cloud/devices/get/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/devices/api/get?auth_key={value.json.auth_key}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT CloudSetSwitch
        WITH SOURCE_TOPIC "energy/shelly/cloud/switch/set"
        WITH DESTINATION_TOPIC "energy/shelly/cloud/switch/set/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/devices/api/set/switch?auth_key={value.json.auth_key}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT CloudSetCover
        WITH SOURCE_TOPIC "energy/shelly/cloud/cover/set"
        WITH DESTINATION_TOPIC "energy/shelly/cloud/cover/set/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/devices/api/set/cover?auth_key={value.json.auth_key}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT CloudSetLight
        WITH SOURCE_TOPIC "energy/shelly/cloud/light/set"
        WITH DESTINATION_TOPIC "energy/shelly/cloud/light/set/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/devices/api/set/light?auth_key={value.json.auth_key}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
    ADD EVENT CloudSetGroups
        WITH SOURCE_TOPIC "energy/shelly/cloud/groups/set"
        WITH DESTINATION_TOPIC "energy/shelly/cloud/groups/set/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/v2/devices/api/set/groups?auth_key={value.json.auth_key}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "User-Agent" "Coreflux-Broker REST_API route (https://www.coreflux.org)"
            ADD "Content-Type" "application/json"
        WITH BODY "{value.json.body}"
```

Deploy it with `-addRoute` (do not include `ADD METADATA`).

## Usage example

Call `CloudGetDevices` by publishing a JSON payload to its request topic, and read the reply on the response topic:

```bash theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
mosquitto_sub -t 'energy/shelly/cloud/devices/get/response' &
mosquitto_pub -t 'energy/shelly/cloud/devices/get' -m '{"auth_key": "<auth_key>", "body": {}}'
```

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [REST API Apps catalog](/latest/lot-language/routes/rest-api-apps)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.