Manage devices

Use the Devices API to access devices integrated with SmartThings Cloud.

List devices

Below is an example of a JSON payload response that is returned from SmartThings Cloud for a GET request with /devices path.

{
  "items": [
    {
      "deviceId": "6f5ea629-4c05-4a90-a244-cc129b0a80c3",
      "name": "Kitchen fridge",
      "deviceManufacturerCode": "010F-0B01-2002",
      "locationId": "0c0b935d-0616-4441-a0bf-da7aeec3dc0a",
      "components": [
        {
          "id": "main"
        }
      ],
      "app": {
        "installedAppId": "0c0b935d-0616-4441-a0bf-da7aeec3dc0a",
        "externalId": "Th13390",
        "profile": {
          "id": "user@example.com/thermostat.model1"
        }
      },
      "dth": {
      },
      "type": "ENDPOINT_APP"
    }
  ],
  "_links": {
    "next": {
      "href": "https://..."
    },
    "previous": {
      "href": "https://..."
    }
  }
}

Get a device's description

Here is an example of a JSON payload response that is returned from SmartThings Cloud for a GET request with /devices/{deviceId} path.

{
  "deviceId": "6f5ea629-4c05-4a90-a244-cc129b0a80c3",
  "name": "color.light.100x",
  "label": "color.light.100x",
  "deviceManufacturerCode": "010F-0B01-2002",
  "locationId": "0c0b935d-0616-4441-a0bf-da7aeec3dc0a",
  "components": [
    {
      "id": "main",
      "capabilities": [
        {
          "id": "switch"
        }
      ]
    }
  ],
  "app": {
    "installedAppId": "0c0b935d-0616-4441-a0bf-da7aeec3dc0a",
    "externalId": "Th13390",
    "profile": {
      "id": "user@example.com/thermostat.model1"
    }
  },
  "dth": {

  },
  "type": "ENDPOINT_APP"
}

Get the full state of a device

An example of a JSON payload response that is returned from SmartThings Cloud for a GET request with /devices/{deviceId}/states path.

{
  "main": {
    "switch": {
      "value": "on"
    },
    "temperature": {
      "value": 10,
      "unit": "°C"
    }
  }
}

List the components of a device

An example of a JSON payload response that is returned from SmartThings Cloud for a GET request with /devices/{deviceId}/components path.

{
  "items": [
    {
      "id": "main",
      "capabilities": [
        {
          "id": "switch"
        }
      ]
    }
  ],
  "_links": {
    "next": {
      "href": "https://..."
    },
    "previous": {
      "href": "https://..."
    }
  }
}

Get a component's details

An example of a JSON payload response that is returned from SmartThings Cloud for a GET request with /devices/{deviceId}/components/{componentId} path.

{
  "id": "main",
  "capabilities": [
    {
      "id": "switch"
    }
  ]
}

Get a component's state

An example of a JSON payload response that is returned from SmartThings Cloud for a GET request with /devices/{deviceId}/components/{componentId}/states path.

{
  "switch": {
    "value": "on"
  }
}

Get the state of a capability

An example of a JSON payload response that is returned from SmartThings Cloud for a GET request with /devices/{deviceId}/components/{componentId}/capabilities/{capabilityId}/states path.

{
  "switch": {
    "value": "on"
  }
}

Example with Postman

You can use Postman app for accessing and updating your devices using SmartThings API.

In the example below we will use Postman to get a list of all the devices for a user account, and actuate and update a device. Make sure that you have at least one device in your SmartThings user account and follow the steps below:

Install Postman

Install the Postman app and create a Postman account for yourself (a free account is sufficient for this example).

Obtain SmartThings personal access token

  • If you don't have it already, open your Samsung account.

  • Next, get a personal access token for calling the SmartThings API. You will use this as a bearer token in the Postman app.

Go to the personal access tokens page and click on the Generate new token on top-right.

Create a token

Give a name for your token. Select Devices to authorize the scope of the token for the devices. Click on Generate Token in the bottom right.

Select devices

This will generate a token, as shown below (token display hidden in the pictures below). Copy the token and save it somewhere safe and private.

Display token

Get a list of devices

  • In the Postman window, select GET and type in the SmartThings API https://api.smartthings.com/v1/devices.

  • In the Authorization section, for the TYPE field, select Bearer Token from the drop-down menu list. This will display the Token form field on the right. Copy and paste here the personal access token that you obtained from above.

Get devices list

  • Click Send in the top right.

The response from SmartThings Cloud will be seen in the bottom half of the Postman window. SmartThings Cloud will respond with a JSON body containing a list of devices, as shown in the picture below.

ST response devices list

Get the description of a specific device

For any device in the above list of devices, using the deviceId of that device, we can get a full description of that device.

  • For any device of your choice from the above list in the JSON response body, copy the value of the deviceId.

  • In the Postman window, select GET and type in the SmartThings API https://api.smartthings.com/v1/devices/{PASTE THE DEVICEID} as shown below.

Get device description

  • Click Send in the top right. You will get a detailed description of the device in the same response window of the Postman app.

Execute commands on the device

To actuate a device you need to send a POST request to the https://api.smartthings.com/v1/devices/{deviceId}/commands API with the device command in the body of the request.

  • In the Postman window, select POST and type in the SmartThings API https://api.smartthings.com/v1/devices/{PASTE THE DEVICEID}/commands.

  • In the Body section of the Postman request window, select raw option, and JSON (application/json) from the pull down menu, as shown below.

Execute ON device command

  • Type in the JSON command body. In this example, the below device command to turn ON a Sylvania Smart bulb is issued:
{
"commands": [
    {
        "component": "main",
        "capability": "switch",
        "command": "on"
    }
]
}
  • Click Send in the top right. This will turn ON the Sylvania bulb.

Update a device

You can change the properties of a device with the PUT request to the SmartThings API https://api.smartthings.com/v1/devices/{deviceId}.

  • In the Postman window, select PUT and type in the SmartThings API https://api.smartthings.com/v1/devices/{PASTE THE DEVICEID}.

  • In the Body section of the Postman request window, select raw option, and JSON (application/json) from the pull down menu, as shown below.

Update device

  • Type in the JSON command body. In this example, the label property of the Sylvania bulb is changed to New Bulb.
{
    "label": "NEW Bulb"
}
  • Click Send in the top right. This will change the label of the Sylvania bulb. This is confirmed by pull-down refreshing the My Home screen of the SmartThings app.