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: - LOCATION - USER_LEVEL createdDate: type: string format: date-time description: App creation timestamp. lastUpdatedDate: type: string format: date-time description: App last updated timestamp. 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. security: - BearerAuth: []