Introduction
The SplashMe Open API is the public interface to the SplashMe cloud platform. It lets your software do, on behalf of a SplashMe user, what the SplashMe app does: see which pool controllers the user owns, read their live state, and change what they are doing.
A SplashMe controller is an ESP32-based device installed at the pool. It manages the filtration pump, chemistry sensing and dosing, heating, lighting, auxiliary equipment such as blowers and water features, and the schedules that tie them together. Every controller keeps a permanent MQTT connection to the SplashMe cloud, and it is that connection your requests travel over.
Who this is for
Section titled “Who this is for”- Integrators building smart-home, energy-management or pool-service software that needs to control a customer’s SplashMe controller with the customer’s consent.
- Pool professionals automating monitoring of many sites from their own tooling.
- Firmware-level integrators who want to talk to a controller directly on the local network, using their own authentication, without going through the SplashMe cloud at all.
What you can do
Section titled “What you can do”| Capability | Where |
|---|---|
| Sign users in and obtain consent with standard OAuth2 | Authentication |
| List a user’s sites and controllers and see which are online | Users & sites |
| Read the dashboard, chemistry, pump and equipment state | Device API v1 |
| Change chemistry set points, pump speeds, equipment and schedules | Device API v1 |
| Read a signed, merged state document and issue signed actions with low latency | Device API v2 |
| Receive the controller’s audit event stream | Device API v2 events |
| Speak the controller’s own binary protocol, in the cloud or on the LAN | Command Protocol v2 |
Two generations of device API
Section titled “Two generations of device API”The platform exposes two device APIs side by side. Both are available through the same OAuth2 gateway and the same access token.
Device API v1 works with every controller. Reads go through the controller’s cloud shadow and writes are JSON commands the cloud forwards to the controller. It is the broadest surface and the one to start with.
Device API v2 is available for controllers running firmware 2.5.46 or later. The controller pushes a compact, cryptographically signed state frame to the cloud whenever anything changes, and accepts signed queries and actions. v2 is faster, cheaper for the controller, and carries an audit trail of every change. Its wire format, Command Protocol v2, is fully documented here so that you can implement it yourself.
The two APIs never interfere with each other. A v1 call behaves the same whether or not the controller supports v2.
Conventions used in this documentation
Section titled “Conventions used in this documentation”- All endpoints are relative to the API base URL shown in Environments.
- Request and response bodies are JSON unless the page says otherwise. Binary protocol frames are shown as hex.
- Device identifiers look like
02_53_4D_00_00_01: the controller’s MAC address with underscores, upper case. - Field tables list the JSON name exactly as the API sends or expects it.