backend API documentation for all current endpoints and adds small supporting fixes

README.md

@@ -59,15 +59,22 @@ uvicorn backend.app.main:app --reload
 The service listens on `http://127.0.0.1:8000` by default. OpenAPI
 documentation is available at `http://127.0.0.1:8000/docs`.
 
+Detailed endpoint documentation with request/response examples, authentication
+flow, and testing steps is available at
+`docs/backend_api_reference.md`.
+
 ### Core Endpoints
 
 | Entity | Base Path | Notes |
 | --- | --- | --- |
+| Authentication | `/api/v1/auth` | User registration + token issuance |
+| Health | `/health`, `/api/v1/analytics/health` | Public readiness checks |
 | Projects | `/api/v1/projects` | CRUD with pagination & search |
 | ICT Resources | `/api/v1/resources` | Validates project/location references and enforces ticket rules |
 | Locations | `/api/v1/locations` | CRUD with geo metadata |
 | Maintenance Tickets | `/api/v1/maintenance-tickets` | Requires resolution metadata when closing a ticket |
 | Sensor Sites | `/api/v1/sensor-sites` | Links IoT deployments to resources, projects, and locations |
+| Alerts | `/api/v1/alerts` | Sensor-threshold alert creation and lookup |
 
 Each list endpoint accepts `limit`, `offset`, and `search` query parameters and
 returns pagination metadata to keep API consumers informed.

backend/app/api/alert_router.py

@@ -26,7 +26,7 @@ def get_alert_service(session: AsyncSession = Depends(get_session)) -> AlertServ
     return AlertService(alert_repository)
 
 
-@router.post("", response_model=AlertRead)
+@router.post("", response_model=AlertRead | None)
 async def create_alert(
     sensor_id: int,
     metric: str,

backend/app/api/deps.py

@@ -75,7 +75,7 @@ async def get_current_user(
         headers={"WWW-Authenticate": "Bearer"},
     )
     try:
-        payload = jwt.decode(token, SECRET_key, algorithms=[ALGORITHM])
+        payload = jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])
         username: str = payload.get("sub")
         if username is None:
             raise credentials_exception

backend/app/schemas/alert.py

@@ -12,4 +12,4 @@ class AlertRead(BaseSchema):
     metric: str
     value: float
     threshold: float
-    created_at: datetime
+    timestamp: datetime