starr-philproperties/apps/api/ROUTES.md

# API Routes Reference
**Project:** star-auth-system (new_starr backend)
**Base URL:** `/api`
**Last updated:** 2026-06-20

---

## Legend

| Symbol | Meaning |
|--------|---------|
| 🔓 | Public — no authentication required |
| 🔑 | Requires valid JWT (`authenticate`) |
| 👤 | Requires role: `user / staff / admin` (`requireClient`) |
| 🧑‍💼 | Requires role: `staff / admin` (`requireStaff`) |
| 👑 | Requires role: `admin` only (`requireAdmin`) |
| 🌐 | `originGuard` exempt — accessible from any client (monitoring tools, browser media elements) |
| ⚡ | Rate-limited separately (`sensitiveOpsLimiter`) |

> All routes except Health and `GET /api/auth/google*` are protected by `originGuard`
> (requires `Sec-Fetch-Site` header; mutations also require `Origin` in allowlist).

---

## 🏥 Health
> 🌐 No auth · No originGuard — designed for monitoring tools, load balancers, Kubernetes probes

```
GET  /api/health        Dashboard — app info, system info, all service connections (human-readable)
GET  /api/health/ready  Readiness — compact 200/503 for machines (Kubernetes, deploy scripts)
```

---

## 🔐 Auth
> 🔓 Public — no authentication required unless noted

```
GET  /api/auth/csrf-token                  CSRF token for cookie-based clients
POST /api/auth/register                    Create account (sends OTP email)
POST /api/auth/verify-otp                  Verify OTP → auto-login
POST /api/auth/resend-otp                  Resend OTP email
POST /api/auth/login                       Login with email + password
POST /api/auth/refresh                     Exchange refresh token for new access token
POST /api/auth/logout              🔑      Invalidate current session
POST /api/auth/change-password     🔑 ⚡   Change password

GET  /api/auth/google                      Initiate Google OAuth
GET  /api/auth/google/callback             Google OAuth callback
GET  /api/auth/google/failed               OAuth failure fallback
```

---

## 👤 Client
> 🔑 👤 `authenticate → requireClient` applied to all routes below unless noted

### Profile & Sessions
```
GET    /api/client/profile                 Own profile
PUT    /api/client/profile                 Update own profile
POST   /api/client/profile/avatar          Upload avatar
DELETE /api/client/profile/avatar          Delete avatar
GET    /api/client/sessions                Own active sessions
DELETE /api/client/sessions/:id            Revoke a session
GET    /api/client/achievements            Own achievements
```

### Media
```
GET  /api/client/media/stream/:token  🌐🔓  Stream S3 asset (JWT auth via URL param, no headers)
POST /api/client/media/token          🔑    Issue a short-lived media token for an S3 asset
```

### Notifications
```
GET   /api/client/notifications/unseen  🔓*  Unseen count (* softAuthenticate — returns 0 if unauthenticated)
GET   /api/client/notifications              Paginated notification list
PATCH /api/client/notifications/seen-all     Mark all notifications seen
PATCH /api/client/notifications/:id/seen     Mark one notification seen
```

### Tiers & Payments
```
GET  /api/client/tiers/me                  My active tier
GET  /api/client/tiers/me/history          My tier history
GET  /api/client/tiers/me/payments         My payment history
GET  /api/client/tiers/plans               All available plans
POST /api/client/tiers/checkout/order   ⚡  Create PayPal order (tier upgrade)
POST /api/client/tiers/checkout/capture ⚡  Capture PayPal payment
POST /api/client/tiers/checkout/cancel  ⚡  Cancel PayPal order
POST /api/client/tiers/checkout/refund  ⚡  Request refund
```

### Courses
```
GET  /api/client/courses                                              Paginated course list
GET  /api/client/courses/uuid/:uuid                                   Course by UUID
GET  /api/client/courses/unit/uuid/:uuid                              Unit by UUID
GET  /api/client/courses/unit/uuid/:uuid/lessons                      Lessons by unit UUID
GET  /api/client/courses/lesson/uuid/:uuid                            Lesson by UUID
GET  /api/client/courses/:courseId                                    Single course
GET  /api/client/courses/:courseId/units/:unitId                      Single unit
GET  /api/client/courses/:courseId/units/:unitId/lessons/:lessonId    Single lesson
GET  /api/client/courses/:courseId/units/:unitId/quiz                 Unit quiz (no answers)
GET  /api/client/courses/:courseId/assessment                         Course assessment (no answers)
POST /api/client/courses/:courseId/units/:unitId/quiz/:quizId/submit       Submit unit quiz
POST /api/client/courses/:courseId/assessment/:assessmentId/submit         Submit course assessment
```

### Course Purchases
```
GET  /api/client/course-purchases           My course purchases
POST /api/client/course-purchases/order  ⚡  Create PayPal order (course purchase)
POST /api/client/course-purchases/capture ⚡  Capture payment
POST /api/client/course-purchases/cancel  ⚡  Cancel order
```

### Groups & Tasks
```
GET  /api/client/groups                                                                       My groups
GET  /api/client/groups/:groupId                                                              Single group
GET  /api/client/groups/:groupId/task-lists                                                   Task lists (?status=ongoing|done|overdue)
GET  /api/client/groups/:groupId/task-lists/:taskListId                                       Single task list
GET  /api/client/groups/:groupId/task-lists/:taskListId/tasks/:taskId                         Task + requirements + latest completion
GET  /api/client/groups/:groupId/task-lists/:taskListId/tasks/:taskId/progress                Full progress snapshot
GET  /api/client/groups/:groupId/task-lists/:taskListId/tasks/:taskId/completions/latest      Latest completion
GET  /api/client/groups/:groupId/task-lists/:taskListId/tasks/:taskId/completions             Full completion history
POST /api/client/groups/:groupId/task-lists/:taskListId/tasks/:taskId/completions         ⚡  Submit task completion
GET  /api/client/groups/:groupId/task-lists/:taskListId/tasks/:taskId/completions/:completionId/files/:fileId/stream    Stream a completion file
GET  /api/client/groups/:groupId/task-lists/:taskListId/tasks/:taskId/completions/:completionId/files/:fileId/download  Download a completion file
POST /api/client/groups/:groupId/task-lists/:taskListId/tasks/:taskId/upload              ⚡  Upload file to S3 (returns file metadata)
POST /api/client/groups/:groupId/task-lists/:taskListId/tasks/:taskId/requirements/:requirementId/visit     ⚡  UPSERT link visit
POST /api/client/groups/:groupId/task-lists/:taskListId/tasks/:taskId/requirements/:requirementId/progress  ⚡  UPSERT lesson progress
```

### Advertisements
```
GET  /api/client/advertisements/active                  Active advertisement (?type=hero)
POST /api/client/advertisements/:advertisementId/click  Track ad click
```

### Certificates
```
GET /api/client/certificates/:courseUuid   Download course completion certificate
```

---

## 🧑‍💼 Staff
> 🔑 🧑‍💼 `authenticate → requireStaff`

```
GET /api/staff/users                    Paginated user list (non-admins only)
GET /api/staff/users/:id                Single non-admin user
PUT /api/staff/users/:id/status         Activate or deactivate a user
GET /api/staff/users/:id/sessions       User's active sessions
```

---

## 👑 Admin
> 🔑 👑 `authenticate → requireAdmin → adminLimiter` applied to all routes below

### Dashboard
```
GET /api/admin/dashboard/users    User stats overview
GET /api/admin/dashboard/groups   Group stats overview
```

### Profile
```
GET    /api/admin/profile         Own admin profile
PUT    /api/admin/profile         Update own profile
POST   /api/admin/profile/avatar  Upload avatar
DELETE /api/admin/profile/avatar  Delete avatar
```

### Users
```
GET    /api/admin/users                        Paginated user list
GET    /api/admin/users/field-values           Filter field values (for dropdowns)
GET    /api/admin/users/archived               Archived/deactivated users
POST   /api/admin/users/staff            ⚡    Create a staff account
POST   /api/admin/users/bulk/restore     ⚡    Bulk restore users
DELETE /api/admin/users/bulk             ⚡    Bulk deactivate users
GET    /api/admin/users/:id                    Single user
PUT    /api/admin/users/:id              ⚡    Update user
DELETE /api/admin/users/:id              ⚡    Deactivate user
POST   /api/admin/users/:id/restore      ⚡    Restore user
GET    /api/admin/users/:id/sessions           User's active sessions
DELETE /api/admin/users/:id/sessions/:sid ⚡   Terminate a user session
GET    /api/admin/users/:id/achievements       User's achievements
```

### Groups
```
GET    /api/admin/groups                       Paginated group list
GET    /api/admin/groups/field-values          Filter field values
GET    /api/admin/groups/archived              Archived groups
POST   /api/admin/groups/bulk/restore    ⚡    Bulk restore groups
DELETE /api/admin/groups/bulk            ⚡    Bulk deactivate groups
POST   /api/admin/groups                 ⚡    Create group
GET    /api/admin/groups/:gid                  Single group
PUT    /api/admin/groups/:gid            ⚡    Update group
PATCH  /api/admin/groups/:gid/deactivate ⚡    Deactivate group
PATCH  /api/admin/groups/:gid/restore    ⚡    Restore group
GET    /api/admin/groups/:gid/users            Users in group
GET    /api/admin/groups/:gid/users/add        Users not yet in group (for add dialog)
POST   /api/admin/groups/:gid/users      ⚡    Add user to group
DELETE /api/admin/groups/:gid/users      ⚡    Remove user from group
```

### Assets
```
GET   /api/admin/assets                   Paginated asset list
GET   /api/admin/assets/archived          Archived assets
GET   /api/admin/assets/field-values      Filter field values
POST  /api/admin/assets                   Upload asset (file + optional thumbnail)
DELETE /api/admin/assets/bulk        ⚡   Bulk archive assets
PATCH  /api/admin/assets/bulk-restore     Bulk restore assets
GET    /api/admin/assets/:assetId         Single asset
PATCH  /api/admin/assets/:assetId    ⚡   Update asset
PATCH  /api/admin/assets/:assetId/restore ⚡  Restore asset
DELETE /api/admin/assets/:assetId    ⚡   Archive asset
```

### Courses
```
GET   /api/admin/courses                    Paginated course list
POST  /api/admin/courses                    Create course
GET   /api/admin/courses/field-values       Filter field values
GET   /api/admin/courses/flat               All courses (flat list, no pagination)
GET   /api/admin/courses/units-flat         All units (flat list)
GET   /api/admin/courses/lessons-flat       All lessons (flat list)
GET   /api/admin/courses/archives           Archived courses
DELETE /api/admin/courses/bulk              Bulk archive courses
PATCH  /api/admin/courses/restore/bulk      Bulk restore courses
GET    /api/admin/courses/archives/:courseId          Archived course detail
GET    /api/admin/courses/:courseId                   Single course
PUT    /api/admin/courses/:courseId                   Update course
DELETE /api/admin/courses/:courseId                   Archive course
PATCH  /api/admin/courses/:courseId/restore           Restore course
GET    /api/admin/courses/:courseId/instructors       Course instructors
PUT    /api/admin/courses/:courseId/instructors       Sync instructors (replace)
GET    /api/admin/courses/:courseId/prerequisites     Course prerequisites
PUT    /api/admin/courses/:courseId/prerequisites     Sync prerequisites (replace)
GET    /api/admin/courses/:courseId/field-values      Unit filter field values
```

#### Course Assessment
```
GET    /api/admin/courses/:courseId/assessment                                           Assessment
POST   /api/admin/courses/:courseId/assessment                                           Create assessment
GET    /api/admin/courses/:courseId/assessment/archives                                  Archived assessment
PATCH  /api/admin/courses/:courseId/assessment/:assessmentId                             Update assessment
DELETE /api/admin/courses/:courseId/assessment/:assessmentId                             Delete assessment
PATCH  /api/admin/courses/:courseId/assessment/:assessmentId/restore                     Restore assessment
GET    /api/admin/courses/:courseId/assessment/:assessmentId/questions                   Questions
POST   /api/admin/courses/:courseId/assessment/:assessmentId/questions                   Create question
DELETE /api/admin/courses/:courseId/assessment/:assessmentId/questions/bulk              Bulk archive questions
PATCH  /api/admin/courses/:courseId/assessment/:assessmentId/questions/restore/bulk      Bulk restore questions
GET    /api/admin/courses/:courseId/assessment/:assessmentId/questions/archives/:questionId  Archived question
PATCH  /api/admin/courses/:courseId/assessment/:assessmentId/questions/:questionId           Update question
DELETE /api/admin/courses/:courseId/assessment/:assessmentId/questions/:questionId           Delete question
PATCH  /api/admin/courses/:courseId/assessment/:assessmentId/questions/:questionId/restore   Restore question
```

#### Units
```
GET    /api/admin/courses/:courseId/units                                 Unit list
POST   /api/admin/courses/:courseId/units                                 Create unit
GET    /api/admin/courses/:courseId/units/archives                        Archived units
DELETE /api/admin/courses/:courseId/units/bulk                            Bulk archive units
PATCH  /api/admin/courses/:courseId/units/restore/bulk                    Bulk restore units
GET    /api/admin/courses/:courseId/units/archives/:unitId                Archived unit detail
GET    /api/admin/courses/:courseId/units/:unitId                         Single unit
PUT    /api/admin/courses/:courseId/units/:unitId                         Update unit
DELETE /api/admin/courses/:courseId/units/:unitId                         Archive unit
PATCH  /api/admin/courses/:courseId/units/:unitId/restore                 Restore unit
GET    /api/admin/courses/:courseId/units/:unitId/field-values            Lesson filter field values
```

#### Unit Quiz
```
GET    /api/admin/courses/:courseId/units/:unitId/quiz                                    Quiz
POST   /api/admin/courses/:courseId/units/:unitId/quiz                                    Create quiz
GET    /api/admin/courses/:courseId/units/:unitId/quiz/archives                           Archived quiz
PATCH  /api/admin/courses/:courseId/units/:unitId/quiz/:quizId                            Update quiz
DELETE /api/admin/courses/:courseId/units/:unitId/quiz/:quizId                            Delete quiz
PATCH  /api/admin/courses/:courseId/units/:unitId/quiz/:quizId/restore                    Restore quiz
GET    /api/admin/courses/:courseId/units/:unitId/quiz/:quizId/questions                  Questions
POST   /api/admin/courses/:courseId/units/:unitId/quiz/:quizId/questions                  Create question
DELETE /api/admin/courses/:courseId/units/:unitId/quiz/:quizId/questions/bulk             Bulk archive questions
PATCH  /api/admin/courses/:courseId/units/:unitId/quiz/:quizId/questions/restore/bulk     Bulk restore questions
GET    /api/admin/courses/:courseId/units/:unitId/quiz/:quizId/questions/archives/:questionId  Archived question
PATCH  /api/admin/courses/:courseId/units/:unitId/quiz/:quizId/questions/:questionId           Update question
DELETE /api/admin/courses/:courseId/units/:unitId/quiz/:quizId/questions/:questionId           Delete question
PATCH  /api/admin/courses/:courseId/units/:unitId/quiz/:quizId/questions/:questionId/restore   Restore question
```

#### Lessons
```
GET    /api/admin/courses/:courseId/units/:unitId/lessons                              Lesson list
POST   /api/admin/courses/:courseId/units/:unitId/lessons                              Create lesson
GET    /api/admin/courses/:courseId/units/:unitId/lessons/archives                     Archived lessons
DELETE /api/admin/courses/:courseId/units/:unitId/lessons/bulk                         Bulk archive lessons
PATCH  /api/admin/courses/:courseId/units/:unitId/lessons/restore/bulk                 Bulk restore lessons
GET    /api/admin/courses/:courseId/units/:unitId/lessons/archives/:lessonId           Archived lesson detail
GET    /api/admin/courses/:courseId/units/:unitId/lessons/:lessonId                    Single lesson
PUT    /api/admin/courses/:courseId/units/:unitId/lessons/:lessonId                    Update lesson
DELETE /api/admin/courses/:courseId/units/:unitId/lessons/:lessonId                    Archive lesson
PATCH  /api/admin/courses/:courseId/units/:unitId/lessons/:lessonId/restore            Restore lesson
GET    /api/admin/courses/:courseId/units/:unitId/lessons/:lessonId/page               Lesson page content
PUT    /api/admin/courses/:courseId/units/:unitId/lessons/:lessonId/page               Upsert lesson page content
```

### Task Lists
```
GET  /api/admin/task-lists                         Paginated task list collection
GET  /api/admin/task-lists/archived                Archived task lists
GET  /api/admin/task-lists/field-values            Filter field values
POST /api/admin/task-lists                    ⚡   Create task list
POST /api/admin/task-lists/bulk-archive       ⚡   Bulk archive task lists
POST /api/admin/task-lists/bulk-restore       ⚡   Bulk restore task lists
GET  /api/admin/task-lists/:taskListId             Single task list
PATCH  /api/admin/task-lists/:taskListId      ⚡   Update task list
DELETE /api/admin/task-lists/:taskListId      ⚡   Archive task list
PATCH  /api/admin/task-lists/:taskListId/restore ⚡  Restore task list
```

#### Task List → Groups
```
GET  /api/admin/task-lists/:taskListId/groups                Groups assigned to this task list
POST /api/admin/task-lists/:taskListId/groups/assign    ⚡   Assign groups
POST /api/admin/task-lists/:taskListId/groups/unassign  ⚡   Unassign groups
```

#### Task List → Tasks
```
GET  /api/admin/task-lists/:taskListId/tasks                       Task list's tasks
GET  /api/admin/task-lists/:taskListId/tasks/archived              Archived tasks
GET  /api/admin/task-lists/:taskListId/tasks/field-values          Filter field values
POST /api/admin/task-lists/:taskListId/tasks                  ⚡   Create task
POST /api/admin/task-lists/:taskListId/tasks/bulk-archive     ⚡   Bulk archive tasks
POST /api/admin/task-lists/:taskListId/tasks/bulk-restore     ⚡   Bulk restore tasks
GET    /api/admin/task-lists/:taskListId/tasks/:taskId             Single task
PATCH  /api/admin/task-lists/:taskListId/tasks/:taskId        ⚡   Update task
DELETE /api/admin/task-lists/:taskListId/tasks/:taskId        ⚡   Archive task
PATCH  /api/admin/task-lists/:taskListId/tasks/:taskId/restore ⚡  Restore task
```

#### Task List → Tasks → Completions
```
GET    /api/admin/task-lists/:taskListId/tasks/:taskId/completions                         All completions
GET    /api/admin/task-lists/:taskListId/tasks/:taskId/completions/user/:userId            Completions by user
POST   /api/admin/task-lists/:taskListId/tasks/:taskId/completions/bulk-archive       ⚡   Bulk archive
POST   /api/admin/task-lists/:taskListId/tasks/:taskId/completions/bulk-restore       ⚡   Bulk restore
GET    /api/admin/task-lists/:taskListId/tasks/:taskId/completions/:completionId           Single completion
DELETE /api/admin/task-lists/:taskListId/tasks/:taskId/completions/:completionId      ⚡   Archive completion
PATCH  /api/admin/task-lists/:taskListId/tasks/:taskId/completions/:completionId/restore ⚡ Restore completion
```

### Tiers
```
GET    /api/admin/tiers                         Paginated tier/plan list
POST   /api/admin/tiers                         Create plan
GET    /api/admin/tiers/field-values            Filter field values
POST   /api/admin/tiers/bulk/archive            Bulk archive plans
POST   /api/admin/tiers/bulk/restore            Bulk restore plans
GET    /api/admin/tiers/payments                All payments (paginated)
GET    /api/admin/tiers/payments/field-values   Payment filter field values
GET    /api/admin/tiers/payments/:id            Single payment record
GET    /api/admin/tiers/users/:id/tiers         Tiers assigned to a user
POST   /api/admin/tiers/users/tiers/grant  ⚡   Manually grant a tier to a user
PATCH  /api/admin/tiers/users/tiers/:tid/revoke ⚡  Revoke a user's tier
GET    /api/admin/tiers/:id                     Single plan
PUT    /api/admin/tiers/:id                     Update plan
DELETE /api/admin/tiers/:id                     Archive plan
POST   /api/admin/tiers/:id/restore             Restore plan
GET    /api/admin/tiers/:id/courses             Courses in this plan
POST   /api/admin/tiers/:id/courses             Sync courses in plan (replace)
```

### Categories
```
GET    /api/admin/categories          All categories
POST   /api/admin/categories          Create category
GET    /api/admin/categories/:id      Single category
PUT    /api/admin/categories/:id      Update category
DELETE /api/admin/categories/:id      Archive category
POST   /api/admin/categories/:id/restore  Restore category
```

### Products
```
GET    /api/admin/products/courses/:courseId/product       Course product pricing
PUT    /api/admin/products/courses/:courseId/product       Upsert course product
DELETE /api/admin/products/courses/:courseId/product       Remove course product
GET    /api/admin/products/courses/:courseId/categories    Course categories
POST   /api/admin/products/courses/:courseId/categories    Sync course categories (replace)
```

### Advertisements
```
GET    /api/admin/advertisements                        Paginated list
GET    /api/admin/advertisements/archived               Archived advertisements
GET    /api/admin/advertisements/field-values           Filter field values
POST   /api/admin/advertisements                        Create advertisement
DELETE /api/admin/advertisements/bulk              ⚡   Bulk archive
PATCH  /api/admin/advertisements/bulk-restore           Bulk restore
GET    /api/admin/advertisements/:advertisementId        Single advertisement
PATCH  /api/admin/advertisements/:advertisementId   ⚡   Update advertisement
PATCH  /api/admin/advertisements/:advertisementId/restore ⚡  Restore advertisement
DELETE /api/admin/advertisements/:advertisementId   ⚡   Archive advertisement
```

### Notifications
```
GET   /api/admin/notifications              Paginated notification list
GET   /api/admin/notifications/unseen       Unseen count
PATCH /api/admin/notifications/seen-all     Mark all seen
PATCH /api/admin/notifications/:id/seen     Mark one seen
```

---

## Route Count Summary

| Scope   | Routes |
|---------|--------|
| Health  | 2      |
| Auth    | 11     |
| Client  | 43     |
| Staff   | 4      |
| Admin   | 113    |
| **Total** | **173** |