SmartThings Web Host

1. Overview

SmartWeb is a local bridge server app that runs on Android devices.

Its main purposes are as follows:

- It checks SmartThings authentication status and assists with related API calls.

- It provides general HTTP proxy functionality.

- It allows you to open a page in an actual WebView (browser) to read the final HTML.

- It acts as an intermediary for SmartThings Edge drivers, local web pages, and automation scripts.

2. Basic Information

- Default Port: 8088

- Default Address Format: http://deviceIP:8088

Example:

- http://192.168.219.137:8088

3. Screen Layout

3.1 Server Tab

In the Server Tab, you can check the status of the bridge server and how to use key APIs.

Examples of displayed content:

- Bridge server address

- /api/forward usage format

- /api/web usage format

- SmartThings authentication status check API

- Background WebView execution API

3.2 Settings Tab

In the Settings tab, you can check the environment settings and status required for using the app.

Examples:

- Battery optimization exception status

- Notification permission status

- View/copy logs

- App version information

4. Key APIs

4.1 POST /api/ping

Description: Briefly checks the bridge server status and SmartThings authentication status.

Method:

- POST only

Example:

POST http://deviceIP:8088/api/ping

Example response:

{

"battery": 86,

"bridgeDevice": "phone",

"bridgeVersion": "Version: 2026.05.15",

"serverStartTime": "05/14 03:00",

"stOauthConnected": true,

"accessTokenExpiresAt": 1778773965000,

"accessTokenMinutesLeft": 1332

}

4.2 GET /api/smartthings/devices

Description:

Returns a list of SmartThings devices in a simple format.

Method:

- GET only

Example:

GET http://deviceIP:8088/api/smartthings/devices

Example response:

{

"items": [

{

"deviceId": "...",

"label": "Google Home Mini Library",

"name": "Google Home"

}

]

}

Uses:

- When finding the deviceId by the device name

- Searching for speaker names

- Selecting devices based on labels

4.3 GET /api/forward?url=origin_address

Description:

A standard HTTP proxy.

Method:

- GET only

Example:

GET http://deviceIP:8088/api/forward?url=https://api.smartthings.com/v1/devices

Uses:

- JSON API calls

- Reading static HTML pages

- SmartThings REST API calls

Features:

- Passes most request headers

- Automatically uses credentials if the Authorization header is missing when calling SmartThings APIs

- Does not execute JavaScript

- May be weak against Cloudflare/browser validation pages

Caution:

- Not suitable for sites that require JavaScript execution

4.4 GET or POST /api/web?url=origin_address

Description: Opens the page in an actual WebView and returns the final HTML.

Method:

- GET or POST

Usage:

- Sites requiring JavaScript execution

- Cloudflare validation pages

- Sites not loaded via /api/forward

Example:

GET http://deviceIP:8088/api/web?url=https://

Or:

POST http://deviceIP:8088/api/web

Content-Type: application/json

{

"url": "https://",

"timeoutMs": 20000

}

Response:

- Final HTML body (text/html) on success

- Error string on failure

Features:

- Opens page like a real browser

- JavaScript execution possible

- Slow but robust

Timeout Parameters:

- timeout: seconds

- timeoutSeconds: seconds

- timeoutMs: milliseconds

Example:

- ?timeout=20

- ?timeoutSeconds=20

- ?timeoutMs=20000

Note:

- The response is the HTML body itself, not JSON.

- The caller needs to parse the HTML to obtain the necessary values.

4.5 GET or POST /api/webview/run

Description:

Runs a page in a background WebView for a set period of time.

Method:

- GET or POST

Uses:

- Keep a specific page running in the background for a set period of time.

- Keep JS operations/page execution running.

Example:

GET http://deviceIP:8088/api/webview/run?url=http://hubaddress:port&timeout=60

Features:

- Runs up to 5 pages simultaneously.

- Excess requests are stored in a queue.

4.6 GET /api/webview/stop

Description:

Stops the execution of a background WebView.

Method:

- Currently used as GET

5. Difference between /api/forward and /api/web

/api/forward

- Standard HTTP proxy

- Fast

- Suitable for JSON/API calls

- Does not execute JavaScript

- Suitable for static pages/general APIs

/api/web

- WebView-based browser read

- Slow but robust

- JavaScript executable

- Supports Cloudflare/browser validation pages

- Suitable for pages requiring a browser

Recommended Criteria:

- General APIs/Static pages: /api/forward

- Pages that need to be opened in a browser: /api/web

6. Summary of Allowed Methods

POST only

- /api/ping

- /api/smartthings/token

- /api/smartthings/access-token

GET only

- /api/smartthings/devices

- /api/forward

GET or POST

- /api/web

- /api/webview/run

For stopping

- /api/webview/stop

7. Explanation of bridgeDevice Value

The bridgeDevice for /api/ping is one of the following:

- tv

- pad

- phone

Determination Criteria:

- tv: Android TV / Leanback devices

- pad: smallestScreenWidthDp >= 600

- phone: Others

8. Usage Examples

8.1 Check Server Status

POST /api/ping

8.2 Check Device List

GET /api/smartthings/devices

8.3 General API Proxy

GET /api/forward?url=https://api.smartthings.com/v1/devices

8.4 Read Sites Require a Browser

GET /api/web?url=https://

9. Summary

SmartWeb is a local bridge server running on Android devices.

Key Points:

- Check SmartThings authentication status

- Simple device list API

- Standard HTTP proxy (/api/forward)

- WebView-based browser reading (/api/web)

- Run WebView in the background (/api/webview/run)

In particular, the /api/web function allows you to read pages that are difficult to read via standard HTTP requests using an actual browser method.