Last active
April 2, 2018 15:04
-
-
Save jimmyjames/6250a8ab65dae247ab3de08582c25851 to your computer and use it in GitHub Desktop.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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