API Reference

This document describes the REST API for integrating WaterGuard data into your own systems. The API allows dealers and developers to retrieve device data, manage configurations, and receive real-time events via webhooks.

Authentication

All API requests require authentication using an API key. Contact your myCistern account manager to obtain an API key.

Request Headers

Authorization: Bearer <your-api-key>
Content-Type: application/json

Rate Limiting

The API enforces rate limiting to ensure fair usage. Limits are applied per API key.

Tier	Requests per minute	Requests per hour
Standard	60	1000
Premium	300	5000

Exceeding the rate limit returns a 429 Too Many Requests response.

Base URL

All API endpoints are relative to the following base URL:

https://api.mycistern.com/v1

Endpoints

List Devices

Retrieves a list of all WaterGuard devices associated with your account.

GET /devices

Response

{
  "devices": [
    {
      "id": "wg-123456",
      "name": "Main Cistern",
      "model": "refill",
      "firmware_version": "2.1.0",
      "online": true,
      "last_seen": "2025-01-15T14:30:00Z"
    }
  ]
}

Get Device Details

Retrieves detailed information about a specific device.

GET /devices/{device_id}

Parameters

Parameter	Type	Description
`device_id`	string	The unique identifier of the device

Response

{
  "id": "wg-123456",
  "name": "Main Cistern",
  "model": "refill",
  "firmware_version": "2.1.0",
  "online": true,
  "last_seen": "2025-01-15T14:30:00Z",
  "cistern": {
    "capacity_liters": 5000,
    "current_level_percent": 72,
    "refill_threshold_percent": 30,
    "high_level_alert_percent": 95
  },
  "sensor": {
    "status": "ok",
    "last_reading": "2025-01-15T14:30:00Z",
    "signal_quality": "good"
  },
  "filter": {
    "status": "clean",
    "last_cleaned": "2025-01-01T10:00:00Z"
  }
}

Get Water Level History

Retrieves historical water level data for a device.

GET /devices/{device_id}/history

Parameters

Parameter	Type	Default	Description
`device_id`	string	—	The unique identifier of the device
`from`	ISO 8601	24 hours ago	Start of the time range
`to`	ISO 8601	now	End of the time range
`interval`	string	`1h`	Aggregation interval: `5m`, `15m`, `1h`, `1d`

Response

{
  "device_id": "wg-123456",
  "interval": "1h",
  "data_points": [
    {
      "timestamp": "2025-01-15T13:00:00Z",
      "level_percent": 70,
      "temperature_celsius": 12.5
    },
    {
      "timestamp": "2025-01-15T14:00:00Z",
      "level_percent": 72,
      "temperature_celsius": 12.3
    }
  ]
}

Update Device Configuration

Updates the configuration of a specific device.

PATCH /devices/{device_id}/config

Request Body

{
  "name": "Main Cistern - Garden",
  "refill_threshold_percent": 25,
  "high_level_alert_percent": 90,
  "cistern_capacity_liters": 5000
}

Response

{
  "success": true,
  "device_id": "wg-123456",
  "updated_fields": ["name", "refill_threshold_percent"]
}

Trigger Relay Output (Refill Only)

Manually triggers a relay output on a WaterGuard Refill device.

POST /devices/{device_id}/relay

Request Body

{
  "output": 1,
  "action": "activate",
  "duration_seconds": 60
}

Parameters

Field	Type	Description
`output`	integer	Relay output number (1 or 2)
`action`	string	`activate` or `deactivate`
`duration_seconds`	integer	Duration in seconds (omit for indefinite)

Webhooks

Webhooks allow your system to receive real-time events from WaterGuard devices. Configure webhook endpoints in the myCistern dashboard.

Register a Webhook

POST /webhooks

Request Body

{
  "url": "https://your-server.com/webhooks/mycistern",
  "events": ["device.online", "device.offline", "level.low", "filter.dirty", "error"],
  "secret": "your-webhook-secret"
}

Supported Events

Event	Description
`device.online`	Device came online
`device.offline`	Device went offline
`level.low`	Water level dropped below threshold
`level.high`	Water level exceeded high alert threshold
`filter.dirty`	Filter requires cleaning
`error`	Device reported an error
`firmware.updated`	Firmware update completed

Webhook Payload

{
  "event": "level.low",
  "device_id": "wg-123456",
  "timestamp": "2025-01-15T14:30:00Z",
  "data": {
    "level_percent": 28,
    "threshold_percent": 30
  }
}

Webhook Signature Verification

Each webhook request includes a signature header for verification:

X-MyCistern-Signature: t=1705314600,v1=abc123def456...

The signature is computed using HMAC-SHA256 with your webhook secret:

HMAC-SHA256(secret, timestamp + "." + request_body)

Data Formats

Timestamps

All timestamps are in ISO 8601 format (UTC):

2025-01-15T14:30:00Z

Units

Measurement	Unit
Water level	Percentage (0–100)
Cistern capacity	Liters
Temperature	Celsius
Duration	Seconds

Error Responses

{
  "error": {
    "code": "device_not_found",
    "message": "No device found with the specified ID",
    "details": {
      "device_id": "wg-invalid"
    }
  }
}

HTTP Status	Error Code	Description
400	`invalid_request`	Malformed request body
401	`unauthorized`	Missing or invalid API key
404	`device_not_found`	Device ID does not exist
429	`rate_limit_exceeded`	Too many requests
500	`internal_error`	Server error

Owner input required

What is known: API endpoint structure and data format specifications

What is missing: Exact API key provisioning process and webhook secret rotation policy

Questions for the product owner:

How are API keys provisioned for dealers?
Is there a webhook secret rotation policy?
What is the webhook retry policy for failed deliveries?

Safe to publish without this information: Yes

Source document: WG-API-EN-v1

Source pages: 1, 2, 3, 4

Content status: Source-backed

API Reference

On this page