Overview

Device API v1 works with every SplashMe controller. Each endpoint addresses one controller:

/api-gateway/v1/iot-shadow/device/{deviceId}/…

and requires a bearer token whose user owns that controller. See Users & sites for how to find deviceId values.

Endpoints

Endpoint	Purpose
GET …/dashboardInfo	Live overview: pH, ORP, pump, heaters, flow
GET …/chemistryCard	Chemistry readings, pH and chlorine dosing settings, equipment slots
GET …/pumpInfo	Main pump model, speed, flow, dry-run protection
GET …/auxInfo	Every equipment slot and whether it is on
GET …/ambientTemp	Water and air temperature
POST …/setPhSettings	pH dosing configuration
POST …/setChlorineSettings	Chlorine and ORP configuration
POST …/setPumpInfo	Main pump on, off and speed
POST …/manualSet	Any equipment slot on or off
GET …/scheduleInfo	All schedules
POST …/changeScheduleStatus	Enable or disable a schedule
POST …/createSchedule	Add a schedule
POST …/updateSchedule	Replace a schedule
POST …/deleteSchedule	Remove a schedule

Reads are on Reading state; writes on Chemistry, Pump and equipment and Schedules.

How reads work

Every read asks the controller for a fresh copy of the relevant data, but the API keeps the last answer for each controller and endpoint:

• If a cached answer exists it is returned immediately, and a refresh is requested from the controller in the background, at most once every 30 seconds per endpoint.
• If there is no cached answer the call waits for the controller, typically well under a second, up to 3 seconds per controller request. dashboardInfo allows 10 seconds. scheduleInfo, and pumpInfo when uncached, make two controller requests, so allow up to about 6 seconds. Add any time spent waiting behind other commands to the same controller.

In practice this means the first read after a write, or after a long idle period, may be slightly stale. Read again a couple of seconds later to see the refreshed value. Successful writes clear the cached answers they affect, so the next read goes to the controller.

How writes work

A write sends a command to the controller and waits for its acknowledgement: up to 10 seconds for setPumpInfo and manualSet, up to 3 seconds for chemistry and schedule writes. 200 with "status": "SUCCESS" means the controller accepted the command; data.message carries the controller’s raw reply and is informational. Read the corresponding state afterwards to confirm the effect.

Commands to one controller are executed one at a time with a short spacing between them. Sending many writes at once to the same controller queues them, and beyond a small queue the API returns 429. See Rate limits and throttling.

Status codes

Status	Meaning
200	Success. For chemistryCard, check partial as well.
400	Invalid JSON or a value outside its allowed range. message describes the problem.
401	Missing or invalid bearer token
403	The user does not own this controller
404	Unknown endpoint. Only the endpoints listed above exist on the gateway.
429	Controller busy or cooling down; message contains device busy:. Back off and retry.
500	The controller did not answer in time (… timeout waiting for response), returned something unexpected, or a read had no cached copy while the API’s link to the controller network was down (MQTT client not connected)
503	Writes and scheduleInfo only: the API’s link to the controller network is down (IoT service not connected). Retry later.

Units and conventions

Quantity	Representation
pH	Integer, pH × 10. 74 is pH 7.4
ORP	Millivolts
Water temperature (ambientTemp)	Number, °C × 10. 265 is 26.5 °C
Air temperature (ambientTemp)	Number, °C × 100. 2450 is 24.5 °C. 0 means no sensor
Pump speed	Percent, 0 to 100
Drum volumes	Millilitres
Times of day	Minutes since midnight, 0 to 1439
Days of week	Seven booleans, Monday first
Equipment slots	aux_slot_num, the controller’s slot index as reported by auxInfo. The main pump is slot 0
Equipment types	Numeric codes, see Equipment types