Smart home REST API: control Hue, SmartThings from code

If you want to script your devices from code, you have two routes. You can call each vendor's API directly, with a separate login, data model and command format for every brand. Or you can link your provider accounts to one service and call a single smart home REST API. Port OS offers the second route: one HTTP API for the devices on your linked provider accounts.

Port OS publishes this article, so read the comparison with that interest in mind. It is based on Port OS's own documentation and its OpenAPI file, plus the vendor pages linked below. We have not benchmarked Port OS against any vendor API, and nothing here claims it is faster or more reliable.

One API or one per vendor?

The deciding question is how many brands you need to reach and how much of each vendor's detail you want to own.

What the vendors say about their own APIs:

• SmartThings. Samsung's developer documentation says SmartThings resources are protected with OAuth 2.0 bearer tokens. It also describes personal access tokens, which it says are valid for 24 hours when created now, and recommends a service integration for ongoing access.
• Philips Hue. Hue publishes its API v2 through the Hue developer program. We could not read the documentation without a developer account login, so check it directly for current authentication and bridge details. Port OS's Hue page says a Hue Bridge and Hue account are required.
• Alexa. Amazon's public Alexa Smart Home APIs are written for people who build an add-on for a device cloud: Alexa sends directives to your add-on, and your add-on controls the device. We did not find a public API in Amazon's documentation for controlling your own Alexa devices from a script, so we make no claim that one exists. Port OS has a separate Alexa integration for supported devices already linked to an Amazon account. Its device controls are available through the Port OS API after account linking; this does not establish a public Amazon consumer-control API.

Which providers you can reach

Port OS is in alpha, and the list changes. The Add a Device page is the current source. As of November 2, 2026:

• Philips Hue, Sonos and supported Roborock vacuums are in public alpha. See the Hue, Sonos and Roborock pages.
• SmartThings has a setup guide. You register your own OAuth-In app with Samsung's command-line tool, then enter its client ID and secret in Port OS.
• Google Nest, Spotify and Android TV have setup guides but need developer-style steps.
• Amazon Alexa supports the devices and actions returned by its account connection. Review its setup and limits before using a particular model.
• Shelly is a waitlist integration and is not ready to use.

A provider name does not guarantee every model or action. The endpoint you get back lists the capabilities it supports.

How authentication works

Port OS uses bearer tokens. Send Authorization: Bearer $PORTOS_TOKEN to https://api.portoperatingsystem.com, the server listed in the OpenAPI file.

• To try the API yourself, the REST API guide lets you sign in, copy a short-lived token and create a simulator light. Copy a fresh token when it expires.
• For your own app, register an OAuth client by following how to set up an OAuth client. It supports authorization code with PKCE and a device-code flow.
• Scopes are a ceiling. The listing call needs endpoint:read and sending a command needs message:send. A token can never do more than the scopes the user approved, and access control rules are checked as well. Owners can already use their own devices; rules grant access to other people.

One thing that is not an API key: the "access key" in the test access keys guide is a website sign-in key for a person or reviewer. It grants full account access. The guide says API and automation keys cannot sign into the website, so do not treat it as a scripting credential.

Linking a provider is separate from API authentication. You connect Hue, SmartThings or another account once, in the browser, and the API then sees the devices that link discovers.

List devices, then send a command

These examples use placeholders. Use a real token, and copy real endpoint ids from the list response.

List your lights with POST /endpoint-query:

curl -s https://api.portoperatingsystem.com/endpoint-query \
  -H "Authorization: Bearer $PORTOS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": { "match": { "key": "type", "value": "LIGHT" } },
    "paginationContext": { "maxResults": 10 }
  }'

An empty query returns all of your enabled endpoints. Follow the returned continuation token until it is absent, and repeat the same query settings when you do.

Then turn one light off with POST /message-requests. The Idempotency-Key header is required. Choose a new unique value for each intended command, and reuse the same key and complete payload if retrying that command after a transport failure:

PORTOS_REQUEST_KEY="$(uuidgen)"
curl -s https://api.portoperatingsystem.com/message-requests \
  -H "Authorization: Bearer $PORTOS_TOKEN" \
  -H "Idempotency-Key: $PORTOS_REQUEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target": {
      "type": "ENDPOINT",
      "id": "port1/systems/home/endpoints/hall-light"
    },
    "message": {
      "header": {
        "namespace": "port1/systems/zero/capability-interfaces/power",
        "name": "turn-off",
        "version": "1.0"
      },
      "body": {}
    },
    "responseType": "SYNC"
  }'

The id above is a placeholder. The same call works for other capabilities by changing the header, and the capabilities reference and capabilities, messages and attributes pages describe what each device accepts. Do not invent message fields. The HTTP reference has every path and schema, and the endpoints and reference pages cover the model.

Accepted command or fresh state?

Treat these as two facts. Creating a durable message request returns HTTP 200 with its current status, results and errors. That response can describe unfinished work, and successful delivery does not prove the light changed. A TIMED_OUT result leaves the external outcome unknown. Read state before you repeat a command, especially a relative action like "brighten by 10". If retrying the same request after a transport failure, reuse its existing idempotency key and payload rather than creating a second intended command.

To read fresh state, call the same endpoint query with "expand": ["interfaces.attributes"] and "forceDeviceQuery": true. Each attribute carries a sample time and freshness, and the response can include partial errors. A provider may answer with its own last known value, so check the sample time rather than assuming the reading is live.

Limits to plan around

• Alpha. Port OS is in alpha. Contact the team through the contact page for pricing or compatibility commitments; we do not state any here.
• Catalog coverage. Only integrations Port OS offers are reachable. A device your provider supports may not be exposed here.
• Provider dependence. Outages, account verification, relinking and the provider's own rate limits still apply. We have no published Port OS rate limit figures to share.
• Cloud path. Requests go through Port OS's hosted service and then the provider, so internet access is required.
• No SDK claim. This article assumes plain HTTP. We do not document an official SDK here.

When to use the vendor's API directly

Go direct when you need a feature the unified API does not expose, when you only use one brand, when you need the vendor's local network API, or when you do not want an extra hosted service in the path. Go direct to Alexa only if you are building an add-on for your own device cloud, since that is what its public APIs are for.

Use Port OS when your devices span several supported providers and you want one authentication model and one command format. If you want the same devices available to an AI assistant, the smart home MCP page covers the hosted MCP server, and agentic API development best practices covers designing APIs that agents can call safely.

FAQ

Is there an official Alexa REST API for controlling my devices? Amazon's public Alexa Smart Home APIs are for building add-ons that let Alexa control a device cloud. We did not establish a public Amazon API for controlling your own Alexa devices from a script. Port OS separately exposes the supported devices and actions returned by its Alexa account connection through its unified API.

Can I call the SmartThings API through Port OS? Port OS does not proxy SmartThings API calls. You link SmartThings through its setup guide, and the devices appear as Port OS endpoints with the controls they return.

Does it work in Python? It is plain HTTPS and JSON, so any HTTP client works. We do not document an official Python library.

Does a successful command mean the device changed? No. Read fresh state with the forced query and check the sample time.

Where do I get a token? The REST API guide for a short-lived one, or an OAuth client for your own app.

All posts