User and site endpoints

All endpoints require a bearer token and return the standard {"status","data"} envelope.

Profile

GET/api-gateway/v1/user/info

{
  "status": "SUCCESS",
  "data": {
    "user": {
      "id": "aB3dE5fG7h",
      "email": "user@example.com",
      "username": "user@example.com",
      "firstName": "Sam",
      "lastName": "Lee",
      "role": "user",
      "userType": "owner"
    }
  }
}

id is the SplashMe account identifier, the same value as sub from the OAuth user info endpoint.

Role

GET/api-gateway/v1/user/role

{ "status": "SUCCESS", "data": { "role": "user", "permissions": ["view_dashboard", "view_reports"] } }

role is normally user, with view_dashboard and view_reports. The permission list is informational; it does not change which API endpoints the token can call.

Sites and controllers

GET/api-gateway/v1/user/sites

Returns every site the account owns or has been invited to, with the controllers at each site.

{
  "status": "SUCCESS",
  "data": {
    "sites": [
      {
        "objectId": "Q1w2E3r4T5",
        "name": "Home",
        "street": "1 Pool St",
        "city": "Sydney",
        "state": "NSW",
        "postcode": "2000",
        "country": "Australia",
        "phone": "",
        "email": "user@example.com",
        "note": "",
        "location": { "__type": "GeoPoint", "latitude": -33.86, "longitude": 151.2 },
        "device_list": [
          {
            "objectId": "Zx9Yw8Vu7t",
            "deviceId": "02_53_4D_00_00_01",
            "tag": "Backyard pool",
            "address": "",
            "online": true
          }
        ]
      }
    ]
  }
}

Field	Meaning
objectId	Stable site identifier
location	Omitted when the site has no coordinates
device_list[].deviceId	The controller identifier used in every device endpoint
device_list[].tag	The user’s label for the controller
device_list[].online	Whether the controller was connected at the cloud’s last periodic connectivity check

An account with no sites returns "sites": [].

The list is a snapshot taken when the user last signed in or refreshed. If the user has just been given access to a new site, call the refresh endpoint below.

Online status only

GET/api-gateway/v1/user/deviceOnlineStatuses

A flat, de-duplicated list of the same controllers, useful for a cheap poll.

{ "status": "SUCCESS", "data": { "devices": [ { "deviceId": "02_53_4D_00_00_01", "online": true } ] } }

Refresh the site list

POST/api-gateway/v1/user/refreshSite

No body. Re-reads the account’s sites and controllers from the SplashMe account system and updates the ownership records used by device endpoints.

{ "status": "SUCCESS", "data": { "message": "Site refreshed successfully" } }

Limited to once per minute per user; the second call within a minute returns 429 with Retry-After: 60. A 500 means the SplashMe account system could not be reached or the account’s session with it has expired; signing in again through the OAuth flow renews it.

Ownership and device endpoints

A device endpoint accepts a deviceId only if it appears in the signed-in user’s site list. Anything else, including identifiers that do not exist, returns:

{ "status": "FAILED", "message": "Device does not belong to current user" }

with status 403. Newly granted access is effective immediately after a sign-in or refresh; removed access can take up to a minute to be enforced. A 500 with Failed to verify device ownership is a temporary server-side failure; retry.