The SmartThings API supports REST, resources are protected with OAuth 2.0 Bearer Tokens, and all responses are sent as JSON.
For an example on how to use this SDK, please refer to the SmartThings Terminal cli tool.
Note: This SDK is mostly auto-generated from the public SmartThings open-api definition but with necessary compilation fixes. The underlying SmartThings API is currently in preview and has ongoing changes - so there are some discrepancies between what functionality is exposed and what is implemented. Therefore if things don't work, please check the SmartThings API behaves in the way you expect first.
Also, the documentation here is not kept up to date with the code base
All SmartThings resources are protected with OAuth 2.0 Bearer Tokens sent on the request as an Authorization: Bearer <TOKEN>
header.
Only personal access tokens are supported. These are used to interact with the API for non-SmartApp use cases. They can be created and managed on the personal access tokens page.
Operations may be protected by one or more OAuth security schemes, which specify the required permissions. Each scope for a given scheme is required. If multiple schemes are specified (not common), you may use either scheme.
Personal access token scopes are associated with the specific permissions authorized when creating them.
Scopes are generally in the form permission:entity-type:entity-id
.
An *
used for the entity-id
specifies that the permission may be applied to all entities that the token type has access to, or may be replaced with a specific ID.
For more information about authrization and permissions, please see the Authorization and permissions guide.
The SmartThings API supports both path and header-based versioning. The following are equivalent:
- https://api.smartthings.com/v1/locations
- https://api.smartthings.com/locations with header
Accept: application/vnd.smartthings+json;v=1
Currently, only version 1 is available.
Operations that return a list of objects return a paginated response.
The _links
object contains the items returned, and links to the next and previous result page, if applicable.
{
"items": [
{
"locationId": "6b3d1909-1e1c-43ec-adc2-5f941de4fbf9",
"name": "Home"
},
{
"locationId": "6b3d1909-1e1c-43ec-adc2-5f94d6g4fbf9",
"name": "Work"
}
....
],
"_links": {
"next": {
"href": "https://api.smartthings.com/v1/locations?page=3"
},
"previous": {
"href": "https://api.smartthings.com/v1/locations?page=1"
}
}
}
Some SmartThings API's support localization. Specific information regarding localization endpoints are documented in the API itself. However, the following should apply to all endpoints that support localization.
When making a request with the Accept-Language
header, this fallback pattern is observed.
- Response will be translated with exact locale tag.
- If a translation does not exist for the requested language and region, the translation for the language will be returned.
- If a translation does not exist for the language, English (en) will be returned.
- Finally, an untranslated response will be returned in the absense of the above translations.
The format of the Accept-Language
header follows what is defined in RFC 7231, section 5.3.5
The Content-Language
header should be set on the response from the server to indicate which translation was given back to the client.
The absense of the header indicates that the server did not recieve a request with the Accept-Language
header set.
This C# SDK is automatically generated by the OpenAPI Generator project (then modified to work):
- API version: 1.0-PREVIEW
- SDK version: 1.0.0
- Build package: SmartThingsNet.codegen.languages.CSharpNetCoreClientCodegen
- .NET Core >=1.0
- .NET Framework >=4.6
- Mono/Xamarin >=vNext
- RestSharp - 106.10.1 or later
- Json.NET - 12.0.1 or later
- JsonSubTypes - 1.5.2 or later
- System.ComponentModel.Annotations - 4.5.0 or later
The DLLs included in the package may not be the latest version. We recommend using NuGet to obtain the latest version of the packages:
Install-Package RestSharp
Install-Package Newtonsoft.Json
Install-Package JsonSubTypes
Install-Package System.ComponentModel.Annotations
NOTE: RestSharp versions greater than 105.1.0 have a bug which causes file uploads to fail. See RestSharp#742
Generate the DLL using your preferred tool (e.g. dotnet build
)
Then include the DLL (under the bin
folder) in the C# project, and use the namespaces:
using SmartThingsNet.Api;
using SmartThingsNet.Client;
using SmartThingsNet.Model;
using System.Collections.Generic;
using System.Diagnostics;
using SmartThingsNet.Api;
using SmartThingsNet.Client;
using SmartThingsNet.Model;
namespace Example
{
public class Example
{
public static void Main()
{
Configuration config = new Configuration();
config.BasePath = "https://api.smartthings.com/v1";
// Configure OAuth2 access token for authorization: Bearer
config.AccessToken = "YOUR_ACCESS_TOKEN";
var apiInstance = new AppsApi(config);
var createOrUpdateAppRequest = new CreateAppRequest(); // CreateAppRequest |
var signatureType = signatureType_example; // string | The Signature Type of the application. For WEBHOOK_SMART_APP only. (optional)
var requireConfirmation = true; // bool? | Override default configuration to use either PING or CONFIRMATION lifecycle. For WEBHOOK_SMART_APP only. (optional)
try
{
// Create an app.
CreateAppResponse result = apiInstance.CreateApp(createOrUpdateAppRequest, signatureType, requireConfirmation);
Debug.WriteLine(result);
}
catch (ApiException e)
{
Debug.Print("Exception when calling AppsApi.CreateApp: " + e.Message );
Debug.Print("Status Code: "+ e.ErrorCode);
Debug.Print(e.StackTrace);
}
}
}
}
All URIs are relative to https://api.smartthings.com/v1
Class | Method | HTTP request | Description |
---|---|---|---|
AppsApi | CreateApp | POST /apps | Create an app. |
AppsApi | DeleteApp | DELETE /apps/{appNameOrId} | Delete an app. |
AppsApi | GenerateAppOauth | POST /apps/{appNameOrId}/oauth/generate | Generate an app's oauth client/secret. |
AppsApi | GetApp | GET /apps/{appNameOrId} | Get an app. |
AppsApi | GetAppOauth | GET /apps/{appNameOrId}/oauth | Get an app's oauth settings. |
AppsApi | GetAppSettings | GET /apps/{appNameOrId}/settings | Get settings. |
AppsApi | ListApps | GET /apps | List apps. |
AppsApi | Register | PUT /apps/{appNameOrId}/register | Sends a confirmation request to App. |
AppsApi | UpdateApp | PUT /apps/{appNameOrId} | Update an app. |
AppsApi | UpdateAppOauth | PUT /apps/{appNameOrId}/oauth | Update an app's oauth settings. |
AppsApi | UpdateAppSettings | PUT /apps/{appNameOrId}/settings | Update settings. |
AppsApi | UpdateSignatureType | PUT /apps/{appNameOrId}/signature-type | Update an app's signature type. |
DeviceprofilesApi | CreateDeviceProfile | POST /deviceprofiles | Create a device profile |
DeviceprofilesApi | DeleteDeviceProfile | DELETE /deviceprofiles/{deviceProfileId} | Delete a device profile |
DeviceprofilesApi | GetDeviceProfile | GET /deviceprofiles/{deviceProfileId} | GET a device profile |
DeviceprofilesApi | ListDeviceProfiles | GET /deviceprofiles | List all device profiles for the authenticated user |
DeviceprofilesApi | UpdateDeviceProfile | PUT /deviceprofiles/{deviceProfileId} | Update a device profile. |
DevicesApi | CreateDeviceEvents | POST /devices/{deviceId}/events | Create Device Events. |
DevicesApi | DeleteDevice | DELETE /devices/{deviceId} | Delete a Device. |
DevicesApi | ExecuteDeviceCommands | POST /devices/{deviceId}/commands | Execute commands on device. |
DevicesApi | GetDevice | GET /devices/{deviceId} | Get a device's description. |
DevicesApi | GetDeviceComponentStatus | GET /devices/{deviceId}/components/{componentId}/status | Get a device component's status. |
DevicesApi | GetDeviceStatus | GET /devices/{deviceId}/status | Get the full status of a device. |
DevicesApi | GetDeviceStatusByCapability | GET /devices/{deviceId}/components/{componentId}/capabilities/{capabilityId}/status | Get a capability's status. |
DevicesApi | GetDevices | GET /devices | List devices. |
DevicesApi | InstallDevice | POST /devices | Install a Device. |
DevicesApi | UpdateDevice | PUT /devices/{deviceId} | Update a device. |
InstalledappsApi | CreateInstalledAppEvents | POST /installedapps/{installedAppId}/events | Create Installed App events. |
InstalledappsApi | DeleteInstallation | DELETE /installedapps/{installedAppId} | Delete an installed app. |
InstalledappsApi | GetInstallation | GET /installedapps/{installedAppId} | Get an installed app. |
InstalledappsApi | GetInstallationConfig | GET /installedapps/{installedAppId}/configs/{configurationId} | Get an installed app configuration. |
InstalledappsApi | ListInstallationConfig | GET /installedapps/{installedAppId}/configs | List an installed app's configurations. |
InstalledappsApi | ListInstallations | GET /installedapps | List installed apps. |
LocationsApi | CreateLocation | POST /locations | Create a Location. |
LocationsApi | DeleteLocation | DELETE /locations/{locationId} | Delete a Location. |
LocationsApi | GetLocation | GET /locations/{locationId} | Get a Location. |
LocationsApi | ListLocations | GET /locations | List Locations. |
LocationsApi | UpdateLocation | PUT /locations/{locationId} | Update a Location. |
RoomsApi | CreateRoom | POST /locations/{locationId}/rooms | Create a Room. |
RoomsApi | DeleteRoom | DELETE /locations/{locationId}/rooms/{roomId} | Delete a Room. |
RoomsApi | GetRoom | GET /locations/{locationId}/rooms/{roomId} | Get a Room. |
RoomsApi | ListRooms | GET /locations/{locationId}/rooms | List Rooms. |
RoomsApi | UpdateRoom | PUT /locations/{locationId}/rooms/{roomId} | Update a Room. |
RulesApi | CreateRule | POST /rules | Create a rule |
RulesApi | DeleteRule | DELETE /rules/{ruleId} | Delete a rule |
RulesApi | ExecuteRule | POST /rules/execute/{ruleId} | Execute a rule |
RulesApi | GetRule | GET /rules/{ruleId} | Get a Rule |
RulesApi | ListRules | GET /rules | Rules list |
RulesApi | UpdateRule | PUT /rules/{ruleId} | Update a rule |
ScenesApi | ExecuteScene | POST /scenes/{sceneId}/execute | Execute Scene |
ScenesApi | ListScenes | GET /scenes | List Scenes |
SchedulesApi | CreateSchedule | POST /installedapps/{installedAppId}/schedules | Save an installed app schedule. |
SchedulesApi | DeleteSchedule | DELETE /installedapps/{installedAppId}/schedules/{scheduleName} | Delete a schedule. |
SchedulesApi | DeleteSchedules | DELETE /installedapps/{installedAppId}/schedules | Delete all of an installed app's schedules. |
SchedulesApi | GetSchedule | GET /installedapps/{installedAppId}/schedules/{scheduleName} | Get an installed app's schedule. |
SchedulesApi | GetSchedules | GET /installedapps/{installedAppId}/schedules | List installed app schedules. |
SubscriptionsApi | DeleteAllSubscriptions | DELETE /installedapps/{installedAppId}/subscriptions | Delete all of an installed app's subscriptions. |
SubscriptionsApi | DeleteSubscription | DELETE /installedapps/{installedAppId}/subscriptions/{subscriptionId} | Delete an installed app's subscription. |
SubscriptionsApi | GetSubscription | GET /installedapps/{installedAppId}/subscriptions/{subscriptionId} | Get an installed app's subscription. |
SubscriptionsApi | ListSubscriptions | GET /installedapps/{installedAppId}/subscriptions | List an installed app's subscriptions. |
SubscriptionsApi | SaveSubscription | POST /installedapps/{installedAppId}/subscriptions | Create a subscription for an installed app. |
- Model.Action
- Model.AdhocMessage
- Model.AdhocMessageTemplate
- Model.App
- Model.AppClassification
- Model.AppDeviceDetails
- Model.AppOAuth
- Model.AppTargetStatus
- Model.AppType
- Model.AppUISettings
- Model.Argument
- Model.ArrayOperand
- Model.AttributeProperties
- Model.AttributePropertiesData
- Model.AttributePropertiesUnit
- Model.AttributeSchema
- Model.AttributeState
- Model.BetweenCondition
- Model.CapabilityAttribute
- Model.CapabilityAttributeEnumCommands
- Model.CapabilityCommand
- Model.CapabilityReference
- Model.CapabilitySubscriptionDetail
- Model.CapabilitySummary
- Model.ChangesCondition
- Model.CommandAction
- Model.ComponentTranslations
- Model.Condition
- Model.ConditionAggregationMode
- Model.ConfigEntry
- Model.CreateAppRequest
- Model.CreateAppResponse
- Model.CreateDeviceProfileRequest
- Model.CreateInstalledAppEventsRequest
- Model.CreateLocationRequest
- Model.CreateOrUpdateLambdaSmartAppRequest
- Model.CreateOrUpdateWebhookSmartAppRequest
- Model.CreateRoomRequest
- Model.CronSchedule
- Model.DashboardCardLifecycle
- Model.DateOperand
- Model.DateTimeOperand
- Model.DayOfWeek
- Model.DeleteInstalledAppResponse
- Model.Device
- Model.DeviceActivity
- Model.DeviceCategory
- Model.DeviceCommand
- Model.DeviceCommandsEvent
- Model.DeviceCommandsEventCommand
- Model.DeviceCommandsRequest
- Model.DeviceComponent
- Model.DeviceComponentReference
- Model.DeviceConfig
- Model.DeviceEvent
- Model.DeviceEventsRequest
- Model.DeviceHealthDetail
- Model.DeviceHealthEvent
- Model.DeviceInstallRequest
- Model.DeviceInstallRequestApp
- Model.DeviceIntegrationType
- Model.DeviceLifecycle
- Model.DeviceLifecycleDetail
- Model.DeviceLifecycleEvent
- Model.DeviceLifecycleMove
- Model.DeviceNetworkSecurityLevel
- Model.DeviceOperand
- Model.DeviceProfile
- Model.DeviceProfileReference
- Model.DeviceProfileStatus
- Model.DeviceResults
- Model.DeviceStateEvent
- Model.DeviceStatus
- Model.DeviceSubscriptionDetail
- Model.DthDeviceDetails
- Model.EndpointApp
- Model.EqualsCondition
- Model.Error
- Model.ErrorResponse
- Model.EventType
- Model.EveryAction
- Model.ExecutionResult
- Model.GenerateAppOAuthRequest
- Model.GenerateAppOAuthResponse
- Model.GetAppSettingsResponse
- Model.GreaterThanCondition
- Model.GreaterThanOrEqualsCondition
- Model.HubHealthDetail
- Model.HubHealthEvent
- Model.IconImage
- Model.IfAction
- Model.IfActionAllOf
- Model.InstallConfiguration
- Model.InstallConfigurationDetail
- Model.InstallConfigurationStatus
- Model.InstalledApp
- Model.InstalledAppIconImage
- Model.InstalledAppLifecycle
- Model.InstalledAppLifecycleError
- Model.InstalledAppLifecycleEvent
- Model.InstalledAppStatus
- Model.InstalledAppType
- Model.InstalledAppUi
- Model.Interval
- Model.IntervalUnit
- Model.IrDeviceDetails
- Model.IrDeviceDetailsFunctionCodes
- Model.IsaResults
- Model.LambdaSmartApp
- Model.LessThanCondition
- Model.LessThanOrEqualsCondition
- Model.Link
- Model.Links
- Model.LocaleReference
- Model.LocaleVariables
- Model.Location
- Model.LocationAction
- Model.LocationAttribute
- Model.LocationOperand
- Model.Message
- Model.MessageConfig
- Model.MessageTemplate
- Model.MessageType
- Model.Mode
- Model.ModeConfig
- Model.ModeEvent
- Model.ModeSubscriptionDetail
- Model.Notice
- Model.NoticeAction
- Model.NoticeCode
- Model.OnceSchedule
- Model.Operand
- Model.OperandAggregationMode
- Model.Owner
- Model.PagedApp
- Model.PagedApps
- Model.PagedDeviceProfiles
- Model.PagedDevices
- Model.PagedInstallConfigurations
- Model.PagedInstalledApps
- Model.PagedLocation
- Model.PagedLocations
- Model.PagedMessageTemplate
- Model.PagedRooms
- Model.PagedRules
- Model.PagedSchedules
- Model.PagedSubscriptions
- Model.ParentType
- Model.PermissionConfig
- Model.PredefinedMessage
- Model.PrincipalType
- Model.Room
- Model.Rule
- Model.RuleAllOf
- Model.RuleExecutionResponse
- Model.RuleMetadata
- Model.RuleRequest
- Model.SceneAction
- Model.SceneArgument
- Model.SceneCapability
- Model.SceneCommand
- Model.SceneComponent
- Model.SceneConfig
- Model.SceneDevice
- Model.SceneDeviceGroup
- Model.SceneDeviceGroupRequest
- Model.SceneDeviceRequest
- Model.SceneLifecycle
- Model.SceneLifecycleDetail
- Model.SceneLifecycleEvent
- Model.SceneMode
- Model.SceneModeRequest
- Model.ScenePagedResult
- Model.SceneRequest
- Model.SceneSecurityModeRequest
- Model.SceneSleepRequest
- Model.SceneSummary
- Model.Schedule
- Model.ScheduleRequest
- Model.SecurityArmStateDetail
- Model.SecurityArmStateEvent
- Model.SignatureType
- Model.SimpleCondition
- Model.SimpleValue
- Model.SingleOperandCondition
- Model.SleepAction
- Model.SmartAppDashboardCardEventRequest
- Model.SmartAppEventRequest
- Model.StandardSuccessResponse
- Model.StringConfig
- Model.Subscription
- Model.SubscriptionDelete
- Model.SubscriptionFilter
- Model.SubscriptionFilterTypes
- Model.SubscriptionMode
- Model.SubscriptionRequest
- Model.SubscriptionSource
- Model.SubscriptionTarget
- Model.TimeOperand
- Model.TimeReference
- Model.TimerEvent
- Model.TimerType
- Model.UpdateAppOAuthRequest
- Model.UpdateAppRequest
- Model.UpdateAppSettingsRequest
- Model.UpdateAppSettingsResponse
- Model.UpdateDeviceProfileRequest
- Model.UpdateDeviceRequest
- Model.UpdateDeviceRequestComponents
- Model.UpdateLocationRequest
- Model.UpdateRoomRequest
- Model.UpdateSignatureTypeRequest
- Model.ViperDeviceDetails
- Model.WebhookSmartApp
- Type: HTTP basic authentication
- Type: OAuth
- Flow: implicit
- Authorization URL: https://auth-global.api.smartthings.com
- Scopes:
- 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.
- r:scenes:*: Read details about 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 (the scope is limited to the account associated with the token).
- r:hubs: Read hubs.
- r:security:locations:*:armstate: Read arm state in the given location.