Introduction

This page establishes the core model before you integrate. It does not list every endpoint parameter. Instead, it explains the main objects, request patterns, device state model, and command lifecycle used by WLTE OpenAPI.

If you only want to run the first request immediately, go to Quick Start.

What Is WLTE OpenAPI?

WLTE OpenAPI is designed for server-side systems. It lets your platform read, control, and monitor WLTE devices.

Typical capabilities include:

• Listing devices accessible to an account
• Reading one device's state and peripheral data
• Loading device type definitions and supported operations
• Submitting relay, RS485, and configuration commands
• Querying command results
• Receiving real-time device events over WebSocket

Core Concepts

Concept	Description
API Client	The calling identity created in the Developer Console for one application
clientId / clientSecret	Server-side credentials used to obtain an access token
Access token	Short-lived token used to call protected endpoints
Device	A WLTE device accessible to the account
Device Type	Device definition describing supported peripherals and operations
Peripheral State	State of relays, digital inputs, sensors, analog inputs, and other peripherals
Command	One device operation request, such as relay control, RS485 transceive, or configuration update
WebSocket Event	Real-time notification for state changes, connection changes, power loss, and similar events

Integration Model

Your server should store clientSecret and obtain access tokens. Browsers, mobile apps, and other clients should not store clientSecret directly.

REST API and WebSocket

REST API and WebSocket are not replacements for each other. They serve different responsibilities.

Scenario	Recommended Method
Obtain access token	REST API
List devices	REST API
Load device type definitions	REST API
Submit device commands	REST API or WebSocket, depending on your connection model
Query command results	REST API
Explicitly refresh one device	REST API GET /devices/{deviceId} or WebSocket device.state.get
Monitor online, offline, power-loss, or state-change events	WebSocket

For first-time integration, use REST API to verify authentication, device listing, and one device-state query. Add WebSocket when your product needs real-time events.

See REST API vs WebSocket for a more detailed comparison.

Device State Model

Device state should be interpreted by use case.

Data	Use Case	Description
Device list state	List views, dashboards, background synchronization	Data already synchronized by the platform and suitable for bulk display
Single-device real-time state	Detail-page refreshes and before/after operation checks	The server attempts to actively refresh one device
WebSocket events	Continuous state monitoring	Real-time notifications for connection changes, power loss, peripheral changes, and similar events

Do not use high-frequency HTTP polling across all devices to monitor peripherals, offline state, or power loss. Continuous monitoring should use WebSocket events. After reconnecting, use the device list or single-device status endpoint to re-establish critical state.

Command Model

Device commands usually have two phases:

1. The platform accepts the request.
2. The device confirms the final result, or the wait window times out.

Common statuses:

Status	Meaning
SUCCESS	The device confirmed the result
TIMEOUT	No final confirmation arrived within the wait window
FAILED	The command failed or was explicitly rejected
SENT	The command was sent but has no terminal status yet; this is usually seen when querying an existing command

TIMEOUT does not prove that the device did not execute the command. The device may have executed it while the confirmation was delayed or lost. For commands with side effects, do not blindly repeat the request after a timeout. Read the current device state first, then decide what to do.

Permission and Security Model

API clients use scopes to control access. Common rules:

• Read-only queries usually require device:read
• Device control usually requires device:control
• Device configuration usually requires device:config
• Device management usually requires device:manage

If a request returns AUTH_SCOPE_DENIED, the response identifies the missing permission. Update the API client permissions in the Developer Console and obtain a new access token.

Security boundaries:

• Store clientSecret only on your server
• Do not write clientSecret, access tokens, or WebSocket tickets to frontend code, public repositories, or logs
• After an API client is disabled or deleted, existing tokens are rejected
• After rotating a secret, update your server-side secret configuration and obtain a new token

Recommended Integration Path

1. Create an API client in the Developer Console.
2. Use Bruno to verify authentication, device listing, and one device-state query.
3. Load device type definitions to confirm supported peripherals and operations.
4. Choose REST API, WebSocket, or both based on your product workflow.
5. Integrate from your server using an SDK or direct HTTP/WebSocket calls.
6. Before production, review permissions, rate limits, retries, idempotency, and log redaction.

Next step: go to Quick Start.