The SmartThings REST API provides programmatic access to the SmartThings platform for controlling connected devices, creating automations, managing locations, and building smart home integrations. Supports OAuth 2.0 and personal access tokens. Base URL: https://api.smartthings.com/v1.
openapi: 3.0.3
info:
title: Samsung SmartThings API
description: >-
The SmartThings REST API provides programmatic access to the SmartThings
platform for controlling connected devices, creating automations, managing
locations, rooms, scenes, and building smart home integrations. Supports
OAuth 2.0 Bearer tokens and personal access tokens. Base URL:
https://api.smartthings.com/v1.
version: 1.0.0
contact:
name: SmartThings Developer Support
url: https://developer.smartthings.com/
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: https://api.smartthings.com/v1
description: SmartThings REST API
tags:
- name: Devices
description: Connected device management and control.
- name: Locations
description: Location and room management.
- name: Scenes
description: Scene activation and management.
- name: Rules
description: Automation rule management.
- name: Subscriptions
description: Device event subscriptions.
- name: Apps
description: SmartApp registration and management.
paths:
/devices:
get:
operationId: listDevices
summary: List Devices
description: >-
Returns a list of devices accessible to the authenticated user, optionally
filtered by location, capability, or device type.
tags:
- Devices
parameters:
- name: locationId
in: query
required: false
description: Filter devices by location ID.
schema:
type: string
format: uuid
- name: capabilityId
in: query
required: false
description: Filter devices by SmartThings capability (e.g., switch, lock).
schema:
type: string
- name: deviceId
in: query
required: false
description: Filter by specific device IDs (repeatable).
schema:
type: array
items:
type: string
- name: max
in: query
required: false
description: Maximum number of devices to return (max 200).
schema:
type: integer
maximum: 200
- name: pageToken
in: query
required: false
description: Cursor token for pagination.
schema:
type: string
responses:
"200":
description: List of devices.
content:
application/json:
schema:
type: object
properties:
items:
type: array
items:
$ref: "#/components/schemas/Device"
_links:
$ref: "#/components/schemas/Links"
"401":
description: Unauthorized.
"403":
description: Forbidden.
/devices/{deviceId}:
get:
operationId: getDevice
summary: Get Device
description: Returns details for a specific device by its ID.
tags:
- Devices
parameters:
- $ref: "#/components/parameters/DeviceIdParam"
responses:
"200":
description: Device details.
content:
application/json:
schema:
$ref: "#/components/schemas/Device"
"401":
description: Unauthorized.
"404":
description: Device not found.
delete:
operationId: deleteDevice
summary: Delete Device
description: Deletes a device from the SmartThings platform.
tags:
- Devices
parameters:
- $ref: "#/components/parameters/DeviceIdParam"
responses:
"200":
description: Device deleted.
"401":
description: Unauthorized.
"403":
description: Forbidden.
"404":
description: Device not found.
/devices/{deviceId}/status:
get:
operationId: getDeviceStatus
summary: Get Device Status
description: >-
Returns the full status of all components and capabilities for a device,
including current attribute values.
tags:
- Devices
parameters:
- $ref: "#/components/parameters/DeviceIdParam"
responses:
"200":
description: Device status with component attribute values.
content:
application/json:
schema:
$ref: "#/components/schemas/DeviceStatus"
"401":
description: Unauthorized.
"404":
description: Device not found.
/devices/{deviceId}/commands:
post:
operationId: executeDeviceCommands
summary: Execute Device Commands
description: >-
Executes one or more commands on a device component. Commands invoke
capability command methods (e.g., switch.on, lock.lock, thermostat.setCoolingSetpoint).
tags:
- Devices
parameters:
- $ref: "#/components/parameters/DeviceIdParam"
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/DeviceCommandRequest"
examples:
TurnOn:
summary: Turn on a switch
value:
commands:
- component: main
capability: switch
command: on
Lock:
summary: Lock a lock
value:
commands:
- component: main
capability: lock
command: lock
responses:
"200":
description: Commands accepted for execution.
content:
application/json:
schema:
type: object
properties:
results:
type: array
items:
type: object
properties:
id:
type: string
status:
type: string
enum:
- ACCEPTED
- COMPLETED
- ERROR
"401":
description: Unauthorized.
"422":
description: Invalid command or capability.
/locations:
get:
operationId: listLocations
summary: List Locations
description: Returns all SmartThings locations accessible to the authenticated user.
tags:
- Locations
parameters:
- name: pageToken
in: query
required: false
description: Pagination cursor.
schema:
type: string
responses:
"200":
description: List of locations.
content:
application/json:
schema:
type: object
properties:
items:
type: array
items:
$ref: "#/components/schemas/Location"
_links:
$ref: "#/components/schemas/Links"
"401":
description: Unauthorized.
post:
operationId: createLocation
summary: Create Location
description: Creates a new SmartThings location.
tags:
- Locations
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/CreateLocationRequest"
responses:
"200":
description: Location created.
content:
application/json:
schema:
$ref: "#/components/schemas/Location"
"401":
description: Unauthorized.
"422":
description: Validation error.
/locations/{locationId}:
get:
operationId: getLocation
summary: Get Location
description: Returns details for a specific SmartThings location.
tags:
- Locations
parameters:
- $ref: "#/components/parameters/LocationIdParam"
responses:
"200":
description: Location details.
content:
application/json:
schema:
$ref: "#/components/schemas/Location"
"401":
description: Unauthorized.
"404":
description: Location not found.
put:
operationId: updateLocation
summary: Update Location
description: Updates a SmartThings location's properties.
tags:
- Locations
parameters:
- $ref: "#/components/parameters/LocationIdParam"
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/CreateLocationRequest"
responses:
"200":
description: Location updated.
content:
application/json:
schema:
$ref: "#/components/schemas/Location"
"401":
description: Unauthorized.
"404":
description: Location not found.
delete:
operationId: deleteLocation
summary: Delete Location
description: Deletes a SmartThings location and all associated devices and automations.
tags:
- Locations
parameters:
- $ref: "#/components/parameters/LocationIdParam"
responses:
"200":
description: Location deleted.
"401":
description: Unauthorized.
"404":
description: Location not found.
/locations/{locationId}/rooms:
get:
operationId: listRooms
summary: List Rooms
description: Returns all rooms within a SmartThings location.
tags:
- Locations
parameters:
- $ref: "#/components/parameters/LocationIdParam"
responses:
"200":
description: List of rooms.
content:
application/json:
schema:
type: object
properties:
items:
type: array
items:
$ref: "#/components/schemas/Room"
"401":
description: Unauthorized.
"404":
description: Location not found.
post:
operationId: createRoom
summary: Create Room
description: Creates a new room within a SmartThings location.
tags:
- Locations
parameters:
- $ref: "#/components/parameters/LocationIdParam"
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- name
properties:
name:
type: string
description: Room name.
responses:
"200":
description: Room created.
content:
application/json:
schema:
$ref: "#/components/schemas/Room"
"401":
description: Unauthorized.
/scenes:
get:
operationId: listScenes
summary: List Scenes
description: Returns all scenes for the authenticated user, optionally filtered by location.
tags:
- Scenes
parameters:
- name: locationId
in: query
required: false
description: Filter scenes by location ID.
schema:
type: string
format: uuid
responses:
"200":
description: List of scenes.
content:
application/json:
schema:
type: object
properties:
items:
type: array
items:
$ref: "#/components/schemas/Scene"
"401":
description: Unauthorized.
/scenes/{sceneId}/execute:
post:
operationId: executeScene
summary: Execute Scene
description: Activates a SmartThings scene, applying its saved device state configuration.
tags:
- Scenes
parameters:
- name: sceneId
in: path
required: true
description: Scene ID.
schema:
type: string
responses:
"200":
description: Scene execution initiated.
content:
application/json:
schema:
type: object
properties:
status:
type: string
example: success
"401":
description: Unauthorized.
"404":
description: Scene not found.
/rules:
get:
operationId: listRules
summary: List Rules
description: Returns all automation rules for the authenticated user.
tags:
- Rules
parameters:
- name: locationId
in: query
required: false
description: Filter rules by location ID.
schema:
type: string
format: uuid
- name: max
in: query
required: false
description: Maximum number of rules to return.
schema:
type: integer
- name: offset
in: query
required: false
description: Pagination offset.
schema:
type: integer
responses:
"200":
description: List of rules.
content:
application/json:
schema:
type: object
properties:
items:
type: array
items:
$ref: "#/components/schemas/Rule"
_links:
$ref: "#/components/schemas/Links"
"401":
description: Unauthorized.
post:
operationId: createRule
summary: Create Rule
description: Creates a new SmartThings automation rule with trigger conditions and actions.
tags:
- Rules
parameters:
- name: locationId
in: query
required: true
description: Location ID where the rule will be created.
schema:
type: string
format: uuid
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/CreateRuleRequest"
responses:
"200":
description: Rule created.
content:
application/json:
schema:
$ref: "#/components/schemas/Rule"
"401":
description: Unauthorized.
"422":
description: Validation error.
/rules/{ruleId}:
get:
operationId: getRule
summary: Get Rule
description: Returns details for a specific automation rule.
tags:
- Rules
parameters:
- $ref: "#/components/parameters/RuleIdParam"
- name: locationId
in: query
required: true
description: Location ID of the rule.
schema:
type: string
format: uuid
responses:
"200":
description: Rule details.
content:
application/json:
schema:
$ref: "#/components/schemas/Rule"
"401":
description: Unauthorized.
"404":
description: Rule not found.
put:
operationId: updateRule
summary: Update Rule
description: Updates an existing SmartThings automation rule.
tags:
- Rules
parameters:
- $ref: "#/components/parameters/RuleIdParam"
- name: locationId
in: query
required: true
description: Location ID of the rule.
schema:
type: string
format: uuid
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/CreateRuleRequest"
responses:
"200":
description: Rule updated.
content:
application/json:
schema:
$ref: "#/components/schemas/Rule"
"401":
description: Unauthorized.
"404":
description: Rule not found.
delete:
operationId: deleteRule
summary: Delete Rule
description: Deletes a SmartThings automation rule.
tags:
- Rules
parameters:
- $ref: "#/components/parameters/RuleIdParam"
- name: locationId
in: query
required: true
description: Location ID of the rule.
schema:
type: string
format: uuid
responses:
"200":
description: Rule deleted.
"401":
description: Unauthorized.
"404":
description: Rule not found.
/subscriptions:
get:
operationId: listSubscriptions
summary: List Subscriptions
description: Returns all event subscriptions for the authenticated app.
tags:
- Subscriptions
parameters:
- name: installedAppId
in: query
required: false
description: Filter subscriptions by installed app ID.
schema:
type: string
responses:
"200":
description: List of subscriptions.
content:
application/json:
schema:
type: object
properties:
items:
type: array
items:
$ref: "#/components/schemas/Subscription"
"401":
description: Unauthorized.
post:
operationId: createSubscription
summary: Create Subscription
description: >-
Creates an event subscription to receive device capability events, location
mode changes, or scene lifecycle events for a SmartApp.
tags:
- Subscriptions
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/CreateSubscriptionRequest"
responses:
"200":
description: Subscription created.
content:
application/json:
schema:
$ref: "#/components/schemas/Subscription"
"401":
description: Unauthorized.
"422":
description: Validation error.
/subscriptions/{subscriptionId}:
delete:
operationId: deleteSubscription
summary: Delete Subscription
description: Removes an event subscription.
tags:
- Subscriptions
parameters:
- name: subscriptionId
in: path
required: true
description: Subscription ID.
schema:
type: string
responses:
"200":
description: Subscription deleted.
"401":
description: Unauthorized.
"404":
description: Subscription not found.
/apps:
get:
operationId: listApps
summary: List Apps
description: Returns all SmartApps registered to the authenticated account.
tags:
- Apps
responses:
"200":
description: List of apps.
content:
application/json:
schema:
type: object
properties:
items:
type: array
items:
$ref: "#/components/schemas/App"
"401":
description: Unauthorized.
/apps/{appId}:
get:
operationId: getApp
summary: Get App
description: Returns details for a specific SmartApp.
tags:
- Apps
parameters:
- name: appId
in: path
required: true
description: App ID or app name.
schema:
type: string
responses:
"200":
description: App details.
content:
application/json:
schema:
$ref: "#/components/schemas/App"
"401":
description: Unauthorized.
"404":
description: App not found.
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: >-
OAuth 2.0 Bearer token or SmartThings personal access token.
Obtain tokens at https://account.smartthings.com/tokens.
parameters:
DeviceIdParam:
name: deviceId
in: path
required: true
description: Unique device identifier (UUID).
schema:
type: string
format: uuid
LocationIdParam:
name: locationId
in: path
required: true
description: Unique location identifier (UUID).
schema:
type: string
format: uuid
RuleIdParam:
name: ruleId
in: path
required: true
description: Unique rule identifier.
schema:
type: string
schemas:
Device:
type: object
description: A SmartThings connected device.
properties:
deviceId:
type: string
format: uuid
description: Unique device identifier.
name:
type: string
description: Device display name.
label:
type: string
description: User-assigned device label.
manufacturerName:
type: string
description: Manufacturer name.
presentationId:
type: string
description: Device presentation identifier.
locationId:
type: string
format: uuid
description: Location ID this device belongs to.
roomId:
type: string
format: uuid
description: Room ID this device is assigned to.
ownerId:
type: string
description: Owner user ID.
type:
type: string
description: Device integration type.
enum:
- ENDPOINT_APP
- DTH
- MOBILE
- VIPER
- MATTER
- LAN
- BLE
- ZWave
- Zigbee
- HUB
components:
type: array
description: Functional sub-units of the device (main, sub).
items:
$ref: "#/components/schemas/DeviceComponent"
DeviceComponent:
type: object
description: A functional component of a SmartThings device.
properties:
id:
type: string
description: Component ID (e.g., main, sub).
label:
type: string
description: Human-readable component label.
capabilities:
type: array
description: Capabilities this component supports.
items:
type: object
properties:
id:
type: string
description: Capability ID (e.g., switch, lock).
version:
type: integer
description: Capability version.
categories:
type: array
description: Device category classifications.
items:
type: object
properties:
name:
type: string
description: Category name.
categoryType:
type: string
enum:
- manufacturer
- user
DeviceStatus:
type: object
description: Full status of all device components and capability attributes.
properties:
components:
type: object
description: >-
Map of component IDs to capability status objects. Each capability
contains attribute name/value pairs with timestamps.
additionalProperties:
type: object
additionalProperties:
type: object
properties:
value:
description: Current attribute value.
unit:
type: string
description: Unit of measurement (if applicable).
timestamp:
type: string
format: date-time
description: Timestamp of last update.
DeviceCommandRequest:
type: object
required:
- commands
properties:
commands:
type: array
description: List of commands to execute.
items:
type: object
required:
- component
- capability
- command
properties:
component:
type: string
description: Component ID (e.g., main).
capability:
type: string
description: Capability ID (e.g., switch, lock).
command:
type: string
description: Command name (e.g., on, off, lock, unlock).
arguments:
type: array
description: Command arguments.
items: {}
Location:
type: object
description: A SmartThings location (home, office, etc.).
properties:
locationId:
type: string
format: uuid
description: Unique location identifier.
name:
type: string
description: Location name.
countryCode:
type: string
description: ISO 3166-1 alpha-3 country code.
latitude:
type: number
format: double
description: Location latitude.
longitude:
type: number
format: double
description: Location longitude.
regionRadius:
type: integer
description: Geofence radius in meters.
temperatureScale:
type: string
enum:
- F
- C
description: Temperature unit preference.
timeZoneId:
type: string
description: IANA time zone ID (e.g., America/Chicago).
locale:
type: string
description: BCP 47 locale tag.
CreateLocationRequest:
type: object
required:
- name
properties:
name:
type: string
description: Location name.
countryCode:
type: string
description: ISO 3166-1 alpha-3 country code.
latitude:
type: number
format: double
longitude:
type: number
format: double
regionRadius:
type: integer
description: Geofence radius in meters.
temperatureScale:
type: string
enum:
- F
- C
timeZoneId:
type: string
description: IANA time zone ID.
locale:
type: string
Room:
type: object
description: A room within a SmartThings location.
properties:
roomId:
type: string
format: uuid
description: Unique room identifier.
locationId:
type: string
format: uuid
description: Location this room belongs to.
name:
type: string
description: Room name.
backgroundImage:
type: string
description: Room background image URL.
Scene:
type: object
description: A SmartThings scene (saved device state configuration).
properties:
sceneId:
type: string
description: Unique scene identifier.
sceneName:
type: string
description: Scene name.
sceneIcon:
type: string
description: Scene icon identifier.
sceneColor:
type: string
description: Scene color theme.
locationId:
type: string
format: uuid
description: Location this scene belongs to.
createdBy:
type: string
description: User ID who created the scene.
createdDate:
type: string
format: date-time
description: Scene creation timestamp.
lastUpdatedDate:
type: string
format: date-time
description: Scene last updated timestamp.
lastExecutedDate:
type: string
format: date-time
description: Timestamp of last scene execution.
Rule:
type: object
description: A SmartThings automation rule.
properties:
id:
type: string
description: Unique rule identifier.
name:
type: string
description: Rule name.
actions:
type: array
description: Actions to execute when rule conditions are met.
items: {}
timeZoneId:
type: string
description: IANA time zone for time-based conditions.
executionLocation:
type: string
description: Where the rule executes.
enum:
- Cloud
- Local
ownerId:
type: string
description: Owner user ID.
CreateRuleRequest:
type: object
required:
- name
- actions
properties:
name:
type: string
description: Rule name.
actions:
type: array
description: Rule action definitions.
items: {}
timeZoneId:
type: string
description: IANA time zone for time-based conditions.
Subscription:
type: object
description: A SmartThings event subscription for a SmartApp.
properties:
id:
type: string
description: Unique subscription identifier.
installedAppId:
type: string
format: uuid
description: Installed SmartApp ID.
sourceType:
type: string
description: Event source type.
enum:
- CAPABILITY
- DEVICE
- MODE
- TIMER
- SCENE_LIFECYCLE
- DEVICE_LIFECYCLE
device:
type: object
description: Device capability subscription details.
properties:
deviceId:
type: string
description: Device ID to subscribe to (or * for all).
componentId:
type: string
description: Component ID (or * for all).
capability:
type: string
description: Capability ID.
attribute:
type: string
description: Attribute name (or * for all).
value:
description: Attribute value filter.
stateChangeOnly:
type: boolean
description: Only trigger on attribute state changes.
CreateSubscriptionRequest:
type: object
required:
- sourceType
properties:
sourceType:
type: string
enum:
- CAPABILITY
- DEVICE
- MODE
- TIMER
- SCENE_LIFECYCLE
- DEVICE_LIFECYCLE
device:
type: object
properties:
deviceId:
type: string
componentId:
type: string
capability:
type: string
attribute:
type: string
stateChangeOnly:
type: boolean
App:
type: object
description: A SmartThings SmartApp.
properties:
appId:
type: string
format: uuid
description: Unique app identifier.
appName:
type: string
description: App identifier name.
displayName:
type: string
description: Human-readable app name.
description:
type: string
description: App description.
singleInstance:
type: boolean
description: Whether app allows only one installed instance.
appType:
type: string
description: App type.
enum:
- WEBHOOK_SMART_APP
- LAMBDA_SMART_APP
- API_ONLY
principalType:
type: string
description: Authentication principal type.
enum:
# --- truncated at 32 KB (32 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/samsung/refs/heads/main/openapi/samsung-smartthings-openapi.yml