Wattwatchers REST API v3 (Mercury)

{
  "openapi": "3.0.0",
  "info": {
    "title": "Wattwatchers API",
    "description": "API for accessing Wattwatchers data and functionality",
    "contact": {
      "name": "Wattwatchers Support",
      "url": "https://service.wattwatchers.com.au/kb-tickets/new",
      "email": "support@wattwatchers.com.au"
    },
    "version": "3.6.0"
  },
  "servers": [
    {
      "description": "Wattwatchers API v3",
      "url": "https://api-v3.wattwatchers.com.au"
    }
  ],
  "paths": {
    "/devices": {
      "get": {
        "tags": ["Devices"],
        "summary": "Get devices",
        "description": "Returns an array of devices that are available to the current API key.",
        "operationId": "listDevices",
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Devices"
                },
                "example": [
                  "D123456789012",
                  "D234567890123",
                  "D345678901234"
                ]
              }
            }
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      }
    },
    "/devices/{device-id}": {
      "get": {
        "tags": ["Devices"],
        "summary": "Get device details",
        "description": "Returns the status, state, and metadata for a specific device",
        "operationId": "getDevice",
        "parameters": [
          {
            "name": "device-id",
            "in": "path",
            "required": true,
            "description": "The ID of the device to retrieve",
            "schema": {
              "type": "string"
            },
            "example": "D123456789012"
          }
        ],
        "responses": {
          "200": {
            "description": "Device details successfully retrieved",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/DeviceDetailsCellular"
                    },
                    {
                      "$ref": "#/components/schemas/DeviceDetailsWiFi"
                    }
                  ]
                },
                "examples": {
                  "Cellular device": {
                    "$ref": "#/components/examples/DeviceDetailsCellular" 
                  },
                  "WiFi device": {
                    "$ref": "#/components/examples/DeviceDetailsWiFi"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized access",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "Unauthorized",
                  "httpCode": 401,
                  "message": "API key is missing or invalid."
                }
              }
            }
          },
          "403": {
            "description": "Forbidden access",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "Forbidden",
                  "httpCode": 403,
                  "message": "API key is missing or invalid."
                }
              }
            }
          },
          "404": {
            "description": "Device not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "Not Found",
                  "httpCode": 404,
                  "message": "Device with the specified ID does not exist."
                }
              }
            }
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      },
      "patch": {
        "tags": ["Devices"],
        "summary": "Patch device metadata and state",
        "description": "Enables updating of a subset of fields for a device and related objects (such as channels and switches).",
        "operationId": "updateDevice",
        "parameters": [
          {
            "name": "device-id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The ID of the device to update",
            "example": "D123456789012"
          }
        ],
        "requestBody": {
          "description": "Device metadata and state to update",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DevicePatchBody"
              },
              "examples": {
                "default": {
                  "$ref": "#/components/examples/DevicePatchBody"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/DeviceDetailsCellular"
                    },
                    {
                      "$ref": "#/components/schemas/DeviceDetailsWiFi"
                    }
                  ]
                },
                "examples": {
                  "default": {
                    "$ref": "#/components/examples/DeviceDetailsCellular" 
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      }
    },
    "/devices/channel-categories": {
      "get": {
        "tags": ["Devices"],
        "summary": "Get category definitions for device channels",
        "description": "Returns a collection of the categorisation schema for channels",
        "operationId": "getChannelCategories",
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeviceChannelCategories"
                },
                "example": [
                  {
                    "id": -1,
                    "label": "Not set",
                    "description": "No category has been set for this channel."
                  },
                  {
                    "id": 0,
                    "label": "Not connected",
                    "description": "The channel is available on the device, but is not connected to a circuit."
                  },
                  {
                    "id": 1,
                    "label": "Grid connect",
                    "description": "The channel monitors imports and exports to the electricity grid."
                  },
                  {
                    "id": 2,
                    "label": "Lighting & Power",
                    "description": "The channel monitors a single circuit covering Lighting and Power combined."
                  },
                  {
                    "id": 3,
                    "label": "Pool pump",
                    "description": "The channel monitors energy consumption of a pool pump."
                  },
                  {
                    "id": 4,
                    "label": "Air conditioning",
                    "description": "The channel monitors energy consumption of an air conditioner appliance."
                  },
                  {
                    "id": 5,
                    "label": "Solar generation",
                    "description": "The channel monitors the total amount of power generated by a solar installation (before consumption/export)."
                  },
                  {
                    "id": 6,
                    "label": "Hot water",
                    "description": "The channel monitors energy consumption of an electric hot water system."
                  },
                  {
                    "id": 7,
                    "label": "Electric vehicle",
                    "description": "The channel monitors consumption and exports from the battery charger of an electric vehicle."
                  },
                  {
                    "id": 8,
                    "label": "Battery",
                    "description": "The channel monitors charging + exports to/from a premises-based electricity storage system."
                  },
                  {
                    "id": 9,
                    "label": "Oven",
                    "description": "The channel monitors energy consumption of an oven appliance."
                  },
                  {
                    "id": 10,
                    "label": "Lighting",
                    "description": "The channel monitors energy consumption related to lighting."
                  },
                  {
                    "id": 11,
                    "label": "Power",
                    "description": "The channel monitors power consumption that isn't covered in any other category."
                  },
                  {
                    "id": 12,
                    "label": "Hybrid solar & battery system",
                    "description": "The channel monitors energy generation and consumption from a hybrid solar & battery system."
                  }
                ]
              }
            }
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      }
    },
    "/devices/models": {
      "get": {
        "tags": ["Devices"],
        "summary": "Get valid device models",
        "description": "Returns a list of valid device models supported by Wattwatchers.",
        "operationId": "getDeviceModels",
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeviceModels"
                },
                "example": [
                  {
                    "code": "3M",
                    "displayName": "Auditor 3M",
                    "channelsCount": 3,
                    "switchesCount": 0,
                    "communications": "cellular"
                  },
                  {
                    "code": "6M",
                    "displayName": "Auditor 6M",
                    "channelsCount": 6,
                    "switchesCount": 0,
                    "communications": "cellular"
                  },
                  {
                    "code": "6M+One",
                    "displayName": "Auditor 6M+One",
                    "channelsCount": 6,
                    "switchesCount": 0,
                    "communications": "cellular"
                  },
                  {
                    "code": "6M+3SW",
                    "displayName": "Auditor 6M+3SW",
                    "channelsCount": 6,
                    "switchesCount": 3,
                    "communications": "cellular"
                  },
                  {
                    "code": "6MW-CER",
                    "displayName": "Auditor 6MW-CER",
                    "channelsCount": 6,
                    "switchesCount": 1,
                    "communications": "cellular+wifi"
                  }
                ]
              }
            }
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      }
    },
    "/short-energy/{device-id}": {
      "get": {
        "tags":["Short Energy"],
        "summary": "Get short energy data for a device",
        "description": "Retrieves short-term energy data for a specific device",
        "operationId": "getShortEnergyData",
        "parameters": [
          {
            "$ref": "#/components/parameters/deviceId"
          },
          {
            "$ref": "#/components/parameters/fromTsShort"
          },
          {
            "$ref": "#/components/parameters/toTsShort"
          },
          {
            "$ref": "#/components/parameters/filterGroup"
          },
          {
            "$ref": "#/components/parameters/convertEnergy"
          },
          {
            "$ref": "#/components/parameters/fieldsEnergyPF"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ShortEnergyData"
                },
                "example": [
                  {
                    "timestamp": 1550622130,
                    "duration": 5,
                    "frequency": 50.04,
                    "eReal": [
                      1150,
                      2,
                      38
                    ],
                    "eReactive": [
                      -857,
                      -19,
                      -364
                    ],
                    "vRMS": [
                      244.9,
                      244.8,
                      244.8
                    ],
                    "iRMS": [
                      1.259,
                      0.028,
                      0.31
                    ]
                  },
                  {
                    "timestamp": 1550622135,
                    "duration": 5,
                    "frequency": 50.04,
                    "eReal": [
                      1142,
                      3,
                      39
                    ],
                    "eReactive": [
                      -857,
                      -19,
                      -364
                    ],
                    "vRMS": [
                      244.3,
                      244.2,
                      244.3
                    ],
                    "iRMS": [
                      1.252,
                      0.028,
                      0.309
                    ]
                  }
                ]
              }
            }
          },
          "204": {
            "description": "No Content - No energy data has been received from the device"
          },
          "422": {
            "description": "Period > 12 hours",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "UNPROCESSABLE_ENTITY",
                  "httpCode": 422,
                  "message": "The requested time period is greater than 12 hours."
                }
              }
            }
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      }
    },
    "/short-energy/{device-id}/first": {
      "get": {
        "tags": ["Short Energy"],
        "summary": "Get first short energy data entry",
        "description": "Returns the first received short energy entry from the device.",
        "operationId": "getFirstShortEnergyData",
        "parameters": [
          {
            "$ref": "#/components/parameters/deviceId"
          },
          {
            "$ref": "#/components/parameters/filterGroup"
          },
          {
            "$ref": "#/components/parameters/convertEnergy"
          },
          {
            "$ref": "#/components/parameters/fieldsEnergyPFAndTimestamp"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ShortEnergyDataPoint"
                },
                "examples": {
                  "default": {
                    "$ref": "#/components/examples/ShortEnergyDataPoint"
                  },
                  "withTimestampOnly": {
                    "$ref": "#/components/examples/FirstLastTimestampOnly"
                  }
                }
              }
            }
          },
          "204": {
            "description": "No Content - No energy data has been received from the device"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      }
    },
    "/short-energy/{device-id}/latest": {
      "get": {
        "tags": ["Short Energy"],
        "summary": "Get latest short energy data entry",
        "description": "Returns the latest received short energy entry from the device.",
        "operationId": "getLatestShortEnergyData",
        "parameters": [
          {
            "$ref": "#/components/parameters/deviceId"
          },
          {
            "$ref": "#/components/parameters/filterGroup"
          },
          {
            "$ref": "#/components/parameters/convertEnergy"
          },
          {
            "$ref": "#/components/parameters/fieldsEnergyPFAndTimestamp"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ShortEnergyDataPoint"
                },
                "examples": {
                  "default": {
                    "$ref": "#/components/examples/ShortEnergyDataPoint"
                  },
                  "withTimestampOnly": {
                    "$ref": "#/components/examples/FirstLastTimestampOnly"
                  }
                }
              }
            }
          },
          "204": {
            "description": "No Content - No energy data has been received from the device"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      }
    },
    "/long-energy/{device-id}": {
      "get": {
        "tags": ["Long Energy"],
        "summary": "Get long energy data for a device",
        "description": "Returns the energy data for a single device.",
        "operationId": "getLongEnergyData",
        "parameters": [
          {
            "$ref": "#/components/parameters/deviceId"
          },
          {
            "$ref": "#/components/parameters/fromTsLong"
          },
          {
            "$ref": "#/components/parameters/toTsLong"
          },
          {
            "$ref": "#/components/parameters/granularity"
          },
          {
            "$ref": "#/components/parameters/timezone"
          },
          {
            "$ref": "#/components/parameters/filterGroup"
          },
          {
            "$ref": "#/components/parameters/convertEnergy"
          },
          {
            "$ref": "#/components/parameters/fieldsEnergyPF"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LongEnergyData"
                },
                "example": [
                  {
                    "timestamp": 1550408400,
                    "duration": 900,
                    "eReal": [
                      3639405,
                      336898,
                      -560,
                      37,
                      -14,
                      -25
                    ],
                    "eRealNegative": [
                      0,
                      0,
                      560,
                      0,
                      14,
                      25
                    ],
                    "eRealPositive": [
                      3639405,
                      336898,
                      0,
                      37,
                      0,
                      0
                    ],
                    "eReactive": [
                      154581,
                      140216,
                      61,
                      45,
                      -4,
                      11
                    ],
                    "eReactiveNegative": [
                      13832,
                      0,
                      0,
                      0,
                      5,
                      0
                    ],
                    "eReactivePositive": [
                      168413,
                      140216,
                      61,
                      45,
                      1,
                      11
                    ],
                    "vRMSMin": [
                      229.4,
                      229.5,
                      229.6,
                      229.4,
                      229.5,
                      229.6
                    ],
                    "vRMSMax": [
                      232.2,
                      232.4,
                      232.4,
                      232.2,
                      232.4,
                      232.5
                    ],
                    "iRMSMin": [
                      14.799,
                      0.331,
                      0.023,
                      0.023,
                      0.023,
                      0.022
                    ],
                    "iRMSMax": [
                      21.208,
                      4.534,
                      0.043,
                      0.046,
                      0.043,
                      0.042
                    ]
                  }
                ]
              }
            }
          },
          "204": {
            "description": "No Content - No energy data has been received from the device"
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "BAD_REQUEST",
                  "httpCode": 400,
                  "message": "You must specify a valid timezone value when applying granularity of 'hour', 'day', 'week', or 'month.'"
                }
              }
            }
          },
          "422": {
            "description": "Unprocessable Entity - Period is greater than valid values for granularity",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "UNPROCESSABLE_ENTITY",
                  "httpCode": 422,
                  "message": "The requested time period is greater than 7 days."
                }
              }
            }
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      }
    },
    "/long-energy/{device-id}/first": {
      "get": {
        "tags": ["Long Energy"],
        "summary": "Get first long energy data entry",
        "description": "Returns the first received long energy entry from the device.",
        "operationId": "getFirstLongEnergyData",
        "parameters": [
          {
            "$ref": "#/components/parameters/deviceId"
          },
          {
            "$ref": "#/components/parameters/filterGroup"
          },
          {
            "$ref": "#/components/parameters/convertEnergy"
          },
          {
            "$ref": "#/components/parameters/fieldsEnergyPFAndTimestamp"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LongEnergyDataPoint"
                },
                "examples": {
                  "default": {
                    "$ref": "#/components/examples/LongEnergyDataPoint"
                  },
                  "withTimestampOnly": {
                    "$ref": "#/components/examples/FirstLastTimestampOnly"
                  }
                }
              }
            }
          },
          "204": {
            "description": "No Content - No energy data has been received from the device"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      }
    },
    "/long-energy/{device-id}/latest": {
      "get": {
        "tags": ["Long Energy"],
        "summary": "Get latest long energy data entry",
        "description": "Returns the latest received long energy entry from the device.",
        "operationId": "getLatestLongEnergyData",
        "parameters": [
          {
            "$ref": "#/components/parameters/deviceId"
          },
          {
            "$ref": "#/components/parameters/filterGroup"
          },
          {
            "$ref": "#/components/parameters/convertEnergy"
          },
          {
            "$ref": "#/components/parameters/fieldsEnergyPFAndTimestamp"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LongEnergyDataPoint"
                },
                "examples": {
                  "default": {
                    "$ref": "#/components/examples/LongEnergyDataPoint"
                  },
                  "withTimestampOnly": {
                    "$ref": "#/components/examples/FirstLastTimestampOnly"
                  }
                }
              }
            }
          },
          "204": {
            "description": "No Content - No energy data has been received from the device"
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      }
    },
    "/modbus/{device-id}": {
      "get": {
        "tags": ["Modbus"],
        "summary": "Get modbus energy data for a device",
        "description": "Returns the modbus energy data for a specific device.",
        "operationId": "getModbusData",
        "parameters": [
          {
            "$ref": "#/components/parameters/deviceId"
          },
          {
            "$ref": "#/components/parameters/fromTsModbus"
          },
          {
            "$ref": "#/components/parameters/toTsModbus"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/ModbusDataPMC-340B"
                    },
                    {
                      "$ref": "#/components/schemas/ModbusDataPMC-220"
                    }
                  ]
                },
                "examples": {
                  "PMC-340B": {
                    "description": "Response for a PMC-340B device",
                    "value": [
                      {
                        "_Ia": 0,
                        "_Ib": 0,
                        "_Ic": 0,
                        "_PFa": 1,
                        "_PFb": 1,
                        "_PFc": 1,
                        "_Uan": 244.8056182861328,
                        "_Ubn": 122.43417358398438,
                        "_Ucn": 122.45341491699219,
                        "kVAh": 0,
                        "kWh_Exp": 0,
                        "kWh_Imp": 0,
                        "kWh_Net": 0,
                        "kWh_Tot": 0,
                        "kvarh_Q1": 0,
                        "kvarh_Q2": 0,
                        "kvarh_Q3": 0,
                        "kvarh_Q4": 0,
                        "kvarh_Exp": 0,
                        "kvarh_Imp": 0,
                        "kvarh_Net": 0,
                        "kvarh_Tot": 0,
                        "model": "PMC-340B",
                        "timestamp": 1546952400
                      }
                    ]
                  },
                  "PMC-220": {
                    "description": "Response for a PMC-220 device",
                    "value": [
                      {
                        "_I": 0.3065536916255951,
                        "_V": 245.0169219970703,
                        "_PF": 0.5856215357780457,
                        "kVAh": 616,
                        "kWh_Exp": 0,
                        "kWh_Imp": 283,
                        "kWh_Net": 283,
                        "kWh_Tot": 283,
                        "kvarh_Exp": 173,
                        "kvarh_Imp": 0,
                        "kvarh_Net": -173,
                        "kvarh_Tot": 173,
                        "model": "PMC-220",
                        "timestamp": 1546956000
                      }
                    ]
                  }
                }
              }
            }
          },
          "204": {
            "description": "No Content - No modbus data has been received from the device, or the device is not a modbus-capable device"
          },
          "422": {
            "description": "Unprocessable Entity",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "PeriodTooLong": {
                    "value": {
                      "code": "UNPROCESSABLE_ENTITY",
                      "httpCode": 422,
                      "message": "The requested time period is greater than 7 days."
                    }
                  },
                  "NonModbusDevice": {
                    "value": {
                      "code": "UNPROCESSABLE ENTITY",
                      "httpCode": 422,
                      "message": "You have attempted to query modbus data for a device ID that does not support it"
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "BearerAuth": []
          }
        ]
      }
    },
    "/modbus/{device-id}/first": {
      "get": {
        "tags": ["Modbus"],
        "summary": "Get first modbus energy data entry",
        "description": "Returns the first recorded modbus energy data entry for a specific device.",
        "operationId": "getFirstModbusData",
        "parameters": [
          {
            "$ref": "#/components/parameters/deviceId"
          },
          {
            "$ref": "#/components/parameters/fieldsEnergyTimestamp"
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/ModbusDataPointPMC-340B"
                    },
                    {
                      "$ref": "#/components/schemas/ModbusDataPointPMC-220"}
                  ]
                },
                "examples": {
                  "PMC-340B": {
                    "$ref": "#/components/examples/PMC-340B"
                  },
                  "PMC-220": {
                    "$ref": "#/components/examples/PMC-220"
                  },
                  "withTimestampOnly": {
                    "$ref": "#/components/examples/FirstLastTimestampOnly"
                  }
                }
              }
            }
          },
          "204": {
            "description": "No Content - No modbus data has been received from the device, or the device is not a modbus-capable device"
          },
          "422": {
            "description": "Unprocessable Entity",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "code": "UNPROCESSABLE ENTITY",
                  "httpCode": 422,
                  "message": "You have attempted to query modbus data for a device ID that does not support it"
                }
              }
            }
          }
        },
    

# --- truncated at 32 KB (85 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/wattwatchers/refs/heads/main/openapi/wattwatchers-rest-api-v3-openapi.json