Request for all the user's devices and their functions (get devices)

Last updated on May 25, 2023

Sber Smart Home queries a vendor for a list of all devices linked to the user's account.

Sample case:

1. A user in the vendor's app ties a new device to their account.
2. From time to time, Sber Smart Home queries the vendor for the list of all devices of a user.
3. The vendor returns it. It contains a new device.
4. Sber Smart Home updates the user's device list. In Salute mobile app, on SberBox, SberPortal and other devices supported with Salute assistants, the new device appears and becomes available for management.

Query format

Sber Smart Home sends a query to the vendor's endpoint. For the headers, see Query headers.

GET /v1/devices

Response format

Success response:

Field	Type	Mandatory?	Description
devices	list<objects>	✔︎	Device list (see User device (device))

{
    "devices": [
        {
            "id": string,
            "parent_id": string,
            "name": string,
            "default_name": string,
            "nicknames": [
                string,
                string
                // ...
            ],
            "home": string,
            "room": string,
            "groups": [
                string,
                string
                // ...
            ],
            "model_id": string,
            "hw_version": string,
            "sw_version": string,
            "partner_meta": {
                "key": value,
                "key": value,
                // ...
            },
        },
        {
            // ...
        }
    ]
}

When an error occurs, an object of the Common error (common error) type should be returned:

{
    "code": integer,
    "message": string,
    "details": list<string>
}

Sample query and response

Sber Smart Home queries the vendor for the list of all devices of a user. The vendor returns the list of two devices: a lamp and a socket.

Query:

curl -i -X GET /v1/devices \
-H Host: example.com \
-H Content-Type: application/json \
-H Authorization: Bearer qwerty-1234-... \
-H X-Request-Id: abcd-0000-ifgh-...

Success response:

{
    "devices": [
        {
            "id": "ABCD_003",
            "name": "My lamp",
            "default_name": "Smart lamp",
            "nicknames": [
                "LED lamp",
                "Smart lamp"
            ],
            "home": "My home",
            "room": "Living room",
            "groups": [
                "Overhead light",
                "Alcove"
            ],
            "model_id": "QWERTY123",
            "hw_version": "3.2",
            "sw_version": "5.7",
            "partner_meta": {
                "internal-id": 1234,
                "specificity": "microchip 2A"
            },
        },
        {
            "id": "ABCD_004",
            "name": "My outlet",
            "default_name": "Smart outlet",
            "nicknames": [
                "Smart socket",
                "Controlled socket"
            ],
            "home": "My home",
            "room": "Living room",
            "groups": [
                "Video equipment",
                "Sound"
            ],
            "model_id": "QWERTY124",
            "hw_version": "3.1",
            "sw_version": "5.6",
            "partner_meta": {
                "internal-id": 1235,
            },
        },
    ]
}

Error response:

{
    "code": 400,
    "message": "Invalid argument",
    "details": []
}