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