API Reference

info

AquaGen API exposes three blueprints, each serving a distinct audience.

API Blueprints

Blueprint	Base Path	Purpose
User API	/api/user	End-user mobile/web app
Admin API	/api/admin	Platform administration
External API	/api/external	Third-party integrations

Swagger UI URLs

Environment	User API	Admin API	External API
Production	https://prod-aquagen.azurewebsites.net/api/user/docs	https://prod-aquagen.azurewebsites.net/api/admin/docs	https://prod-aquagen.azurewebsites.net/api/external/docs
Development	http://localhost:5001/api/user/docs	http://localhost:5001/api/admin/docs	http://localhost:5001/api/external/docs

---

URL Structure

/api/{blueprint}/{resource}[/{action}]

Segment	Examples
Blueprint	user, admin, external
Resource	deviceData, alerts, industry, accounts
Action	login, refresh, offline, granular

---

Authentication

info

All endpoints (except public login routes) require a JWT token. See Authentication.

Header (recommended):

Authorization: Bearer <token>

Query string (alternative):

?jwt=<token>

Access tokens expire after 4 hours. Refresh tokens expire after 14 days. Use GET /api/user/user/refresh to get a new access token.

note

Every protected route uses current_user['industryId'] (not a request param) as the authoritative industry ID for the authenticated user. Admin routes accept a targetIndustryId header to act on behalf of other industries.

---

HTTP Methods

Method	Usage
GET	Retrieve data — never modifies state
POST	Create a resource or trigger an action with a body
PUT	Full replacement of an existing resource
PATCH	Partial update using JSON Patch operations
DELETE	Remove a resource (soft delete where possible)

---

Standard Response Envelope

tip

All JSON responses use this envelope — check status and status_code before reading data.

All JSON responses use this envelope:

{
  "status": "success",
  "status_code": 200,
  "message": "Operation completed",
  "data": {}
}

On error:

{
  "status": "failed",
  "status_code": 1403,
  "message": "Human-readable error description"
}

---

Date Format

warning

All request parameters use DD/MM/YYYY. Passing dates in any other format (e.g. YYYY-MM-DD) will result in incorrect query results or a validation error.

All request parameters use DD/MM/YYYY:

startDate=09/11/2024    # November 9, 2024
endDate=30/11/2024      # November 30, 2024

Timestamps in responses use ISO 8601 UTC:

"timestamp": "2024-11-09T10:30:00Z"

---

Status Codes

Code	Name	Description
200	OK	Request succeeded
400	Bad Request	Missing/invalid parameters
401	Unauthorized	Missing or expired token
403	Forbidden	Insufficient permissions
420	Invalid Token	JWT expired or user in blocklist
429	Too Many Requests	Rate limit exceeded
440	Session Expired	Token revoked in token_logs
500	Server Error	Unhandled exception
1401	Data Not Found	No data for query
1403	Missing Parameter	Required header or param absent
1430	Validation Error	JSON schema validation failure

---

Rate Limiting

AquaGen API uses flask-limiter to enforce per-endpoint rate limits. Exceeding the limit returns HTTP 429 with:

{
  "message": "Too many requests. Please try again later.",
  "status": "failed"
}

note

Default limits: 200 requests/day, 50 requests/hour per IP. Login and OTP endpoints have stricter per-operation limits — see User API Reference.

---

Input Validation

Query parameters — parsed via Flask-RESTX argument parsers:

requestParser = namespace.parser()
requestParser.add_argument('date1', required=True, type=str, help='DD/MM/YYYY')
requestParser.add_argument('type', choices=['DAY', 'MONTH', 'YEAR'], default='DAY')
requestParser.add_argument('divisionFactor', type=int, default=1000)

Request bodies — validated against JSON schemas in app/validators/schemas/ using jsonschema.validate. Schema validation failures return 1430.

warning

SQL injection — all string parameters pass through @validate_values() from app/security_checks/input_validator.py. A match returns 405. Never bypass this decorator on new endpoints that accept string input.