OpenAPI Specification
openapi: 3.0.3
info:
title: Samsung SmartThings Apps Devices 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
security:
- BearerAuth: []
tags:
- name: Devices
description: Connected device management and control.
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: true
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.
components:
schemas:
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: {}
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.
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'
Links:
type: object
description: Pagination links.
properties:
next:
type: object
properties:
href:
type: string
description: URL to the next page.
previous:
type: object
properties:
href:
type: string
description: URL to the previous page.
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
parameters:
DeviceIdParam:
name: deviceId
in: path
required: true
description: Unique device identifier (UUID).
schema:
type: string
format: uuid
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.