Working with Rules

The Rules API enables the developer to create automations, both simple and complex, that can operate on the SmartThings cloud. In a future release of the API, local execution of rules on the SmartThings hub will be supported, making rules a great choice for those looking to create fast, stable and secure automations.

Using the Rules API the developer can create automations such as:

  • Turning on all your lights when your door opens
  • Turning off all your lights at a certain time of day
  • Changing your location mode to away when all presence detection devices are not present

With this quick overview we will provide you with the basics for creating your first rules. Please take a look at Rules Breakdown to get a more in depth look at how rules work and the possibilities unlocked with the API.

Interaction with the SmartThings Cloud

  • Use the Rules API to work with Rules.

  • Personal access tokens require Rules scopes. See Authorization and Permissions.

  • Rate limits and guardrails apply for Rules. Also note that Rules are subject to the same rate limits that Apps are. See Rate Limits

Example with Postman

For this example we will create an automation that will turn off a light if we change our location mode to Night or it will turn the light on if we set our location mode to Home or Away. Make sure you have a bulb paired to the SmartThings Hub in your account or a virtual device created for this test. You will also need to obtain the device id for the device you will use in this rule. In this example we will use the Rules API to create the automation.

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.

Make sure that you select Rules > Read all rules, Rules > Write all rules, Rules > Execute all rules, Devices > Read devices and Locations > Read locations for Authorized Scopes.

Obtain device id's, location id and location mode id's for use in Rules

  • In Postman make a request to the Devices API to get a list of devices and their id's.

  • In Postman make a request to the Location API to get a list of locations and a location id.

  • In Postman make a request to the Location API to get a list of the location modes.

Create a Rule

To create a Rule with Postman, send a POST request to https://api.smartthings.com/v1/behaviors?locationId=C955F1C2-CE6B-49CA-99B7-B28B7FC493C6.

  • Start Postman. In the Authorization section of the Postman window, 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 generated above.

Post Rule Auth

  • In the Postman window, select POST and type in the following url: https://api.smartthings.com/v1/behaviors?locationId=C955F1C2-CE6B-49CA-99B7-B28B7FC493C6.

  • In the Postman window, select Body and then click raw and then to the right select JSON from the drop down.

Here is our POST request body to create a rule that will turn off a light if our location mode is changed to Night, otherwise it will turn the light on if the location mode is changed to any other state (by default this would be Home and Away).

{
    "name": "Control lights when location mode changes.",
    "actions": [{
        "if": {
            "equals": {
                "left": {
                    "location": {
                        "attribute": "Mode"
                    }
                },
                "right": {
                    "string": "a89a6ad7-929f-4f64-b0ce-8bdf83026982"
                }
            },
            "then": [{
                "command": {
                    "devices": [
                        "d89a6ad7-929f-4f64-b0ce-8bdf83026984"
                    ],
                    "commands": [{
                        "component": "main",
                        "capability": "switch",
                        "command": "off"
                    }]
                }
            }],
            "else": [{
                "command": {
                    "devices": [
                        "d89a6ad7-929f-4f64-b0ce-8bdf83026984"
                    ],
                    "commands": [{
                        "component": "main",
                        "capability": "switch",
                        "command": "on"
                    }]
                }
            }]
        }
    }]
}

Post Rule

With our new Rule created via the Rules API SmartThings will automatically turn on or off your light depending on the current setting of your location mode.

Get the list of created Rules

To see the rules that you have created via the Rules API, again using Postman, send a GET request to https://api.smartthings.com/v1/behaviors?locationId=C955F1C2-CE6B-49CA-99B7-B28B7FC493C6.

  • Start Postman. In the Authorization section of the Postman window, 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 generated above.

  • In the Postman window, select GET and type in the SmartThings API https://api.smartthings.com/v1/behaviors?locationId=C955F1C2-CE6B-49CA-99B7-B28B7FC493C6.

Get Rules

Execute Rules

  • For complex rules it may be helpful to execute the rule manually to ensure that it is performing as expected. In this case the execute api can be used to trigger your rule instead of waiting for an event to trigger the rule automatically.

To execute the rule you created via the Rules API get it's id by sending a GET request to https://api.smartthings.com/v1/behaviors?locationId=C955F1C2-CE6B-49CA-99B7-B28B7FC493C6

  • In the Postman window, select POST and type in the SmartThings API url: https://api.smartthings.com/v1/behaviors/execute/:behaviorId?locationId=C955F1C2-CE6B-49CA-99B7-B28B7FC493C6.

Execute Rules