Information about the states of user devices

Smart home platform request format
Provider response format
Example

Requests information about the state of user devices.

Example case where this request is sent: the user opens the Home with Alice app and wants to change the state of their devices.

In response to the request, the provider must return the states of the requested user devices.

Note

The capabilities for which the state request is not available (with retrievable=false). Can be omitted in the response because their state is ignored.

Smart home platform request format

The smart home platform sends a request to the provider's Endpoint URL (https://example.com/).

POST https://example.com/v1.0/user/devices/query

Request headers

Header	Description	Required
Authorization	Authorization token of the skill owner.	Yes
Content-Type	The format of sent/submitted data. Possible values: application/json.	Yes, in operations with HTTP POST
X-Request-Id	Request ID. Must be logged on the provider's side for investigating incidents and problems.	Yes

Request body format

{
    "devices": [
      {
        "id": String,
        "custom_data": Object
      },
      ...
    ]
}

Parameter	Type	Description	Required
devices	Array of objects	Array of the user's devices.	Yes

devices object

Parameter	Type	Description	Required
id	String	Device ID. It must be unique among all the manufacturer's devices.	Yes
custom_data	Object	An object passed by the provider for the device in response to the request Information about user devices.	No

Provider response format

The provider must use the correct format to respond to the request received from the smart home platform.

Response successful

Response with error

HTTP/1.1 200 OK

{
  "request_id": String,
  "payload": {
    "devices":[
      {
        "id": String,
        "capabilities": [
          "<capability1>": Object,
          "<capability2>": Object,
          ...
        ],
        "properties": [
          "<property1>": Object,
          "<property2>": Object,
          ...
        ],
        "error_code": String,
        "error_message": String
      },
      ...
    ]
  }
}

Parameter	Type	Description	Required
request_id	String	Request ID.	Yes
payload	Object	Object with devices.	Yes

payload object

Parameter	Type	Description	Required
devices	Array of objects	Array of the user's devices.	Yes

devices object

Parameter	Type	Description	Required
id	String	Device ID. It must be unique among all the manufacturer's devices.	Yes
capabilities	Array of objects	Array with information about device capabilities.	No
properties	Array of objects	Array with information about the device properties.	No
error_code	String	An error code from the list. If the field is filled in, the `capabilities` and `properties` parameters are ignored.	No
error_message	String	Extended human-readable description of a possible error. Available only on the Testing tab of the developer console.	No

capabilities object

Parameter	Type	Description	Required
<capability1>	Object	Capability and its status. For more information about the list of available capabilities and their parameters, see About capabilities.	No
<capability2>	Object	Capability and its status. For more information about the list of available capabilities and their parameters, see About capabilities.	No

properties object

Parameter	Type	Description	Required
<property1>	Object	Property and its status. For more information about the list of available properties and their parameters, see About properties.	No
<property2>	Object	Property and its status. For more information about the list of available properties and their parameters, see About properties.	No

Codes associated with the request

HTTP/1.1 404 Not Found

Global codes

Example

This example describes the properties of a lamp featuring color and outlet control.

Request

Response successful

Response with error

curl -i -X POST 'https://example.com/v1.0/user/devices/query' \
-H 'Authorization: Bearer 123qwe456a...' \
-H 'X-Request-Id: ff36a3cc-ec...' \
-H 'Content-Type: application/json'

Request body

{
    "devices": [
        {
            "id": "abc-123",
            "custom_data": {
              "foo": 1,
              "bar": "two",
              "baz": false,
              "qux": [1, "two", false],
              "quux": {
                "quuz": {
                  "corge": []
                }
              }
            }
        },
        {
            "id": "sock-56GF-3"
        }
    ]
}

{
    "request_id": "ff36a3cc-ec34-11e6-b1a0-64510650abcf",
    "payload": {
        "devices": [{
            "id": "abc-123",
            "capabilities": [{
                "type": "devices.capabilities.color_setting",
                "state": {
                    "instance": "hsv",
                    "value": {
                        "h": 255,
                        "s": 50,
                        "v": 100
                    }
                }
            }, {
                "type": "devices.capabilities.on_off",
                "state": {
                    "instance": "on",
                    "value": true
                }
            }]
        },
        {
            "id": "abc-123",
            "error_code": "DEVICE_NOT_FOUND",
            "error_message": "the human readable error message"
        },
        {
            "id": "sock-56GF-3",
            "capabilities": [{
                "type": "devices.capabilities.on_off",
                "state": {
                    "instance": "on",
                    "value": true
                }
            }]
        }]
    }
}

HTTP/1.1 404 Not Found

Information about the states of user devices

Smart home platform request formatSmart home platform request format

Request headersRequest headers

Request body formatRequest body format

Provider response formatProvider response format

ExampleExample

Was the article helpful?

Smart home platform request format

Request headers

Request body format

Provider response format

Example