Download the PHP package christianjbrown/smartthings-api-sdk without Composer

SmartThings API SDK

A strongly-typed PHP client for the SmartThings API. It lists the devices in your SmartThings account, reads a device's status, and — for the operations below marked as writes — lets you act on them: run device commands, switch a location's mode, and execute scenes and rules. It returns plain, typed model objects rather than raw arrays.

The client currently supports:

• Listing devices — id, name, label, location and room ids, and each component's capabilities — or reading a single device by id (getOneById). Write: executing one or more capability commands on a device (executeCommands), returning each command's tracking id and status; installing a SmartApp-managed device (installDevice); updating a device's label, location, room, components (id, label, icon and categories) or indoor map position (updateDevice); deleting a device (deleteDevice); and posting attribute-state events for a SmartApp-managed device (createEvents).
• Reading a device's status — currently the temperatureMeasurement, relativeHumidityMeasurement, and battery capabilities (value, unit, and timestamp) from the device's main component (getOneById/getOneByDevice), a single component (getOneByComponent), or a single capability on a component (getOneByCapability).
• Reading a device's health — the connection state (ONLINE/OFFLINE/UNHEALTHY) and the lastUpdatedDate, by id (getOneById) or from a device (getOneByDevice).
• Reading a device's preferences — the device's current preference values, by id (getOneById) or from a device (getOneByDevice). Each preference carries its name, preferenceType, and value.
• Reading device preference definitions — the account's custom device-preference definitions, optionally filtered by namespace (getMultiple), or a single definition by id (getOneById). Each carries its preference id, name, title, description, preferenceType, and required flag. Write: creating (createPreference), updating (updatePreferenceById) and deleting (deletePreferenceById) a preference. A preference's definition varies by preferenceType (minimum/maximum for integer/number, minLength/maxLength/stringType for string, options for enumeration, a default for any type), so PreferenceRequest accepts it as a raw array shaped per the vendor's schema rather than a fully typed nested model, for the same proportionality reason as Rules and Device profiles. Localizations are written with createPreferenceLocalization and updatePreferenceLocalization (POST /preferences/{preferenceId}/i18n, PUT /preferences/{preferenceId}/i18n/{locale}, the paths in the vendor spec).
• Listing locations — id and name, or reading a single location by id (getOneById). Write: creating a location (createLocation); replacing a location's fields (updateLocation); patching a location's latitude, longitude or region radius, including clearing a field (patchLocation); and deleting a location (deleteLocation).
• Reading rooms — listing every room in a location (getMultiple), reading a single room, either from a device (getOneByDevice) or by a location and room id (getOneByLocationAndId), or listing the devices in a room (getDevicesInRoom). Each room carries its id, name, and location id. Write: creating a room (createRoom), updating its name (updateRoom), and deleting it (deleteRoom).
• Reading modes — listing a location's modes (getMultiple), reading the currently active mode (getCurrent), or a single mode by id (getOneByLocationAndId). Each mode carries its id, label, and name. Write: switching the location's currently active mode (changeCurrent), which can trigger any automations for which the new mode is a trigger; creating a mode (createMode), updating its label (updateMode), and deleting it (deleteMode).
• Reading scenes — listing scenes for the account, optionally filtered by location (getMultiple), or a single scene by id (getOneById). Each scene carries its id, name, and location id. Write: executing a scene (execute), running each of its actions.
• Reading rules — listing a location's rules (getMultiple) or a single rule by id (getOneById); both require a location id. Each rule carries its id, name, and status. Write: triggering Rule execution (execute), returning the execution id and result; creating (createRule), updating (updateRule) and deleting (deleteRule) a Rule; and deleting every Rule in a location (deleteAllRules). The vendor's Rule action and condition schema is a recursive expression language (if, sleep, command, scene, every, location, limit and toggle actions, each of which can nest further actions and conditions). RuleRequest::getActions() accepts either typed ActionInterface objects or raw arrays shaped per the vendor's Action schema, and an action sequence can be set with setActionSequence. Rules read back through the typed Action tree as well.
• Reading capabilities — listing all platform capabilities (getMultiple), the custom capabilities in a namespace (getMultipleByNamespace), every capability namespace (getNamespaces), the versions of a capability (getVersions), one capability definition by id and version (getOneByIdAndVersion), or a capability's presentation by id and version (getPresentation). Each capability carries its id, name, status, version and ephemeral flag, plus its attributes and commands as typed models (schemas, enum commands and arguments); localizations read back with their preference options and capability attribute and command labels; each namespace its name, owner type, and owner id; each presentation its id and version. Write: creating a custom capability, optionally in a namespace and for an organization (createCapability); updating (updateCapability) and deleting (deleteCapability) a capability version; creating (createCapabilityLocalization), replacing (updateCapabilityLocalization) and patching (patchCapabilityLocalization) a localization; and creating (createCustomCapabilityPresentation) or replacing (updateCustomCapabilityPresentation) a custom capability's presentation. A capability's attributes and commands are typed models, and the presentation sections (dashboard, detail view, automation, presentation settings) are typed models on the create and update requests, shaped per the vendor schema, and a presentation read back carries the same sections as typed models.
• Reading device profiles — listing the account's device profiles (getMultiple) or a single profile by id (getOneById). Each carries its id, name, and status. Write: creating (createDeviceProfile), updating (updateDeviceProfile) and deleting (deleteDeviceProfile) a profile. A profile's components can be typed DeviceProfileComponentRequestInterface objects (each with typed capability references) or raw arrays, and its preferences can be typed PreferenceRequestInterface objects or raw arrays, all shaped per the vendor's schema. A preference's definition can be set as a typed PreferenceDefinitionInterface with setDefinitionModel. metadata and deviceConfig are still accepted as raw arrays. A profile read back carries its components, preferences and detail fields as typed models.
• Reading presentations — a device presentation by presentation id (getOne) or for a specific device (getByDeviceId, or getByDevice from a device), a stored device config (getDeviceConfig), or the default config generated from a device type (getDeviceConfigByType). Each carries its presentation id, manufacturer name, and type. Typed device configurations: createDeviceConfiguration creates a configuration from a typed DeviceConfigurationRequestInterface (a profile id or the vendor's dashboard, detail view and automation trees), getDeviceConfiguration reads one as typed models, getDevicePresentation reads a device's presentation (optionally limited to a view, with If-None-Match and Accept-Language), and generateDeviceConfiguration returns a draft for an integration type.
• Reading apps — listing the account's apps (getMultiple), one app by name or id (getOneById), an app's OAuth config (getOauth — client name, scopes, redirect URIs), or its settings map (getSettings). Write: creating an app (createApp, returning the app plus the OAuth client id and secret when OAuth was requested); updating it (updateApp); deleting it (deleteApp); replacing its settings (updateAppSettings) and OAuth config (updateAppOauth); generating a new OAuth client id and secret (generateAppOauth); confirming a webhook target (register); and changing the signature type (updateSignatureType). createApp and updateApp accept the signatureType and requireConfirmation options, and createApp an accountId.
• Reading installed apps — listing installed app instances, optionally by location (getMultiple), one instance by id (getOneById), the instance for the current token (getMe), its configurations (getConfigs), or a single configuration (getConfig). Write: deleting an installed app (deleteInstallation); sending SmartApp and dashboard card events to its clients (createEvents); and managing its coordinate aliases (putCoordinateAlias, deleteCoordinateAlias, and getCoordinateAliasCapability for the alias's capability data as the raw response).
• Reading subscriptions — listing an installed app's subscriptions (getMultiple) or a single subscription by id (getOneById). Each carries its id, installed app id, and source type. Write: creating a subscription (saveSubscription, from a SubscriptionRequest whose sourceType selects one typed detail model: device, capability, mode, device lifecycle, device health, security arm state, hub health or scene lifecycle), deleting one (deleteSubscription), and deleting all of an installed app's subscriptions, optionally limited to a device or mode (deleteAllSubscriptions).
• Reading schedules — listing an installed app's schedules (getMultiple) or a single schedule by name (getOneByName). Each carries its name and installed app id. Write: creating a once or cron schedule (createSchedule), deleting one (deleteSchedule), and deleting all of an installed app's schedules (deleteSchedules).
• Reading ST Schema connectors — listing the account's ST Schema (C2C) connectors (getMultiple), a single connector by id (getOneById), the installed connector instances in a location (getInstalledMultiple), a single installed instance by id (getInstalledById), or a connector's install page definition (getInstallPage). Connectors carry their endpoint app id, app name, partner name, certification status, and ST client id; installed instances their isaId, app/partner name, location id, page type, and OAuth link.
• Reading Edge hubs — a hub device by id (getOneById — id, name, EUI, owner, serial number, firmware version), its characteristics as a scalar name→value map (getCharacteristics), the drivers installed on a hub, optionally filtered by device (getInstalledDrivers), one installed driver by id (getInstalledDriver), or the channels a hub is enrolled in (getEnrolledChannels). Write: installing a driver on a hub, optionally from a channel (installDrivers); uninstalling one (uninstallDriver); changing the driver, integration profile or provisioning state of a child device (updateHubDevice, with the forceUpdate option); and deleting a hub by its EUI (deleteHubByEui).
• Reading Edge channels — listing driver-distribution channels, optionally filtered by type, subscriber id, or read-only inclusion (getMultiple), a single channel by id (getOneById), the drivers assigned to a channel (getDrivers), or the driver metadata for a channel/driver pair (getDriverMeta, returning a DriverInterface). Each channel carries its channel id, name, description, terms-of-service URL, and type. A single driver of a channel is read with getDriverChannel. Write: creating (createChannel), updating (updateChannel) and deleting (deleteChannel) a channel; and adding a driver version to a channel (createDriverChannel), changing its version (updateDriverChannelVersion) or removing it (deleteDriverChannel).
• Reading Edge drivers — listing the account's drivers (getMultiple), the drivers on the default channel (getDefaults), a single driver by id (getOneById), or a specific driver revision by id and version (getOneByIdAndVersion). Each carries its driver id, name, description, package key, and version. Write: deleting a driver (deleteDriver). Uploading a driver package (a zip archive) is uploadDriverPackage, which returns the created driver.
• Reading virtual devices — listing the account's virtual devices, optionally filtered by location (getMultiple). Each is returned as a DeviceInterface, the same typed model as a physical device.
• Reading location services — a location's service info (getLocationInfo — city, latitude, longitude, and subscriptions), the list of available service-capability names (getAvailableCapabilities), or the data for one or more capabilities such as weather, airQuality, and forecast (getCapability / getCapabilities). Each capability's fields are returned as a name-keyed map of typed ServiceMeasurementInterface values (value + unit). Write: creating (createSubscription), replacing (updateSubscription) and deleting (deleteSubscription) a location service subscription, and deleting the subscriptions of an installed schema app (deleteSubscriptionsByInstalledApp). The vendor's alert-link operation answers with an HTTP redirect whose Location header the API client does not expose, so it is not covered.
• Text to speech — the voices SmartThings offers (TextToSpeechApi::getInfo), converting text to speech and getting the audio URL (convert), and playing text on a device (playText).
• Schema app invitations — creating an invitation to a schema app (SchemaAppInviteApi::createInvite), accepting one by its short code (acceptInvite), listing a schema app's invitations a page at a time (getInvites), and checking whether an invitation was accepted (checkAcceptance).
• More response fields — the vendor's remaining read-only fields are now exposed on the existing response models, including the detail blocks on locations, rooms, modes, schedules, installed apps, apps, schema apps, subscriptions, Edge channels, drivers, hub drivers and device preference definitions. Each is optional and read through its own typed model, so payloads that omit it are unaffected. Devices now also carry their component-level detail (the app, BLE, Zigbee, Z-Wave, hub, Matter and other integration blocks the vendor defines) and their child devices, read through typed models.
• Schema (Cloud-to-Cloud) connectors, writes — creating a schema app (createApp, returning the generated SmartThings client id and secret), replacing it (updateApp), deleting it (deleteApp), deleting an installed schema app (deleteInstalled), generating new SmartThings OAuth credentials (generateStOauthCredentials), and listing the apps of a user (getByUserId) or organization (getByOrganization). The X-ST-Organization header is an optional argument wherever the vendor spec has it.
• Reading organizations — listing the account's organizations (getMultiple) or a single organization by id (getOneById). Each carries its organization id, name, label, manufacturer name, and default-user-org flag.
• Reading translations (i18n) — for capabilities, device profiles, and device preference definitions, list the locales a resource is translated into (getLocales) or read the translations for one locale/tag (getTranslations). Locales are returned as LocaleReferenceInterface (tag); translations as LocalizationInterface (tag, label, description).
• Reading device history — device event history (getMultiple), optionally filtered by device and/or location, oldest-first, transparently paged across the API's _links.next chain (with an optional page cap). Each event carries its device id, location id, component, capability, attribute, value, and epoch (the SmartThings history window is roughly the last 7 days).

Supported endpoints

:heavy_check_mark: Prerequisites

• Git
• PHP 8.5 or higher (8.x)
• Composer

:bulb: If you're on MacOS and have Homebrew, PHP and Composer will install with brew install composer.

:building_construction: Installation

For your composer-enabled project:

:computer: Usage

First, create a SmartThings personal access token with the devices scopes. This token is passed to each API client.

The quickest way to get the two clients is the SmartThings entry point, which builds them (and their transformer chains) for you through a dependency-injection container — just pass your token:

If you'd rather wire the clients by hand, see Wiring the clients below.

With either approach, listing devices and reading a device's status looks like this:

You can also read a single device or its status by id, list locations, or list and fetch rooms directly:

Writing: commands, modes, scenes, and rules

Reading everything a device reports

DeviceStatusApi::getReportById() returns every component, capability and attribute of a device with its health state; getComponentReport() and getCapabilityReport() narrow it. Attribute values are AttributeStateInterface objects (value, unit, data, timestamp), keyed by capability and attribute name:

Installed app configuration entries are typed too: InstalledAppConfigInterface::getConfigEntries() returns the entries of each configuration name (string, device, permission, mode, scene, message and room configs).

Reading error bodies

Failed requests surface as RequestExceptionInterface from christianjbrown/api-client. When the API sent an error body, read it with the error transformer:

SchemaAppOwnerApi (getSchemaAppOwnerApi()) returns the apps of an organization or a user with the wrapper fields (getOrganizationIds(), getUserId()).

Filtering and query parameters

List and get calls take the API's optional query parameters. The busier lists take a small query object; the rest take plain optional arguments after $skipCache. Lists such as capability or driverIds are sent as repeated parameters, as the API expects.

Calls the API scopes to an organization or a language take them as a trailing optional argument ($organizationId sends X-ST-Organization, $acceptLanguage sends Accept-Language), for example $deviceProfileApi->getOneById('a-profile-id', false, 'an-org-id', 'fr-FR'). Cached responses are kept per organization and language.

ServiceApi::getAlertLink() returns the address the coordinate service redirects to for a location's weather alert page. The redirect is read, not followed.

List calls read every page: when a response carries _links.next.href the client follows it (up to 100 pages) and returns all the items together. DeviceHistoryApi keeps its own $maxPages limit and is not affected.

The other query objects are InstalledAppListQuery, AppListQuery, RuleListQuery, LocationListQuery and PreferenceListQuery. Each response is cached per full request, so the same call with a different filter is fetched again.

:rotating_light: Error handling

Everything this library throws implements ChristianBrown\SmartThings\Exception\ExceptionInterface, so a single catch covers it all:

There are two concrete types:

• UnexpectedResponseException (extends RuntimeException) — the SmartThings API returned a body the client or a transformer couldn't parse (a missing/mis-typed field, an empty response).
• MissingInputException (extends InvalidArgumentException) — bad caller input, e.g. passing a DeviceInterface with no location or room id to LocationRoomApi::getOneByDevice().

Both live in src/Exception/. Request-level failures (network errors, non-2xx responses) still surface as RequestExceptionInterface from christianjbrown/api-client, which is outside this library's exception hierarchy.

Under the hood, SmartThings wires the clients and their transformer chains through a Symfony dependency-injection container. If you don't want the container, you can build the same chains by hand — as shown below. The HTTP request sender comes from christianjbrown/api-client.

Overriding the API host

Every request goes to https://api.smartthings.com by default. To point at a different host — a staging environment, a proxy, a recorded-fixture server in a test suite — pass an ApiHostInterface as the second constructor argument:

Omit it, or pass null, and requests go to production exactly as before — existing callers don't need to change anything. ApiHostInterface::PRODUCTION_BASE_URL holds the default. The interface constants on each *ApiInterface (e.g. DeviceApiInterface::API_URL) still point at production and are unaffected by an override; the override only changes the host each request is actually sent to.

:arrow_up: Upgrading to 2.0

Version 2.0 removes the built-in fallbacks: a client no longer builds a default serializer or transformer for a collaborator you leave out. Every collaborator of an *Api class, and of the transformers and serializers that take collaborators, is now a required constructor argument typed on its interface. Code that uses the SmartThings facade (new SmartThings($token) and the get*Api() getters) is unaffected, because the facade's registrars wire everything. Code that constructs *Api classes by hand has to pass the collaborators, including the RequestUrlBuilderInterface that the clients with query parameters take; the registrars list them.

:memo: Changelog

Notable changes in each release are listed in CHANGELOG.md.

:page_facing_up: License

Released under the MIT License.