SmartThings Schema reference

This reference provides information about interaction types, field descriptions, error handling, examples, and other specification requirements.

Schema info

  • "schema": "st-schema"
  • "version": "1.0"

Interaction types

The interaction type is located in the payload headers.interactionType. The token context for the request in indicated in authentication.token.

Example

{
  "headers": {
    "schema": "st-schema",
    "version": "1.0",
    "interactionType": "discoveryRequest",
    "requestId": "abc-123-456"
  },
  "authentication": {
    "tokenType": "Bearer",
    "token": "token received during oauth from partner"
  }
}

You must implement the following SmartThings interaction types:

  • Discovery: SmartThings requests a list of devices.
  • State Refresh: SmartThings requests the states of the indicated devices.
  • Command: SmartThings requests that you issue commands for the indicated devices.

Optional interaction types

Discovery

Handle the request by retrieving an initial list of devices.

Example request

{
  "headers": {
    "schema": "st-schema",
    "version": "1.0",
    "interactionType": "discoveryRequest",
    "requestId": "abc-123-456"
  },
  "authentication": {
    "tokenType": "Bearer",
    "token": "token received during oauth from partner"
  }
}
  • headers
    • schema: Schema type.
    • version: Schema version.
    • interactionType: Interaction type of payload.
    • requestId: Matching request ID from request.
  • authentication
    • tokenType: Token type.
    • token: Token issued by third-party cloud; the context for the request.

Example response

{
  "headers": {
    "schema": "st-schema",
    "version": "1.0",
    "interactionType": "discoveryResponse",
    "requestId": "abc-123-456"
  },
  "devices": [
    {
      "externalDeviceId": "pdevice-1",
      "deviceCookie": {"updatedcookie": "old or new value"},
      "friendlyName": "Kitchen Bulb",
      "manufacturerInfo": {
        "manufacturerName": "LIFX",
        "modelName": "A19 Color Bulb",
        "hwVersion": "v1 US bulb",
        "swVersion": "23.123.231"
      },
      "deviceContext": {
        "roomName": "Kitchen",
        "groups": ["Kitchen Lights", "House Bulbs"],
        "categories": ["light", "switch"]
      },
      "deviceHandlerType": "c2c-rgbw-color-bulb"
    },
    {
      "externalDeviceId": "pdevice-2",
      "friendlyName": "Toaster",
      "manufacturerInfo": {
        "manufacturerName": "LIFX",
        "modelName": "Outlet",
        "hwVersion": "v1 US outlet",
        "swVersion": "3.03.11"
      },
      "deviceContext": {
        "roomName": "Living Room",
        "groups": ["Hall Lights"],
        "categories": ["light"]                
      },
      "deviceHandlerType": "<deviceHandlerName-or-deviceProfileId>"
    }
  ]
}
  • headers: See above.
  • devices: Array of devices for user account.
    • externalDeviceId: Device ID at third-party cloud.
    • deviceCookie: Pass-through cookie for setting custom key/value pairs. Should not contain personally identifiable information.
    • friendlyName: (Optional) Label of the device shown to the user.
    • manufacturerInfo: Manufacturer info for the device.
      • manufacturerName: Name of the manufacturer, preferably partner name.
      • modelName: Unique model number that identifies the device model.
      • hwVersion: (Optional) Hardware version.
      • swVersion: (Optional) Software/firmware version.
    • deviceContext: Device context info.
      • roomName: Location name associated with the device.
      • groups: Groups that include the device.
      • categories: Categories associated with the device.
    • deviceHandlerType: Device handler type name.

State Refresh

Handle the request by retrieving the device states for the indicated list of devices.

Example request

{
  "headers": {
    "schema": "st-schema",
    "version": "1.0",
    "interactionType": "stateRefreshRequest",
    "requestId": "abc-123-456"
  },
  "authentication": {
    "tokenType": "Bearer",
    "token": "token received during oauth from partner"
  },
  "devices": [
    {
      "externalDeviceId": "partner-device-id-1",
    },
    {
      "externalDeviceId": "partner-device-id-2"
    }
  ]
}
  • headers: See above.
  • authentication: See above.
  • deviceState: Array of device states. See below.

Example response

{
  "headers": {
    "schema": "st-schema",
    "version": "1.0",
    "interactionType": "stateRefreshResponse",
    "requestId": "abc-123-456"
  },
  "deviceState": [
    {
      "externalDeviceId": "pdevice-1",
      "deviceCookie": {},
      "states": [
        {
          "component": "main",
          "capability": "st.switch",
          "attribute": "switch",
          "value": "on"
        },
        {
          "component": "main",
          "capability": "st.switchLevel",
          "attribute": "level",
          "value": 80
        },
        {
          "component": "main",
          "capability": "st.healthCheck",
          "attribute": "healthStatus",
          "value": "online"
        },
        {
          "component": "main",
          "capability": "st.colorControl",
          "attribute": "hue",
          "value": 0
        },
        {
          "component": "main",
          "capability": "st.colorControl",
          "attribute": "saturation",
          "value": 0          
        }
        {
          "component": "main",
          "capability": "st.colorTemperature",
          "attribute": "colorTemperature",
          "value": 3500
        }        
      ]
    }
  ]
}
  • headers: See above.
  • deviceState: Array of device states.
    • externalDeviceID: Third-party device ID.
    • states
      • component: Component of device. In most cases, the value will be "main".
      • capability: Capability of device. Use the syntax st.<capabilityName>.
      • attribute: Attribute of Capability.
      • value: The resource value.

Command

Handle the request by triggering the commands for the list of devices.

Example request

{
  "headers": {
    "schema": "st-schema",
    "version": "1.0",
    "interactionType": "commandRequest",
    "requestId": "abc-123-456"
  },
  "authentication": {
    "tokenType": "Bearer",
    "token": "token-received during oauth from partner"
  },
  "devices": [
    {
      "externalDeviceId": "partner-device-id",
      "deviceCookie": {
        "lastcookie": "cookie value"
      },
      "commands": [
        {
          "component": "main",
          "capability": "st.colorControl",
          "command": "setColor",
          "arguments": [
            {
              "saturation": 91,
              "hue": 0.8333333333333334
            }
          ]
        }
        {
          "component": "main",
          "capability": "st.switchLevel",
          "command": "setLevel",
          "arguments": [80]
        },
        {
          "component": "main",
          "capability": "st.switch",
          "command": "on",
          "arguments": []
        }
      ]
    }
  ]
}
  • headers: See above.
  • authentication: See above.
  • devices
    • externalDeviceId: Device ID on third-party cloud.
    • deviceCookie: Pass-through cookie for setting custom key/value pairs. Taken from Discovery response.
    • commands: Array of commands.
      • component: Component of device. In most cases, the value will be "main".
      • capability: Capability of device. Use the syntax st.<capabilityName>.
      • command: Command name.
      • arguments: Array containing command arguments. If not applicable to the capability/attribute, will be empty.

Example response

{
  "headers": {
    "schema": "st-schema",
    "version": "1.0",
    "interactionType": "commandResponse",
    "requestId": "abc-123-456"
  },
  "deviceState": [
    {
      "externalDeviceId": "partner-device-id",
      "deviceCookie": {},
      "states": [
        {
          "component": "main",
          "capability": "st.colorControl",
          "attribute": "hue",
          "value": 0.8333333333333334
        },
        {
          "component": "main",
          "capability": "st.switch",
          "attribute": "switch",
          "value": "off"
        },
        {
          "component": "main",
          "capability": "st.switchLevel",
          "attribute": "level",
          "value": 80
        },
        {
          "component": "main",
          "capability": "st.healthCheck",
          "attribute": "healthStatus",
          "value": "online"
        }
      ]
    }
  ]
}
  • headers: See above.
  • deviceState: (Optional) Array of device states. See above.

Example response (device error)

{
  "headers": {
    "schema": "st-schema",
    "version": "1.0",
    "interactionType": "<interactionResponse>",
    "requestId": "abc-123-456"
  },
  "deviceState": [
    {
      "externalDeviceId": "pdevice-1",
      "deviceError": [
        {
          "errorEnum": "DEVICE-DELETED",
          "detail": "more detail from the partner"
        }
      ]
    },
   {
      "externalDeviceId": "pdevice-2",
      "states": [...]
    }
  ]
}
  • deviceError
  • errorEnum: Device error enum. See Error responses.
  • detail: Error details.

Example response (global error)

{
  "headers": {
    "schema": "st-schema",
    "version": "1.0",
    "interactionType": "<interactionResponse>",
    "requestId": "abc-123-456"
  },
  "globalError": {
    "errorEnum": "TOKEN-EXPIRED",
    "detail": "more detail from the partner"
  }
}
  • globalError
  • errorEnum: Global error enum. See Error responses.
  • detail: Error details.

Callback

Callback interactions allow a third-party partner to push the latest device state information to SmartThings.

Example request

{
  "headers": {
    "schema": "st-schema",
    "version": "1.0",
    "interactionType": "callback",
    "requestId": "abc-123-456"
  },
  "authentication": {
    "tokenType": "Bearer",
    "token": "<SmartThings callback token>"
  },
  "deviceState": [
    {
      "externalDeviceId": "pdevice-1",
      "deviceCookie": {"updatedcookie": "old or new value"},
      "states": [
        {
          "component": "main",
          "capability": "st.switch",
          "attribute": "switch",
          "value": "on"
        },
        {
          "component": "main",
          "capability": "st.switchLevel",
          "attribute": "level",
          "value": 80
        },
        {
          "component": "main",
          "capability": "st.healthCheck",
          "attribute": "healthStatus",
          "value": "online"
        }
      ]
    },
    {
      "externalDeviceId": "pdevice-2",
      "deviceCookie": {"updatedcookie2": "old or new value"},
      "states": [
        {
          "component": "main",
          "capability": "st.switch",
          "attribute": "switch",
          "value": "off"
        },
        {
          "component": "main",
          "capability": "st.switchLevel",
          "attribute": "level",
          "value": 80
        },
        {
          "component": "main",
          "capability": "st.healthCheck",
          "attribute": "healthStatus",
          "value": "offline"
        }
      ]
    }
  ]
}
  • headers: See above.
  • authentication
    • tokenType: Token type.
    • token: Token received from SmartThings.
  • deviceState: (Optional) Array of device states.
    • externalDeviceID: Third-party device ID.
    • deviceCookie: (Optional) Pass-through cookie for setting custom key/value pairs. Should not contain personally identifiable information.

Reciprocal access token

When SmartThings receives an access token (obtained in an OAuth integration) from a third party, it sends a callback authentication code as below. The third party can use this code to request callback access tokens.

Grant callback access example

{
    "headers": {
        "schema": "st-schema",
        "version": "1.0",
        "interactionType": "grantCallbackAccess",
        "requestId": "abc-123-456"
    },
    "authentication" : {
        "tokenType": "Bearer",
        "token": "Token received during oauth from partner"
    },
    "callbackAuthentication": {
        "grantType": "authorization_code",
        "scope": "callback_access",
        "code": "xxxxxxxxxxx",
        "clientId": "Client ID given to partner in Workspace during app creation"
    },
    "callbackUrls": {
        "oauthToken": "Callback URL for access-token-request.json and refresh-access-tokens.json requests",
        "stateCallback": "Callback URL for state-callback.json updates"
    }
}
  • headers: See above.
  • authentication:
    • tokenType: Token type.
    • token: Token issued by third-party cloud; the context for the request.
  • callbackAuthentication:
    • grantType: Authorization type.
    • scope: Authorization scope.
    • code: Authorization code to be used in accessTokenRequest interaction.
    • clientId: Client ID.
  • callbackUrls:
    • oauthToken: Callback URL used in accessTokenRequest and refreshAccessTokens interactions.
    • stateCallback: Callback URL for providing state callbacks.

Use an HTTPS POST call to the above oauthToken URL to request a callback access token. A third party uses the callback access token to call into SmartThings Cloud.

Example access token request

{
    "headers": {
        "schema": "st-schema",
        "version": "1.0",
        "interactionType": "accessTokenRequest",
        "requestId": "abc-123-456"
    }, 
    "callbackAuthentication": {
        "grantType": "authorization_code",
        "code": "xxxxxxxxxxx",
        "clientId": "client id given to partner in dev-workspace during app creation",
        "clientSecret": "client secret given to partner in dev-workspace during app creation"
    }
}
  • headers: See above.
  • callbackAuthentication:
    • grantType: Authorization type.
    • code: Authorization code (provided in grantCallbackAccess interaction).
    • clientId: Client ID.
    • clientSecret: Client secret (obtained in Developer Workspace).

Example access token response

{
    "headers": {
        "schema": "st-schema",
        "version": "1.0",
        "interactionType": "accessTokenResponse",
        "requestId": "abc-123-456"
    }, 
    "callbackAuthentication": {
        "tokenType": "Bearer",
        "accessToken": "xxxxxxxxxxx",
        "refreshToken": "yyyyyyyyyyy",
        "expiresIn": 86400
    }
}
  • headers: See above.
  • callbackAuthentication:
    • tokenType: Token type.
    • accessToken: Access token used in callback interactions.
    • refreshToken: Refresh token.
    • expiresIn: Expiration time (in seconds).

If the access token has expired, use the provided refreshToken to request a new access token at the oauthToken URL used previously.

Refresh access token example

{
    "headers": {
        "schema": "st-schema",
        "version": "1.0",
        "interactionType": "refreshAccessTokens",
        "requestId": "abc-123-456"
    }, 
    "callbackAuthentication": {
        "grantType": "refresh_token",
        "refreshToken": "xxxxxxxxxxx",
        "clientId": "client id given to partner in dev-workspace during app creation",
        "clientSecret": "client secret given to partner in dev-workspace during app creation"
    }
}
  • headers: See above.
  • callbackAuthentication:
    • grantType: Authorization type.
    • refreshToken: Refresh token.
    • clientId: Client ID.
    • clientSecret: Client secret (obtained in Developer Workspace).

Error responses

Errors can be appended using global errors or device errors in your interaction type response.

Example global error

{
  "headers": {
    "schema": "st-schema",
    "version": "1.0",
    "interactionType": "stateRefreshResponse",
    "requestId": "abc-123-456"
  },
  "authentication": {
    "tokenType": "Bearer",
    "token": "token-issued-by-3rd-party"
  },
  "globalError": {
    "errorEnum": "TOKEN-EXPIRED",
    "detail": "The token has expired"
  },
  "deviceState": []
}

Append a globalError field to the root of your JSON response for an interaction type.

  • errorEnum: Global error enum type (see below).
  • details: Message for the error.

Global error enum types

  • TOKEN-EXPIRED: Token has expired.
  • INTEGRATION-DELETED: User has removed the integration, so both accessToken and refreshToken are invalid. Used to indicate user needs to re-authorize.
  • BAD-REQUEST: Bad request. Example detail values: st-schema body is missing, JSON parse of body failed, missing st-schema headers, missing st-schema authentication
  • INVALID-TOKEN
  • INVALID-INTERACTION-TYPE
  • UNSUPPORTED-GRANT-TYPE
  • INVALID-CODE
  • INVALID-CLIENT-SECRET
  • INVALID-CLIENT

Example device error

{
  "headers": {
    "schema": "st-schema",
    "version": "1.0",
    "interactionType": "stateRefreshResponse",
    "requestId": "abc-123-456"
  },
  "authentication": {
    "tokenType": "Bearer",
    "token": "token-issued-by-3rd-party"
  },
  "deviceState": [
    {
      "externalDeviceId": "pdevice-1",
      "deviceError": [
        {
          "errorEnum": "DEVICE-DELETED",
          "detail": "more detail from the partner"
        }
      ]
    }
  ]
}

Append a deviceError field to the stateRefreshResponse or commandResponse interaction response.

  • errorEnum: Device error enum type (see below).
  • details: Message for the error.

Device error enum types

  • DEVICE-DELETED: Device is deleted and cannot accept commands.
  • RESOURCE-CONSTRAINT-VIOLATION: Value is out of range or not acceptable.
  • DEVICE-UNAVAILABLE: Device is unavailable because of a f/w update, maintenance, etc. For use when temporarily unavailable for known reasons.
  • CAPABILITY-NOT-SUPPORTED: Command requested is not supported by the device.