Communication v2.0-beta

For controlling or fetching the state of a device, you will need its id. It can be found in the Shelly Cloud App under Device->Settings->Device Information->Device Id.

You will also need an AUTH_KEY and a HOST - refer to the Getting started section.

info

All requests in this section are limited to 1 request/second.

Get device(s) state

A more generalized and flexible way to fetch device information. It is a single endpoint, expecting a query like body that can get the state of up to 10 devices.

Request
curl -X POST 'https://<HOST>/v2/devices/api/get?auth_key=<AUTH_KEY>' \
    -H 'Content-Type: application/json' \
    -d '<BODY>'

Body structure
{
    "ids": string[],                     // (required) List of device ids (between 1 and 10).
    "select": ("status" | "settings")[], // List containing any of: `"status"`,`"settings"`. Additional data to fetch.
    "pick": {                            // Fetch only specified properties of the additional data. Fetch all if not provided.
        "status": string[],  // Restrict device status to specific top-level properties. Fetch all if not provided.
        "settings": string[] // Restrict device settings to specific top-level properties. Fetch all if not provided.
    }
}

The response will be a list of device states, each state with the following structure:

Device State
{
    // All devices have these basic properties
    "id": string;
    "type": string;
    "code": string;
    "gen": string;
    "online": 0 | 1;

    // Additional data all devices have, but with different content
    // Will be present only if specified in the request
    "status": {...};
    "settings": {...};
}

note

The status or settings will be missing from the state if:

It is not included in the select parameter
The pick parameter is used and all picked properties do not exist for this device

Example

Check device status.sys and settings.ble
curl -X POST 'https://<HOST>/v2/devices/api/get?auth_key=<AUTH_KEY>' \
    -H 'Content-Type: application/json' \
    -d '{"ids":["b48a0a1cd978"],"select":["status","settings"],"pick":{"status":["sys"],"settings":["ble"]}}'

View Response

Device status.sys and settings.ble
[
  {
    // Basic device info always present for all devices
    "id": "b48a0a1cd978",
    "type": "relay",
    "code": "SNPL-00112EU",
    "gen": "G2",
    "online": 1,

    // Device status, only with the "sys" property
    "status": {
      "sys": {
        // These properties are nested deeper and cannot be independently "pick"-ed
        "mac": "B48A0A1CD978",
        "restart_required": false,
        "time": "10:40",
        "unixtime": 1739436047,
        "uptime": 464987,
        "ram_size": 260540,
        "ram_free": 120752,
        "fs_size": 458752,
        "fs_free": 135168,
        "cfg_rev": 49,
        "kvs_rev": 0,
        "schedule_rev": 0,
        "webhook_rev": 0,
        "available_updates": {
          "stable": {
            "version": "1.3.3"
          }
        },
        "reset_reason": 1
      }
    },

    // Device settings, only with the "ble" property
    "settings": {
      "ble": {
        // These properties are nested deeper and cannot be independently "pick"-ed
        "enable": true,
        "rpc": {
          "enable": true
        },
        "observer": {
          "enable": true
        }
      }
    }
  }
]

Control a single device

Controlling a device means setting its output state. Different endpoints are used, depending on the type of the targeted device - switch, cover or light.

Control a Switch

For all types and generations of relays and plugs

Request
curl -X POST "https://<HOST>/v2/devices/api/set/switch?auth_key=<AUTH_KEY>" \
    -H "Content-Type: application/json" \
    -d '<BODY>'

Body structure
{
    "id": string;            // (required) The Shelly device id
    "channel": number;       // Defaults to 0
    "on": boolean;           // (required) Output state
    "toggle_after": number;  // After how many seconds, the state should be set to oposite the value of "on"
}

Control a Cover

For all types and generations of rollers and covers

Request
curl -X POST "https://<HOST>/v2/devices/api/set/cover?auth_key=<AUTH_KEY>" \
    -H "Content-Type: application/json" \
    -d "<BODY>"

Body structure
{
    "id": string,                                   // (required) The Shelly device id
    "channel": number                               // Defaults to 0
    "position": 'open' | 'close' | 'stop' | number  // (required) Can be a number between 0 and 100 (inclusive) - open at what %
    "duration": number                              // Number of seconds before stopping the position change
}

Control a Light

For all types and generations of lights. Some may not support rgb and temperature adjustment.

Request
curl -X POST "https://<HOST>/v2/devices/api/set/light?auth_key=<AUTH_KEY>" \
    -H "Content-Type: application/json" \
    -d "<BODY>"

Body structure
{
    // For all light devices
    "id": string;               // (required) The Shelly device id
    "channel": number;          // Defaults to 0
    "on": boolean;              // Required if all other parameters are missing, to make sure the command does something
    "toggle_after": number;     // After how many seconds, the state should be set to oposite the value of "on"

    // For specific light devices
    "brightness": number;        // 0 to 100 included
    "red": number;               // 0 to 255 included
    "green": number;             // 0 tok 255 included
    "blue": number;              // 0 to 255 included
    "white": number;             // 0 to 255 included
    "gain": number;              // 0 to 100 included
}

Response Format

Successful execution of the control command is indicated only by the HTTP 200 OK response status code. In case of an error, the response body will have a short error string and a list of long readable messages that indicate the problem.

Error response structure
{
    "error": '<ERROR_STRING>',  // error string
    "data": {
        "messages": string[]    // list of readable error messages
    }
}

Status	Error String	Reason
`400`	`"DEVICE_FAILED_COMMAND"`	The command failed to execute due to some arbitrary reason
`400`	`"DEVICE_OFFLINE"`	The device seems to be offline
`400`	`"DEVICE_INVALID_MODE"`	The device is not in the correct mode (for covers and lights)
`400`	`"DEVICE_INVALID_CHANNEL"`	The given channel is invalid and not supported by this device
`400`	`"BAD_REQUEST"`	The command failed to execute due to invalid parameters
`404`	`"INSTANCE_NOT_FOUND"`	There seems to be a problem with the server responsible for this device
`404`	`"DEVICE_NOT_FOUND"`	The command failed, because of missing device state
`500`	`"UNEXPECTED_SUBSERVICE_ERROR"`	A subservice on our side failed the execution

Control a device group

Allows control of multiple devices as a group. The types of groups are switch, cover and light. Each group consists of a list of <ID>_<CHANNEL> and a command that is similar to its single device control equivalent. More than one type of group can be controled in a single request.

Request
curl -X POST "https://<HOST>/v2/devices/api/set/groups?auth_key=<AUTH_KEY>" \
    -H "Content-Type: application/json" \
    -d "<BODY>"

Body structure
{
    "switch": {
        "ids": string[];  // List of <ID>_<CHANNEL>  (channel defaults to 0 if not included)
        "command": {
            "on": boolean;           // (required) Output state
            "toggle_after": number;  // After how many seconds, the state should be set to oposite the value of "on"
        };
    };

    "cover": {
        "ids": string[];  // List of <ID>_<CHANNEL>  (channel defaults to 0 if not included)
        "command": {
            "position": 'open' | 'close' | 'stop' | number  // (required) Can be a number between 0 and 100 (inclusive) - open at what %
            "duration": number                              // Number of seconds before stopping the position change
        };
    };

    "light": {
        "ids": string[];  // List of <ID>_<CHANNEL>  (channel defaults to 0 if not included)
        "command": {
            // For all light devices
            "on": boolean;               // Required if all other parameters are missing, to make sure the command does something
            "toggle_after": number;      // A flip-back timer in seconds

            // For specific light devices
            "brightness": number;        // 0 to 100 included
            "red": number;               // 0 to 255 included
            "green": number;             // 0 tok 255 included
            "blue": number;              // 0 to 255 included
            "white": number;             // 0 to 255 included
            "gain": number;              // 0 to 100 included
        }
    };
}

note

In each group the command properties that are required are the same as in single device control.

Response Format

Except in the case of a validation or server error, the response will be a success with a HTTP 200 OK status. In case the command failed for some particular devices, a map with their id's and the corresponding error string will be returned:

Response
{
    "failedCommands": {
        // Ids are in Decimal and ALWAYS have a channel
        "<ID>_<CHANNEL>": "<ERROR_STRING>",
        ...
    }
}

Error String	Reason
`"DEVICE_UNSUPPORTED_COMMAND"`	The device received an unknown command
`"BAD_REQUEST"`	The command failed to execute due to invalid parameters
`"DEVICE_NOT_FOUND"`	Failed to retrieve the device's state
`"UNEXPECTED_SUBSERVICE_ERROR"`	A subservice on our side failed the execution
`"DEVICE_FAILED_COMMAND"`	The command failed to execute due to some arbitrary reason

Communication v2.0-beta

Get device(s) state​

Example​

Control a single device​

Control a Switch​

Control a Cover​

Control a Light​

Response Format​

Control a device group​

Response Format​

Get device(s) state

Example

Control a single device

Control a Switch

Control a Cover

Control a Light

Response Format

Control a device group

Response Format