Control Devices

Your app can control devices by sending commands through the SmartThings API. Commands are sent to a specific device and target a capability on a component.

Send a Command

To execute a command on a device, send a POST request to the device's commands endpoint.

tip

For a complete list of capability attributes and commands, visit the Production Capabilities reference.

Request

POST https://api.smartthings.com/v1/devices/{deviceId}/commands HTTP/1.1
Content-Type: application/json;charset=utf-8
Accept: application/json
Authorization: Bearer {access_token}

{
 "commands": [
   {
     "component": "main",
     "capability": "switch",
     "command": "off",
     "arguments": []
   }
 ]
}

Request Body Fields

Field	Description
commands	Array of commands to execute on the device
commands[].componentId	The component to target (e.g. main, outlet1)
commands[].capability	The capability the command belongs to (e.g. switch)
commands[].command	The command to execute (e.g. on, off for the switch capability)
commands[].arguments	Array of arguments for the command (empty for commands that take no arguments)

You can send multiple commands in a single request by including multiple entries in the commands array.

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
 "results": [
   {
     "id": "5eb69bcf-1405-4c4a-8a32-0c3ed42ac357",
     "status": "ACCEPTED"
   }
 ]
}

Response Fields

Field	Description
results	Array of results, one per command
results[].id	Unique identifier for the command execution
results[].status	ACCEPTED means the command was queued for execution

important

A status of ACCEPTED means SmartThings has received the command and will attempt to execute it on the device. It does not mean the command has completed. The actual state change happens asynchronously.

Confirming State Changes

If your app has an active subscription for the capability, SmartThings will send a device event to your webhook once the command has been executed and the device state has changed.

For example, after sending a switch off command, your webhook receives an event confirming the switch value changed to off:

{
 "deviceId": "b9af18af-55c8-4441-83e2-bfe6021235c4",
 "componentId": "main",
 "capability": "switch",
 "attribute": "switch",
 "value": "off",
 "stateChange": true,
 "subscriptionName": "switchHandler"
}

This event-driven pattern allows your app to update its UI only when the state has actually changed on the platform, rather than assuming the command succeeded.

Common Switch Commands

The switch capability supports two commands:

Command	Arguments	Description
on	none	Turn the switch on
off	none	Turn the switch off

Other capabilities have their own commands. For example, the switchLevel capability has a setLevel command that takes a level argument (0-100).

Controlling Multiple Devices

To control multiple devices (e.g. turning all switches off), send separate command requests for each device. These requests can be made in parallel for better performance.

Sending Multiple Commands in the Same Request

Multiple commands can be sent to the same device in a single request by including multiple entries in the commands array.

This is useful for controlling multiple capabilities or components of the same device at once. Device responses will typically be faster and more reliable when sending multiple commands in the same request, as it reduces the number of API calls and allows the device to optimize command execution.

Request

This example turns on a light, sets its level to 50%, and changes its color to light blue in a single request:

POST https://api.smartthings.com/v1/devices/{deviceId}/commands HTTP/1.1
Content-Type: application/json;charset=utf-8
Accept: application/json
Authorization: Bearer {access_token}

{
  "commands": [
    {
      "component": "main",
      "capability": "switch",
      "command": "on",
      "arguments": []
    },
    {
      "component": "main",
      "capability": "switchLevel",
      "command": "setLevel",
      "arguments": [50]
    },
    {
      "component": "main",
      "capability": "colorControl",
      "command": "setColor",
      "arguments": [
        {
          "hue": 60,
          "saturation": 100
        }
      ]
    }
  ]
}

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "results": [
    {
      "id": "76dde3e9-1a40-430f-ab49-d0943e7ea788",
      "status": "ACCEPTED"
    },
    {
      "id": "492877d5-18ca-4177-b89c-f4699d6d18c8",
      "status": "ACCEPTED"
    },
    {
      "id": "218faea8-89cb-4e38-af10-e8f59d24101d",
      "status": "ACCEPTED"
    }
  ]
}