User API Reference

This document provides a complete reference for all user-facing API endpoints in AquaGen API.

🔐 Authentication

All user API endpoints require JWT authentication. Include your token in one of two ways:

Authorization Header (Recommended)

Authorization: Bearer YOUR_JWT_TOKEN

Query String

?jwt=YOUR_JWT_TOKEN

Token Expiration

Access tokens expire after 4 hours. Use refresh tokens to obtain new access tokens.

📊 Reports API

Generate Report

Generate water management reports in various formats.

GET /api/user/report

Query Parameters

Parameter	Type	Required	Description	Example
`reportType`	string	Yes	Type of report	`daily`, `monthly`, `hourly`, `granular`
`reportFormat`	string	Yes	Output format	`html`, `pdf`, `xlsx`, `csv`
`service`	string	Yes	Service type	`water`, `energy`, `level`, `quality`
`startDate`	string	Yes	Start date (DD/MM/YYYY)	`09/11/2024`
`endDate`	string	No*	End date (DD/MM/YYYY)	`10/11/2024`
`unitId`	string	No	Specific unit/device ID	`unit-123`
`unitIds`	array	No	Multiple unit IDs	`unit-123,unit-456`
`startTime`	integer	No	Start hour (0-23)	`9`
`endTime`	integer	No	End hour (0-23)	`17`
`useShift`	boolean	No	Use shift times	`true`
`divisionFactor`	integer	No	Unit division	`1000`

*Required for hourly, granular, and range report types

Report Types

Service Types

Service	Description	Measures
`water`	Water consumption	Flow, volume
`energy`	Power consumption	kWh, kW, power factor
`level`	Water levels	Height, volume, capacity
`quality`	Water quality	pH, TDS, COD, BOD, DO, etc.
`borewell`	Groundwater	Extraction, water table depth
`rain_water`	Rainfall	Precipitation, collection
`summary`	Consolidated summary	Multi-category overview
`smart_city`	Smart city monitoring	Multi-service urban data
`water_balance`	Water balance analysis	Inflow vs. outflow
`alert`	Alert summary	Alert statistics
`consolidated`	Monthly consolidation	Multi-service monthly
`aqua_gpt`	AI insights	GPT-powered analysis

Examples

Daily Water Report (HTML)

curl -X GET "https://api.aquagen.com/api/user/report?\
reportType=daily&\
reportFormat=html&\
service=water&\
startDate=09/11/2024" \
-H "Authorization: Bearer YOUR_TOKEN"

Monthly Energy Report (PDF)

curl -X GET "https://api.aquagen.com/api/user/report?\
reportType=monthly&\
reportFormat=pdf&\
service=energy&\
startDate=01/11/2024" \
-H "Authorization: Bearer YOUR_TOKEN" \
--output energy_report_nov_2024.pdf

Hourly Quality Report (XLSX)

curl -X GET "https://api.aquagen.com/api/user/report?\
reportType=hourly&\
reportFormat=xlsx&\
service=quality&\
startDate=09/11/2024&\
endDate=09/11/2024&\
unitId=unit-123&\
startTime=9&\
endTime=17" \
-H "Authorization: Bearer YOUR_TOKEN" \
--output quality_report.xlsx

Granular Data (CSV)

curl -X GET "https://api.aquagen.com/api/user/report?\
reportType=granular&\
reportFormat=csv&\
service=water&\
startDate=09/11/2024&\
endDate=09/11/2024&\
unitId=unit-123" \
-H "Authorization: Bearer YOUR_TOKEN" \
--output granular_data.csv

Response

Success (200 OK)

Returns file download with appropriate Content-Type:

Content-Type: application/pdf
Content-Disposition: attachment; filename="daily_water_report_09_11_2024.pdf"

[Binary PDF data]

Error (1401 Data Not Found)

{
  "message": "No data found for the specified date range",
  "status": "failed",
  "status_code": 1401
}

📡 Device Data API

Get Device Data

Retrieve latest or historical device/sensor data.

GET /api/user/deviceData

Query Parameters

Parameter	Type	Required	Description
`categoryType`	string	No	Category filter (`source`, `stock`, `energy`, `quality`)
`unitId`	string	No	Specific unit ID
`startDate`	string	No	Start date (DD/MM/YYYY)
`endDate`	string	No	End date (DD/MM/YYYY)
`startTime`	integer	No	Start hour (0-23)
`endTime`	integer	No	End hour (0-23)

Example

curl -X GET "https://api.aquagen.com/api/user/deviceData?\
categoryType=source&\
unitId=unit-123&\
startDate=09/11/2024" \
-H "Authorization: Bearer YOUR_TOKEN"

Response

{
  "status": "success",
  "status_code": 200,
  "data": {
    "units": [
      {
        "unitId": "unit-123",
        "unitName": "Main Water Meter",
        "categoryType": "source",
        "readings": [
          {
            "timestamp": "2024-11-09T10:30:00Z",
            "value": 1234.56,
            "unit": "KL",
            "status": "online"
          },
          {
            "timestamp": "2024-11-09T10:35:00Z",
            "value": 1236.42,
            "unit": "KL",
            "status": "online"
          }
        ],
        "statistics": {
          "min": 1234.56,
          "max": 1250.32,
          "avg": 1242.44,
          "total": 15.88
        }
      }
    ]
  }
}

Get Device Data V2 (Enhanced)

Enhanced device data API with polymorphic formatters.

GET /api/user/deviceDataV2

Features

Better performance with optimized queries
Polymorphic formatters for different device types
Enhanced filtering options
Real-time status indicators

⚠️ Alerts API

List Alerts

Get all alerts for the industry.

GET /api/user/alerts

Query Parameters

Parameter	Type	Description
`status`	string	Filter by status (`active`, `resolved`, `all`)
`severity`	string	Filter by severity (`critical`, `high`, `medium`, `low`)
`startDate`	string	Start date filter
`endDate`	string	End date filter

Example

curl -X GET "https://api.aquagen.com/api/user/alerts?status=active&severity=critical" \
-H "Authorization: Bearer YOUR_TOKEN"

Response

{
  "status": "success",
  "status_code": 200,
  "data": {
    "alerts": [
      {
        "alertId": "alert-789",
        "title": "High Water Consumption",
        "description": "Water consumption exceeded threshold",
        "severity": "high",
        "status": "active",
        "triggeredAt": "2024-11-09T14:23:45Z",
        "threshold": {
          "parameter": "flow",
          "operator": "greater_than",
          "value": 1000,
          "unit": "KL"
        },
        "actualValue": 1245.67,
        "unitId": "unit-123",
        "unitName": "Main Water Meter"
      }
    ],
    "total": 1
  }
}

Create Alert

Create a new alert rule.

POST /api/user/alerts

Request Body

{
  "title": "High Water Consumption Alert",
  "description": "Alert when daily consumption exceeds 1000 KL",
  "severity": "high",
  "condition": {
    "parameter": "flow",
    "operator": "greater_than",
    "threshold": 1000,
    "unit": "KL",
    "aggregation": "daily"
  },
  "units": ["unit-123", "unit-456"],
  "channels": {
    "email": {
      "enabled": true,
      "recipients": ["user@example.com"]
    },
    "sms": {
      "enabled": true,
      "phoneNumbers": ["+919999999999"]
    },
    "google_chat": {
      "enabled": true,
      "webhookUrl": "https://chat.googleapis.com/v1/spaces/..."
    }
  },
  "schedule": {
    "enabled": true,
    "timezone": "Asia/Kolkata",
    "quietHours": {
      "start": "22:00",
      "end": "06:00"
    }
  }
}

Response

{
  "status": "success",
  "status_code": 200,
  "message": "Alert created successfully",
  "data": {
    "alertId": "alert-890",
    "createdAt": "2024-11-09T15:30:00Z"
  }
}

Update Alert

Update an existing alert rule.

PUT /api/user/alerts/{alertId}

Delete Alert

Delete an alert rule.

DELETE /api/user/alerts/{alertId}

🔔 Notifications API

Get Notifications

Retrieve notification history.

GET /api/user/notifications

Query Parameters

Parameter	Type	Description
`unreadOnly`	boolean	Show only unread notifications
`limit`	integer	Number of notifications (default: 50)
`offset`	integer	Pagination offset

Example

curl -X GET "https://api.aquagen.com/api/user/notifications?unreadOnly=true&limit=20" \
-H "Authorization: Bearer YOUR_TOKEN"

Response

{
  "status": "success",
  "status_code": 200,
  "data": {
    "notifications": [
      {
        "notificationId": "notif-123",
        "title": "Daily Report Generated",
        "message": "Your daily water report for 09/11/2024 is ready",
        "type": "report",
        "read": false,
        "createdAt": "2024-11-09T16:00:00Z",
        "data": {
          "reportUrl": "https://storage.firebase.com/reports/..."
        }
      }
    ],
    "total": 1,
    "unread": 1
  }
}

Mark Notification as Read

PUT /api/user/notifications/{notificationId}/read

🏠 Landing Page API

Get Landing Page Data

Get dashboard summary data.

GET /api/user/landingPage

Query Parameters

Parameter	Type	Description
`date`	string	Specific date (DD/MM/YYYY)
`period`	string	Time period (`today`, `yesterday`, `week`, `month`)

Example

curl -X GET "https://api.aquagen.com/api/user/landingPage?period=today" \
-H "Authorization: Bearer YOUR_TOKEN"

Response

{
  "status": "success",
  "status_code": 200,
  "data": {
    "date": "2024-11-09",
    "summary": {
      "water": {
        "total": 1245.67,
        "unit": "KL",
        "change": "+5.2%",
        "status": "normal"
      },
      "energy": {
        "total": 3456.78,
        "unit": "kWh",
        "change": "-2.3%",
        "status": "normal"
      },
      "quality": {
        "status": "good",
        "parameters": {
          "pH": 7.2,
          "TDS": 385,
          "COD": 28
        }
      }
    },
    "alerts": {
      "active": 2,
      "critical": 0,
      "high": 2
    },
    "devices": {
      "total": 25,
      "online": 24,
      "offline": 1
    }
  }
}

📈 Granular Data API

Get Granular Data

High-resolution time-series data.

GET /api/user/granularData

Query Parameters

Parameter	Type	Required	Description
`unitId`	string	Yes	Unit ID
`startDate`	string	Yes	Start date
`endDate`	string	Yes	End date
`interval`	integer	No	Data interval in minutes (default: 5)

Example

curl -X GET "https://api.aquagen.com/api/user/granularData?\
unitId=unit-123&\
startDate=09/11/2024&\
endDate=09/11/2024&\
interval=5" \
-H "Authorization: Bearer YOUR_TOKEN"

💧 Water Balance API

Get Water Balance

Water consumption vs. availability analysis.

GET /api/user/waterBalance

Example

curl -X GET "https://api.aquagen.com/api/user/waterBalance?\
startDate=01/11/2024&\
endDate=30/11/2024" \
-H "Authorization: Bearer YOUR_TOKEN"

Response

{
  "status": "success",
  "data": {
    "period": "November 2024",
    "waterBalance": {
      "totalInflow": 15000.0,
      "totalOutflow": 14250.0,
      "balance": 750.0,
      "balancePercentage": 5.0,
      "status": "surplus"
    },
    "sources": {
      "municipalWater": 8000.0,
      "groundwater": 5000.0,
      "rainwater": 2000.0
    },
    "uses": {
      "domestic": 6000.0,
      "industrial": 5250.0,
      "cooling": 3000.0
    },
    "sustainability": {
      "waterNeutralityIndex": 1.05,
      "rating": "good"
    }
  }
}

👤 User API

Get User Profile

GET /api/user/user

Update User Profile

PUT /api/user/user

Change Password

POST /api/user/user/changePassword

🔑 Authentication

POST /api/user/login

Request Body

{
  "email": "user@example.com",
  "password": "your-password",
  "loginType": "email"
}

Response

{
  "status": "success",
  "status_code": 200,
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "userId": "user-123",
      "email": "user@example.com",
      "username": "john.doe",
      "role": "user",
      "industryId": "industry-456",
      "industryName": "Acme Industries"
    },
    "expiresIn": 14400
  }
}

Refresh Token

POST /api/user/refreshToken

Request Body

{
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Logout

POST /api/user/logout

📊 Summary Page API

Get Summary Page

Monthly/daily summary with key insights.

GET /api/user/summaryPage

Rate Limiting

API requests are subject to rate limiting. Contact support for enterprise rate limits.

📚 Next Steps

Admin API Reference - Admin endpoints
Report Generation Guide - Step-by-step tutorial
Authentication Guide - Detailed auth flow

🔐 Authentication​

Authorization Header (Recommended)​

Query String​

📊 Reports API​

Generate Report​

Query Parameters​

Report Types​

Service Types​

Examples​

Response​

📡 Device Data API​

Get Device Data​

Query Parameters​

Example​

Response​

Get Device Data V2 (Enhanced)​

Features​

⚠️ Alerts API​

List Alerts​

Query Parameters​

Example​

Response​

Create Alert​

Request Body​

Response​

Update Alert​

Delete Alert​

🔔 Notifications API​

Get Notifications​

Query Parameters​

Example​

Response​

Mark Notification as Read​

🏠 Landing Page API​

Get Landing Page Data​

Query Parameters​

Example​

Response​

📈 Granular Data API​

Get Granular Data​

Query Parameters​

Example​

💧 Water Balance API​

Get Water Balance​

Example​

Response​

👤 User API​

Get User Profile​

Update User Profile​

Change Password​

🔑 Authentication​

Login​

Request Body​

Response​

Refresh Token​

Request Body​

Logout​

📊 Summary Page API​

Get Summary Page​

📚 Next Steps​

🔐 Authentication

Authorization Header (Recommended)

Query String

📊 Reports API

Generate Report

Query Parameters

Report Types

Service Types

Examples

Response

📡 Device Data API

Get Device Data

Query Parameters

Example

Response

Get Device Data V2 (Enhanced)

Features

⚠️ Alerts API

List Alerts

Query Parameters

Example

Response

Create Alert

Request Body

Response

Update Alert

Delete Alert

🔔 Notifications API

Get Notifications

Query Parameters

Example

Response

Mark Notification as Read

🏠 Landing Page API

Get Landing Page Data

Query Parameters

Example

Response

📈 Granular Data API

Get Granular Data

Query Parameters

Example

💧 Water Balance API

Get Water Balance

Example

Response

👤 User API

Get User Profile

Update User Profile

Change Password

🔑 Authentication

Login

Request Body

Response

Refresh Token

Request Body

Logout

📊 Summary Page API

Get Summary Page

📚 Next Steps