FAQs

Click on each question to see the answer

General

What is an API?

Answer: API stands for Application Programming Interface. An API allows developers to connect their application to another application. Our API enables you to connect your application to our products.

How can I contact GE Appliances regarding the APIs?

Answer: For information regarding the developer portal or our APIs, please use this contact form.

What brands does this API support?

Answer: GE Appliances maintains a house of brands. All of these brands interact with our APIs in the same way, so you can be assured that your application will be compatible with all our appliances.

Our brands are listed below:

How can I find out what specific appliances are supported with the SmartHQ API?

Answer: Learn which appliances support SmartHQ by browsing our selection of smart appliances here.

Will my application be compatible with appliances that will be launched in the future?

Answer: Yes, appliances produced at a later date will still use our APIs.

Is my application compatible with appliances that are not Wi-Fi enabled?

Answer: Our APIs are only designed for Wi-Fi-enabled appliances. Older appliances that cannot be connected to Wi-Fi will not be controllable via the SmartHQ API.

What do you mean by "device"?

Answer: In SmartHQ, a device typically refers to a Wi-Fi-enabled appliance—like a dishwasher or air conditioner—connected to the SmartHQ ecosystem. While most devices in SmartHQ are appliances, the term can apply to any internet-connected technology. Through the Device Adapter API, even non-appliance devices (e.g., a Wi-Fi-enabled lawnmower) can be integrated into SmartHQ.

How do I connect an appliance to Wi-Fi?

Answer: The SmartHQ app provides specific instructions. Visit our device commissioning page for more information.

Technical Details

What authorization do you use?

Answer: Our developer portal uses the industry-standard OAuth 2.0 security protocol. For more information about this standard, please visit the official OAuth 2.0 website here.

When an end-user authorizes an app, can they choose which of their SmartHQ devices the app is allowed to access?

Answer: No. When an end-user authorizes an app, they grant access to their entire SmartHQ account, including all currently commissioned devices. If a device is later decommissioned, that device will no longer be visible or accessible to authorized applications.

Can I let users “Sign in with SmartHQ” to authenticate into my app instead of building my own login system or using another identity provider?

Answer: Not today. SmartHQ’s OAuth 2.0 implementation only allows users to sign in to grant control of their devices to your application—it doesn’t provide ID tokens, a userinfo endpoint, or the discovery documents required by OpenID Connect. You’ll want to continue using your existing authentication system (or another OIDC provider) for user sign-in for your application. However, if your application would benefit from the ability to authenticate with SmartHQ, please contact us.

Do you provide historical API versions? How do you handle API versioning?

Answer: Our APIs are designed to be fully backwards-compatible. Once released, all features remain supported in future updates. Although APIs have version numbers, we only publish the current, latest version and do not maintain historical versions to access directly. There is no way to access the version of an API from a year ago. Accessing an older version is not necessary because we currently support everything from that version and more with recent updates. We continuously evolve the SmartHQ Data Model by adding new properties or endpoints directly to the current version. We do not currently support a change log of new features, as the demand to see changes is not present. If you are interested in receiving updates about new features as they become available, please contact us.

Where do I send my API requests to?

Each API call is an HTTP request asking a server to perform some action and return data. In the API specifications, you’ll find one or more server entries. Each server has a base URL, which is the root address your request will hit. Using the Identity and Access Management API as an example, the requests are made to a server located at:

https://accounts.brillion.geappliances.com

This specific server URL can be found at the top of the Identity and Access Management specification under the 'servers' section. Each API specification will have a different server.

Each endpoint listed in the API specification, such as GET /oauth2/auth is a specific request to make to the server. That request is sent as part of the URL itself by appending it:

https://accounts.brillion.geappliances.com/oauth2/auth

Often, there is more information that needs to be sent to the server, which can be appended as query parameters. These query parameters can be found in the API specifications, such as these query parameters:

https://accounts.brillion.geappliances.com/oauth2/auth?response_type=code&client_id=<Your-ClientId>&redirect_uri=<Your-RedirectUri>&access_type=offline&state=<someValue>

Typically, the response from an API is JSON. This authorization endpoint however is an exception that returns HTML for a web page for a user to sign into (Learn more).

How do I send API requests?

For a practical guide, see Getting Started.

Ultimately, your HTTP client (a web browser, curl, Postman, or a library in your code) opens a connection to the SmartHQ server hosting the API and sends your request.

Browser vs. programmatic requests

• GET endpoints: You can often paste the full URL into a browser to see the JSON response (or other response types, such as HTML) from the server.

• POST/PUT/DELETE, etc.: These require a request body and headers (for example, Content-Type: application/json), so you’ll want to use curl, Postman, or your HTTP client library. Some endpoints expect form-encoded bodies (application/x-www-form-urlencoded) (often to protect secrets); the endpoint docs will call this out—e.g. POST /oauth2/token.

SmartHQ Apps

What is a SmartHQ app?

The term SmartHQ app can refer to two things:

1. The SmartHQ mobile application: This is the official app you can download from the app store, which allows end-users to commission (set up) and control their SmartHQ-enabled appliances. Learn more about commissioning a device.

2. A custom application you create using the SmartHQ developer portal: When you register a SmartHQ app on the developer portal, you are creating an integration that can interact with SmartHQ APIs. Your app receives a clientId and clientSecret, which uniquely identify it to SmartHQ.

In summary, a SmartHQ app is either the official mobile app or any custom integration you build to interact with SmartHQ.

What can my custom SmartHQ app do?

When we refer to a "SmartHQ app" here, we mean the application you create and register in the SmartHQ developer portal—not the mobile app from the app store.

Your created SmartHQ app allows you to extend and integrate SmartHQ functionality into your own products or services. With a custom SmartHQ app, you can:

 - Connect to SmartHQ APIs
 - Automate appliance control and monitoring
 - Integrate SmartHQ features into your own products or services
 - Respond to device events and alerts
 - Build custom workflows for smart appliances

Alerts

So is an "Alert" just a notification?

Not exactly. An alert is a message generated in the SmartHQ cloud when a specific event occurs on a user's device. By itself, an alert doesn't notify anyone—it simply exists in the system. To make use of alerts (e.g., to notify users), your app must actively access them through the Digital Twin API or subscribe to them via the Event Stream API. Alerts become notifications only when your app delivers them to users.

How do I know what alerts a device supports?

A list of alerts a device can send will be found on each device's page in the data model, such as washing machine alerts.

Where can I see a list of all the alerts offered in SmartHQ?

There is no single list of every alert offered, and this is intentional. Each alert pertains to a particular device. Completely different devices may support the same type of alert, but the types of alerts depend on the device. That is why the data model is structured by device, as this applies to domainTypes and other SmartHQ concepts as well.

What's the difference between service alerts and alerts?

Service alerts are functionally the same as regular alerts, except service alerts typically pertain to messages indicating something went wrong with your device. An example a service alert is cloud.smarthq.alert.fault.keystuck which indicates a button on a device has been continuously pressed for a minute or longer. This alert would inform you that the button is jammed or something is actively pressing it. These are the same service alerts that the SmartHQ Service Platform uses to diagnose issues with devices. Not all service alerts indicate problems, but that is the most common use case. In washing machines, the service alert cloud.smarthq.alert.coinbox.capacity.50 is used to indicate the coinbox capacity has reached 50 percent, which does not pertain to any error state or issue.

How do I actually make use of alerts?

You can access alerts through...

• the various alert endpoints of the Digital Twin API
• setting up real-time updates through WebSockets or HTTPS / SNS Callbacks

For more information on how to practically use alerts, see the device control and monitoring tutorial on receiving device alerts.

Services

How can I conceptualize services? What are they?

Within the SmartHQ app, you can see all the information about a device. That information is coming from these services in SmartHQ.

Why have services at all? Why can't I just call a POST /v1/refrigerator/set-temperature endpoint or something similar?

A service can be used multiple times in different contexts on the same device and across devices. For example, the temperature service is used by a refrigerator for the freezer temperature setpoint and the refrigerator temperature setpoint.

By having the values within service changes from device to device, the API endpoints used to communicate this information can remain constant. This allows adding in new devices and services easily without needing to update the APIs directly. Instead, only the data model documentation here has to change.

What's the difference between deviceType and serviceDeviceType?

• A deviceType is the highest-level device and the main product the end-user commissioned to their account, e.g., refrigerators, air conditioners, etc.
• A serviceDeviceType can be the main device or a sub-device. For example, this could be cloud.smarthq.device.appliance, which would represent the overall appliance, or cloud.smarthq.device.waterfilter, which is a sub-device in the SmartHQ data model.

How do I actually make use of services?

(https://developer.smarthq.com/apis/digital-twin#/Device%20Information%20and%20Control/get_v2_device) you can get all the devices, and the corresponding services, for a user's account. There are various endpoints to access services.

Additionally, you can subscribe to changes in real-time updates in services through WebSockets or HTTPS / SNS Callbacks

For a more detailed guide, see our tutorial.

Device Capabilities

What if my device doesn't support the features I need?

You'll need to adjust your integration to work with the available services, or consider targeting a different device model that supports your required capabilities.

Consider building your application to dynamically offer features based on each device's supported services. This approach allows your app to work across different device models—for example, showing advanced cycle controls only for washers that support them.

What if I don't have access to the device I want to integrate with?

If you're building a major application around a particular SmartHQ product, we strongly recommend verifying device capabilities before diving into development. If you're just exploring, this isn't strictly necessary, but it is recommended before developing a full application.

In the future, we hope to support a way of seeing example responses from any device without needing the physical device.

What's the difference between features, capabilities, and services?

Features and capabilities refer to what you'd expect your integration to do: start a washing machine cycle, check the fridge temperature, or receive notifications when a dryer finishes.

Services are the technical components in the SmartHQ data model that make those features possible. Each service represents a specific device function—like a temperature sensor or cycle control—that your app can interact with through the API.

Will a SmartHQ device ever stop supporting a certain feature?

A SmartHQ device will continue to support the services shown in its GET /v2/device/{deviceId} response.