Backend API Reference

Backend API Reference

All routes are mounted under the base path /csfaq/api/.

---

Authentication (/auth)

Method	Path	Auth	Description
POST	/auth/register	No	Register a new user
POST	/auth/login	No	Login and receive JWT tokens
POST	/auth/refresh	Token	Refresh access token
POST	/auth/logout	Token	Invalidate refresh token
GET	/auth/me	Token	Get current user profile
PATCH	/auth/me	Token	Update current user profile
POST	/auth/change-password	Token	Change password
DELETE	/auth/me	Token	Delete (anonymize) account

FAQ (/faq)

Method	Path	Auth	Description
GET	/faq	Token	List FAQs (paginated, filterable)
GET	/faq/:id	Token	Get a single FAQ
POST	/faq	Admin	Create a new FAQ
PATCH	/faq/:id	Admin	Update a FAQ
DELETE	/faq/:id	Admin	Delete a FAQ
POST	/faq/:id/freshness-review	Admin	Submit a freshness review

Public FAQ (/public)

Method	Path	Auth	Description
GET	/public/faqs	No	List published FAQs (public page)
GET	/public/faqs/:id	No	Get a single published FAQ
GET	/public/faqs/popular	No	Get popular FAQs

Search (/search)

Method	Path	Auth	Description
POST	/search	No	Hybrid search (vector + keyword)
GET	/search/suggest	No	Autocomplete suggestions
GET	/search/trending	No	Trending search queries

Ask AI (/ask-ai)

Method	Path	Auth	Description
POST	/ask-ai	Optional	Ask a question and get an AI-generated answer

Community (/community)

Method	Path	Auth	Description
GET	/community/posts	Token	List community posts (paginated)
GET	/community/posts/:id	Token	Get a single post with comments
POST	/community/posts	Token	Create a new post
PATCH	/community/posts/:id	Token	Update a post
DELETE	/community/posts/:id	Token/Admin	Delete a post
POST	/community/posts/:id/vote	Token	Upvote or downvote a post
POST	/community/posts/:id/bookmark	Token	Bookmark a post
POST	/community/posts/:id/comments	Token	Add a comment
PATCH	/community/comments/:id	Token	Edit a comment
DELETE	/community/comments/:id	Token/Admin	Delete a comment
POST	/community/comments/:id/vote	Token	Vote on a comment
POST	/community/posts/:id/accept-answer	Token	Accept an answer

Support (/support)

Method	Path	Auth	Description
GET	/support/requests	Token	List support tickets
GET	/support/requests/:id	Token	Get a single ticket
POST	/support/requests	Token	Create a support ticket
POST	/support/requests/:id/follow-up	Token	Add a follow-up message
PATCH	/support/requests/:id/status	Admin	Update ticket status
POST	/support/golden-ticket	Token	Submit a golden ticket

Notifications (/notifications)

Method	Path	Auth	Description
GET	/notifications	Token	List notifications
PATCH	/notifications/:id/read	Token	Mark notification as read
POST	/notifications/read-all	Token	Mark all as read
GET	/notifications/tea/stream	Token	Server-Sent Events (SSE) stream

Upload (/upload)

Method	Path	Auth	Description
POST	/upload/signed-url	Token	Get a signed upload URL (GCS)
POST	/upload/avatar	Token	Upload avatar image

Zoom (/zoom)

Method	Path	Auth	Description
GET	/zoom/authorize	Admin	Start Zoom OAuth flow
GET	/zoom/callback	--	OAuth callback (redirects to frontend)
POST	/zoom/webhook	--	Zoom webhook receiver
GET	/zoom/meetings	Admin	List processed meetings
GET	/zoom/sessions	Admin	List Zoom sessions
POST	/zoom/process/:meetingId	Admin	Manually process a meeting

Knowledge (/knowledge)

Method	Path	Auth	Description
GET	/knowledge/insights	Token	List knowledge insights
POST	/knowledge/insights/:id/promote	Admin	Promote insight to FAQ

Documents (/documents)

Method	Path	Auth	Description
POST	/documents/upload	Admin	Upload a document for processing
GET	/documents	Token	List documents
GET	/admin/documents	Admin	Admin document management

Moderation (/moderation)

Method	Path	Auth	Description
POST	/moderation/report	Token	Report content
GET	/moderation/reports	Admin	List reports
POST	/moderation/ban	Admin	Ban a user

Reputation (/reputation)

Method	Path	Auth	Description
GET	/reputation/leaderboard	Token	Get reputation leaderboard
GET	/reputation/me	Token	Get own reputation stats

Programs (/programs, /batches, /courses)

Method	Path	Auth	Description
GET	/programs	Token	List programs
GET	/batches	Token	List batches
GET	/courses	Token	List courses
POST	/admin/programs	Admin	Create a program
PATCH	/admin/programs/:id	Admin	Update a program
GET	/feature-flags	Token	Get feature flags for current batch

Admin (/admin)

Method	Path	Auth	Description
GET	/admin/users	Admin	List all users
PATCH	/admin/users/:id	Admin	Update user role
GET	/admin/stats	Admin	Dashboard statistics
GET	/admin/audit-log	Admin	Audit log
GET	/admin/config	Admin	Get admin config
PATCH	/admin/config	Admin	Update admin config

Health and Utility

Method	Path	Auth	Description
GET	/health	No	Health check
GET	(root) /csfaq/api/health	No	Health check (alternate)
POST	(root) /csfaq/api/warm	No	Warm the embedding model
GET	(root) /csfaq/api/metrics	No	Prometheus-style metrics

---

Authentication

All authenticated endpoints expect a Bearer token in the Authorization header:

Authorization: Bearer <access_token>

Admin endpoints additionally require the user to have role: "admin" in the database.

Response Format

Success responses:

{
  "data": { ... },
  "pagination": { "page": 1, "limit": 20, "total": 100 }
}

Error responses:

{
  "message": "Error description"
}

Rate Limiting

Endpoint Group	Window	Max Requests
Global	15 min	100
Auth (login)	15 min	5
Auth (register)	1 hour	3
Search	1 min	30
Ask AI (anonymous)	24 hours	5
Ask AI (authenticated)	24 hours	50
Upload	1 hour	20