Skip to content

Instantly share code, notes, and snippets.

@jimmyjames
Last active April 2, 2018 15:04
Show Gist options
  • Save jimmyjames/6250a8ab65dae247ab3de08582c25851 to your computer and use it in GitHub Desktop.
Save jimmyjames/6250a8ab65dae247ab3de08582c25851 to your computer and use it in GitHub Desktop.
info:
title: Device API
description: Device API.
version: v20170916.0.1.385-SNAPSHOT-PREVIEW
schemes:
- https
basePath: /
produces:
- application/json
securityDefinitions:
Bearer:
description: |
SmartThings resources are protected with HTTP Bearer authentication and OAuth2 scopes.
type: oauth2
authorizationUrl: https://auth-global.api.smartthings.com
flow: implicit
scopes:
mobile: A user token
service: A service token
r:installedapps:*: |
Read details about installed SmartApps, such as which devices have been configured for the installation. For SmartApp tokens, the scope is restricted to the location the SmartApp is installed into. For personal access tokens, the scope is limited to the account associated with the token.
l:installedapps: |
View a list of installed SmartApps. For SmartApp tokens, the scope is restricted to the location the SmartApp is installed into. For personal access tokens, the scope is limited to the account associated with the token.
w:installedapps:*: |
Create, update, or delete installed SmartApps. For SmartApp tokens, the scope is restricted to the location the SmartApp is installed into. For personal access tokens, the scope is limited to the account associated with the token.
r:apps:*: |
Read details about a SmartApp. Only applicable for personal access tokens, and the scope is limited to the SmartApps associated with the token's account.
w:apps:*: |
Create, update, or delete SmartApps. For SmartApp tokens, the scope is restricted to the location the SmartApp is installed into. For personal access tokens, the scope is limited to the account associated with the token.
l:devices: |
View a list of devices. For SmartApp tokens, the scope is restricted to the location the SmartApp is installed into. For personal access tokens, the scope is limited to the account associated with the token.
r:devices:*: |
Read details about a device, including device attribute state. For SmartApp tokens, the scope is restricted to the location the SmartApp is installed into. For personal access tokens, the scope is limited to the account associated with the token. This scope is required to create subscriptions.
w:devices:*: |
Update details such as the device name, or delete a device. For SmartApp tokens, the scope is restricted to the location the SmartApp is installed into. For personal access tokens, the scope is limited to the account associated with the token.
x:devices:*: |
Execute commands on a device. For SmartApp tokens, the scope is restricted to the location the SmartApp is installed into. For personal access tokens, the scope is limited to the account associated with the token.
r:deviceprofiles: |
View details of device profiles associated with the account. Only applicable for personal access tokens.
w:deviceprofiles: |
Create, update, or delete device profiles. Only applicable to personal access tokens, and the device profile must be owned by the same account associated with the token.
i:deviceprofiles: Create devices of the type associated with the device profile.
Only applicable for SmartApp tokens, and is requires the device profile and
the SmartApp have the same account owner.
l:scenes: |
View a list of scenes. For personal access tokens, the scope is limited to the account associated with the token.
r:scenes:*: |
Read details about a scene. For personal access tokens, the scope is limited to the account associated with the token.
w:scenes:*: |
Create, update or delete a scene. For personal access tokens, the scope is limited to the account associated with the token.
x:scenes:*: |
Execute a scene. For personal access tokens, the scope is limited to the account associated with the token.
r:schedules: |
Read details of scheduled executions. For SmartApp tokens, the scope is restricted to the installed SmartApp. For personal access tokens, the scope is limited to the account associated with the token.
w:schedules: |
Create, update, or delete schedules. For SmartApp tokens, the scope is restricted to the installed SmartApp. For personal access tokens, the scope is limited to the account associated with the token.
l:locations: |
View a list of locations. Only applicable for personal access tokens, and the scope is limited to the account associated with the token.
r:locations:*: |
Read details of a location, such as geocoordinates and temperature scale. For SmartApp tokens, the scope is restricted to the installed SmartApp. For personal access tokens, the scope is limited to the account associated with the token.
w:locations:*: |
Create, update, and delete locations. Only applicable for personal access tokens.
l:hubs: List hubs.
r:hubs: Read hubs.
w:hubs: Write hubs.
hub: Basic hub access.
x:locations:*: |
Execute Mode changes on a location.
r:service:security:registration: Read security registration at the service level.
w:service:security:registration: Write security registration at the service
level.
w:security:locations:*:armstate: Read arm state in the given location.
w:security:locations:*:armaway: Arm away in the given location.
w:security:locations:*:armstay: Arm stay in the given location.
w:security:locations:*:disarm: Disarm in the given location.
r:security:locations:*:contact: Read an emergency contact for the given location.
w:security:locations:*:contact: Create an emergency contact for the given location.
w:security:locations:*:alarm: Send an alarm event for the given location.
service:accountsync: Invoke User account sync.
r:service:paid-services: Read paid services related to some entity at the service
level
Basic:
type: basic
responses:
notAuthenticated:
description: Not authenticated
notAuthorized:
description: Not authorized
notFound:
description: Not found
schema:
$ref: '#/definitions/ErrorResponse'
badRequest:
description: Bad request
schema:
$ref: '#/definitions/ErrorResponse'
unprocessableEntity:
description: Unprocessable Entity
schema:
$ref: '#/definitions/ErrorResponse'
tooManyRequests:
description: Too many requests
schema:
$ref: '#/definitions/ErrorResponse'
conflict:
description: Conflict
schema:
$ref: '#/definitions/ErrorResponse'
defaultResponse:
description: Unexpected error
schema:
$ref: '#/definitions/ErrorResponse'
parameters:
authorization:
name: Authorization
in: header
description: OAuth token
required: true
type: string
format: string
deviceId:
name: deviceId
in: path
type: string
required: true
description: the device ID
locationId:
name: locationId
description: The ID of the location.
in: path
type: string
required: true
format: ^(?:([0-9a-fA-F]{32})|([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}))$
installedAppId:
name: installedAppId
description: The ID of the installed application.
in: path
type: string
required: true
format: ^(?:([0-9a-fA-F]{32})|([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}))$
capabilityId:
name: capabilityId
in: path
type: string
required: true
componentId:
name: componentId
description: The name of the component.
in: path
type: string
required: true
format: ^[-_!.~'()*0-9a-zA-Z]{1,36}$
paths:
/devices:
get:
summary: List devices.
operationId: getDevices
description: Get a list of devices.
parameters:
- name: capability
in: query
type: array
collectionFormat: multi
required: false
items:
type: string
description: |
The device capabilities to filter the results by.
The capabilities are treated as an "and" so all capabilities must be present.
- name: locationId
in: query
type: array
collectionFormat: multi
required: false
items:
type: string
format: ^(?:([0-9a-fA-F]{32})|([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}))$
description: |
The device locations to filter the results by.
- name: deviceId
in: query
type: array
collectionFormat: multi
required: false
items:
type: string
format: ^(?:([0-9a-fA-F]{32})|([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}))$
description: |
The device ids to filter the results by.
- name: includeStatus
in: query
type: boolean
required: false
description: |
Include the status of the device's capabilities where permission is adequate to view them.
This requires `r:devices` permission.
security:
- Bearer:
- l:devices
- Bearer:
- r:devices:*
responses:
200:
description: A list of devices.
schema:
$ref: '#/definitions/PagedDevices'
401:
$ref: '#/responses/notAuthenticated'
403:
$ref: '#/responses/notAuthorized'
400:
$ref: '#/responses/badRequest'
429:
$ref: '#/responses/tooManyRequests'
default:
$ref: '#/responses/defaultResponse'
tags:
- devices
/devices/{deviceId}/commands:
parameters:
- $ref: '#/parameters/authorization'
- $ref: '#/parameters/deviceId'
post:
summary: Execute commands on device.
operationId: executeDeviceCommands
description: Execute commands on a device.
parameters:
- name: executeCapabilityCommand
in: body
required: true
schema:
$ref: '#/definitions/DeviceCommandsRequest'
security:
- Bearer:
- x:devices:*
responses:
200:
description: Created commands.
schema:
$ref: '#/definitions/CreateDeviceCommandsResponse'
401:
$ref: '#/responses/notAuthenticated'
403:
$ref: '#/responses/notAuthorized'
400:
$ref: '#/responses/badRequest'
422:
$ref: '#/responses/unprocessableEntity'
429:
$ref: '#/responses/tooManyRequests'
default:
$ref: '#/responses/defaultResponse'
tags:
- devices
/devices/{deviceId}/events:
parameters:
- $ref: '#/parameters/authorization'
- $ref: '#/parameters/deviceId'
post:
summary: Create Device Events.
operationId: createDeviceEvents
description: |
Create events for a device. When a device is managed by a SmartApp then it is responsible for creating events
to update the attributes of the device in the SmartThings platform.
The token must be for a SmartApp and it must be the SmartApp that created the Device.
parameters:
- name: deviceEventRequest
in: body
required: true
schema:
$ref: '#/definitions/DeviceEventsRequest'
security:
- Bearer:
- w:devices:*
- r:devices:*
responses:
200:
description: Created events.
schema:
$ref: '#/definitions/CreateDeviceEventsResponse'
401:
$ref: '#/responses/notAuthenticated'
403:
$ref: '#/responses/notAuthorized'
400:
$ref: '#/responses/badRequest'
422:
$ref: '#/responses/unprocessableEntity'
429:
$ref: '#/responses/tooManyRequests'
default:
$ref: '#/responses/defaultResponse'
tags:
- devices
/devices/{deviceId}/status:
parameters:
- $ref: '#/parameters/authorization'
- $ref: '#/parameters/deviceId'
get:
summary: Get the full status of a device.
operationId: getDeviceStatus
description: |
Get the current status of all of a device's component's attributes.
The results may be filtered if the requester only has permission to
view a subset of the device's components or capabilities.
If the token is for a SmartApp that created the device then it implicitly has permission for this api.
security:
- Bearer:
- r:devices:*
responses:
200:
description: successful return of current status of device attributes
schema:
$ref: '#/definitions/DeviceStatus'
401:
$ref: '#/responses/notAuthenticated'
403:
$ref: '#/responses/notAuthorized'
400:
$ref: '#/responses/badRequest'
429:
$ref: '#/responses/tooManyRequests'
default:
$ref: '#/responses/defaultResponse'
tags:
- devices
/devices/{deviceId}/components/{componentId}/status:
parameters:
- $ref: '#/parameters/authorization'
- $ref: '#/parameters/deviceId'
- $ref: '#/parameters/componentId'
get:
summary: Get a device component's status.
description: |
Get the status of all attributes of a the component.
The results may be filtered if the requester only has permission to view a subset of the component's capabilities.
If the token is for a SmartApp that created the device then it implicitly has permission for this api.
operationId: getDeviceComponentStatus
security:
- Bearer:
- r:devices:*
responses:
200:
description: Successful return current status of device component's attributes.
schema:
$ref: '#/definitions/ComponentStatus'
401:
$ref: '#/responses/notAuthenticated'
403:
$ref: '#/responses/notAuthorized'
400:
$ref: '#/responses/badRequest'
429:
$ref: '#/responses/tooManyRequests'
default:
$ref: '#/responses/defaultResponse'
tags:
- devices
/devices/{deviceId}/components/{componentId}/capabilities/{capabilityId}/status:
parameters:
- $ref: '#/parameters/authorization'
- $ref: '#/parameters/deviceId'
- $ref: '#/parameters/componentId'
- $ref: '#/parameters/capabilityId'
get:
summary: Get a capability's status.
operationId: getDeviceStatusByCapability
description: |
Get the current status of a device component's capability.
If the token is for a SmartApp that created the device then it implicitly has permission for this api.
security:
- Bearer:
- r:devices:*
responses:
200:
description: Successful return of current status of the attributes of a
device component's capability
schema:
$ref: '#/definitions/CapabilityStatus'
401:
$ref: '#/responses/notAuthenticated'
403:
$ref: '#/responses/notAuthorized'
400:
$ref: '#/responses/badRequest'
429:
$ref: '#/responses/tooManyRequests'
default:
$ref: '#/responses/defaultResponse'
tags:
- devices
definitions:
Link:
type: object
properties:
href:
type: string
description: An absolute URL linking to a resource.
example: https://...
Links:
type: object
properties:
next:
$ref: '#/definitions/Link'
previous:
$ref: '#/definitions/Link'
ErrorResponse:
type: object
properties:
requestId:
type: string
description: A correlation id used for reference when contacting support.
example: 7b8514e6-230d-41cc-b3c2-512bca15abf0
error:
$ref: '#/definitions/Error'
Error:
description: Details about the error.
type: object
properties:
code:
type: string
description: Machine readable error code.
example: ConstraintViolationError
message:
type: string
description: Human readable error message.
example: The request was malformed.
target:
type: string
description: Optional field used to point to a problamatic part of the request.
example: 31192dc9-eb45-4d90-b606-21e9b66d8c2b
details:
type: array
items:
$ref: '#/definitions/Error'
DeviceCommandsRequest:
type: object
properties:
commands:
description: An array of commands to execute on the Device.
type: array
items:
$ref: '#/definitions/DeviceCommand'
DeviceCommand:
type: object
properties:
component:
type: string
description: The name of the component on this device, default is 'main'.
The component must be valid for the device.
default: main
format: ^[-_!.~'()*0-9a-zA-Z]{1,36}$
capability:
description: Capability that this command relates to. This must be a capability
of the component.
type: string
command:
description: Name of the command, this must be valid for the capability.
type: string
arguments:
type: array
items:
type: object
description: |
Arguments of the command.
All the required arguments defined in the capability's command argument definition must be provided.
The type of the arguments are dependent on the type of the capability's command argument.
Please refer to the capabilities definition at https://smartthings.developer.samsung.com/develop/api-ref/capabilities.html
required:
- capability
- command
example:
component: main
capability: temperatureSetPoint
command: setTemperature
arguments:
- 5
DeviceEventsRequest:
type: object
properties:
deviceEvents:
description: An array of attribute state updates.
type: array
minItems: 1
maxItems: 8
items:
$ref: '#/definitions/DeviceStateEvent'
PagedDevices:
description: A paginated array of devices.
type: object
properties:
items:
type: array
items:
$ref: '#/definitions/Device'
_links:
$ref: '#/definitions/Links'
Device:
type: object
properties:
deviceId:
type: string
description: The identifier for the device instance.
example: 6f5ea629-4c05-4a90-a244-cc129b0a80c3
name:
type: string
description: The name that the device integration (Device Handler or SmartApp)
defines for the device.
example: color.light.100x
label:
type: string
description: The name that a user chooses for the device. This defaults to
the same value as name.
example: color.light.100x
deviceManufacturerCode:
type: string
description: The device manufacturer code.
example: 010F-0B01-2002
locationId:
type: string
format: ^(?:([0-9a-fA-F]{32})|([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}))$
description: The ID of the Location with which the device is associated.
example: 0c0b935d-0616-4441-a0bf-da7aeec3dc0a
components:
type: array
description: The IDs of all compenents on the device.
items:
$ref: '#/definitions/DeviceComponent'
app:
type: object
description: Device Profile information for a SmartApp. This field will be
empty if device type is not ENDPOINT_APP.
$ref: '#/definitions/AppDeviceDetails'
dth:
type: object
description: Device Profile information for DTH. This field will be empty
if device type is not DTH.
$ref: '#/definitions/DthDeviceDetails'
type:
$ref: '#/definitions/DeviceIntegrationType'
DeviceIntegrationType:
type: string
enum:
- DTH
- ENDPOINT_APP
default: DTH
description: |
The type of device integration.
If the type is DTH, the device implementation is a groovy Device Handler and the details are in the "dth" field.
If the type is ENDPOINT_APP, the device implementation is a SmartApp and the details are in the "app" field.
AppDeviceDetails:
type: object
properties:
installedAppId:
description: The ID of the installed app that integrates this device.
type: string
example: 0c0b935d-0616-4441-a0bf-da7aeec3dc0a
format: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
externalId:
type: string
description: A field to store an ID from a system external to SmartThings.
maxLength: 64
example: Th13390
profile:
$ref: '#/definitions/DeviceProfileReference'
DeviceProfileReference:
type: object
properties:
id:
type: string
description: The device profile Id
example: user@example.com/thermostat.model1
DthDeviceDetails:
type: object
properties:
deviceTypeId:
type: string
description: The identifier for the device's DeviceType.
format: ^(?:([0-9a-fA-F]{32})|([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}))$
example: 7b8514e6-230d-41cc-b3c2-512bca15abf0
deviceTypeName:
type: string
description: The name for the device's DeviceType.
example: x.com.samsung.da.fridge
deviceNetworkType:
type: string
description: The device network type.
example: ZWAVE
PagedDeviceComponents:
type: object
properties:
items:
type: array
items:
$ref: '#/definitions/DeviceComponent'
_links:
$ref: '#/definitions/Links'
DeviceComponent:
type: object
properties:
id:
type: string
example: main
format: ^[-_!.~'()*0-9a-zA-Z]{1,36}$
capabilities:
type: array
items:
$ref: '#/definitions/CapabilityReference'
CapabilityReference:
type: object
properties:
id:
type: string
example: switch
status:
$ref: '#/definitions/CapabilityStatus'
DeviceStatus:
description: The status of a Device.
type: object
properties:
components:
description: A map of componentId to Component status.
type: object
additionalProperties:
$ref: '#/definitions/ComponentStatus'
example:
main:
switch:
switch:
value: 'on'
switchLevel:
level:
value: 90
ComponentStatus:
description: A map of capabilityId to Capability status.
type: object
additionalProperties:
$ref: '#/definitions/CapabilityStatus'
example:
switch:
switch:
value: 'on'
switchLevel:
level:
value: 90
CapabilityStatus:
description: A map of Attribute name to Attribute state.
type: object
additionalProperties:
$ref: '#/definitions/AttributeState'
example:
switch:
value: 'on'
AttributeState:
type: object
properties:
value:
type: object
example: 0
unit:
type: string
example: °C
DeviceStateEvent:
type: object
properties:
component:
type: string
description: The name of the component on this device, default is 'main'.
capability:
type: string
description: Capability that this event relates to.
attribute:
type: string
description: Name of the capability attribute that this event relates to.
value:
type: object
description: Value associated with the event. The valid value depends on the
capability.
unit:
type: string
description: Unit of the value field.
example:
component: main
capability: switchLevel
attribute: level
value: 0
unit: null
CreateDeviceEventsResponse:
type: object
CreateDeviceCommandsResponse:
type: object
swagger: '2.0'
host: device-api.st.internal
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment