Skip to content
DADL

shelly-cloud

shelly-cloud

contains code

Shelly Cloud Control API — monitor and control Shelly IoT devices (switches, covers, lights) via the Shelly Cloud

Source: Shelly Cloud Control API

device statusswitch controlcover controllight controlgroup controlbulk relaybulk lightbulk rollerauth:apikey
Author: Dunkel Cloud GmbH Updated: 2026-03-26

Coverage

78% (14 of ~18 endpoints)

Focus: device status, switch control, cover control, light control, group control, bulk relay, bulk light, bulk roller

Missing: real-time WebSocket events, integrator token exchange, OAuth token exchange

Last reviewed: 2026-03-26

Tools (14)

POST get_devices_status Get state of up to 10 Shelly devices. Returns online status, settings, and/or live sensor/relay data per device. Use list_devices first to discover device IDs.
POST set_switch Turn a Shelly relay/switch on or off. Supports auto-off timer via toggle_after.
POST set_cover Control a Shelly cover/roller. Supports open/close/stop commands, absolute position (0-100), relative movement, and slat control. position and relative are mutually exclusive. slatPosition and slatRelative are mutually exclusive.
POST set_light Control a Shelly light or dimmer. Supports on/off, brightness, color temperature, RGBW color, and effects.
POST set_groups Batch-control multiple devices at once by type. Send commands to groups of switches, covers, and/or lights in a single request. Device IDs in group arrays use format "deviceId_channel". Response may include failedCommands for devices that errored.
POST v1_device_status [DEPRECATED — use get_devices_status] Get device online status and state. Returns relay states, power readings, sensor data.
POST v1_relay_control [DEPRECATED — use set_switch] Control a relay on/off.
POST v1_roller_control [DEPRECATED — use set_cover] Control a roller/cover shutter.
POST v1_light_control [DEPRECATED — use set_light] Control a light (RGBW or white mode).
POST v1_relay_bulk_control [DEPRECATED — use set_groups] Bulk-control multiple relays at once.
POST v1_light_bulk_control [DEPRECATED — use set_groups] Bulk-control multiple lights at once.
POST v1_roller_bulk_control [DEPRECATED — use set_groups] Bulk-control multiple rollers at once.
POST list_devices List all devices on the account with names, types, and IDs. Unofficial endpoint used by the Shelly app — not in the official API docs but stable and widely used by integrations.
POST get_all_device_status Get status of all devices on the account in a single call. Returns online state, relay/sensor data for every device. Use show_info=true to include device names and types inline (avoids a separate list_devices call).

Composites (1) ⚠ contains code

FN get_named_status Get all device status with human-readable names and on/off summary. Joins list_devices (names) with get_all_device_status (live state).

Setup

  1. Install the Shelly mobile app (iOS/Android) and create a Shelly Cloud account
  2. Add your Shelly devices to the app and ensure they are cloud-connected
  3. In the app, go to User Settings > Authorization cloud key
  4. Copy both the 'auth_key' and the 'server_uri' values
  5. The server_uri becomes the base URL (e.g. https://shelly-103-eu.shelly.cloud)

Environment variable: CREDENTIAL_SHELLY_AUTH_KEY

Authentication docs ↗

The server_uri is per-account and region-specific (e.g. shelly-103-eu.shelly.cloud). You MUST use the server_uri shown in your Shelly app — there is no universal base URL. The auth_key regenerates automatically if you change your account password.

Install

Add to your backends.yaml:

- name: shelly-cloud
  transport: rest
  dadl: /app/dadl/shellycloud.dadl
  url: "https://<your-server-uri>"

Set the credential:

CREDENTIAL_SHELLY_AUTH_KEY=your-token-here
View on GitHub Raw DADL