Apis DOCS/Endpoints.md

# Ain El Aql - Endpoints Reference

This document catalogs all the REST API endpoints available in the backend. Use this as a reference guide when integrating or building frontend clients (Websites, Flutter Apps, dashboards, etc.).

---

## 🏠 Public & Utility
| Method | Endpoint | Description |
|---|---|---|
| `GET` | `/` | Base API sanity check |
| `GET` | `/health` | Application health status |
| `GET` | `/supabase/health` | Supabase connectivity health check |

---

## 🔐 Authentication (`/auth`)
*Most of these rely on Supabase Auth. They handle user sessions, passwords, and OTP logic.*

| Method | Endpoint | Description |
|---|---|---|
| `POST` | `/auth/register` | Register a new user |
| `POST` | `/auth/login` | Login to receive a JWT session token |
| `POST` | `/auth/forgot-password` | Request a password reset link |
| `POST` | `/auth/reset-password/resolve-token` | Validate the token from the reset email |
| `POST` | `/auth/reset-password` | Update password |
| `GET` | `/auth/reset-password-page` | Web UI for resetting password |
| `GET` | `/auth/reset-password-bridge` | Mobile deep-link bridge for password reset |
| `POST` | `/auth/otp/request` | Request an OTP code via Email/Phone |
| `POST` | `/auth/otp/verify` | Verify the requested OTP code |

---

## 👤 Profile & Vehicles
*Requires `Authorization: Bearer <token>`.*

| Method | Endpoint | Description |
|---|---|---|
| `PUT` | `/profile/update` | Update authenticated user's profile info |
| `POST` | `/vehicles/add` | Add a new vehicle to user's profile |
| `GET` | `/vehicles/my` | List authenticated user's vehicles |
| `PUT` | `/vehicles/{vehicle_id}` | Edit an existing vehicle |
| `DELETE` | `/vehicles/{vehicle_id}` | Delete/Unlink a vehicle |
| `POST` | `/vehicles/verify` | Request admin verification for a vehicle |

---

## 🔔 Notifications
*Requires `Authorization: Bearer <token>`.*

| Method | Endpoint | Description |
|---|---|---|
| `POST` | `/notifications/fcm-token` | Register an FCM (Firebase) token for push notifications |
| `GET` | `/notifications/my` | Get user's personal notification feed |

---

## 🤖 AI Models & Inference Core
*The core AI pipeline execution paths.*

| Method | Endpoint | Description |
|---|---|---|
| `GET` | `/models` | List available AI models |
| `GET` | `/developer/models` | Diagnostic data for loaded models |
| `POST` | `/predict` | **Main Pipeline:** Upload image, run OCR, update parking session, return gate decision. |
| `POST` | `/model/infer` | Remote model execution endpoint (Hugging Face integration) |
| `POST` | `/developer/predict` | Developer debugging for predictions |

---

## 🅿️ Parking, Events, and History
*Requires `Authorization: Bearer <token>`.*
**Role-aware endpoints:** Regular users only see data for their own vehicles. `admin` and `security` roles see all data globally across the entire garage.

| Method | Endpoint | Description |
|---|---|---|
| `GET` | `/parking/locations` | Get garage capacities, pricing rules, and occupancy snapshot |
| `GET` | `/parking/occupancy` | Get pure occupancy statistics |
| `GET` | `/events/entered-cars` | Feed of cars that entered the garage |
| `GET` | `/events/leaving-cars-within-5-minutes` | Feed of cars currently in their exit grace period |
| `GET` | `/events/left-cars` | Feed of cars that have exited the garage completely |
| `GET` | `/events/inside-cars` | Live feed of cars currently physically inside the garage |
| `GET` | `/parking/history` | Historical log of all parking sessions |

---

## 💳 Payments & Gate Control

| Method | Endpoint | Description |
|---|---|---|
| `POST` | `/payments/paymob/create` | Initialize a Paymob iframe checkout URL |
| `POST` | `/payments/paymob/webhook` | Webhook listener for Paymob status updates |
| `POST` | `/gate/decision` | Evaluate if the physical gate should open based on payment status |

---

## 🛡️ Administrative & Security (Strict RBAC)
*Requires `Authorization: Bearer <token>` with either `admin` or `security` role.*

| Method | Endpoint | Description |
|---|---|---|
| `GET` | `/events/new-cars` | Real-time polling feed of cars pulling up to cameras (Security Dashboard) |
| `POST` | `/payments/manual/cash-confirm` | Security action to bypass payment and manually mark session as paid via cash |
| `POST` | `/admin/maintenance/weekly-refresh` | Internal backend maintenance and cleanup task |