DoCurious

Appearance

API Endpoints ​

Complete reference for all backend API endpoints. The source of truth is server/src/routes/healthDashboard.routes.ts, which maintains a machine-readable inventory with implementation status.

STATUS: BUILT

130+ endpoints across 20 modules. The live health dashboard at /api/portal/health/dashboard shows real-time implementation status.

Base URL ​

All endpoints are prefixed with /api/portal. In development:

http://localhost:8000/api/portal

Authentication ​

Most endpoints require a JWT access token in the Authorization header:

Authorization: Bearer <accessToken>

Token lifecycle:

  • Access token expires in 15 minutes (configurable via JWT_ACCESS_EXPIRY)
  • Refresh token expires in 7 days (configurable via JWT_REFRESH_EXPIRY)
  • Use POST /auth/refresh with the refresh token to get a new token pair

Status Legend ​

StatusMeaning
LiveFully implemented with Prisma database queries
PartialFunctional but with noted limitations
StubReturns mock data or 501 (not yet implemented)

Auth (13 endpoints) ​

MethodPathAuthStatusDescription
POST/auth/register--LiveRegister a new user
POST/auth/login--LiveLogin with email + password
POST/auth/refresh--LiveRefresh access token
POST/auth/logout--LiveRevoke refresh token
POST/auth/google--StubGoogle OAuth (returns 501)
POST/auth/apple--StubApple Sign-In (returns 501)
POST/auth/forgot-password--PartialReset request (no email sending)
POST/auth/reset-password--LiveReset password with token
POST/auth/change-passwordAuthLiveChange password
POST/auth/verify-otp--StubVerify OTP (always succeeds)
POST/auth/resend-otp--StubResend OTP (always succeeds)
POST/auth/send-verificationAuthPartialRequest email verify (no email)
POST/auth/verify-email--LiveVerify email with token

Users (11 endpoints) ​

MethodPathAuthStatusDescription
GET/users/meAuthLiveGet current user profile
PUT/users/meAuthLiveUpdate profile
PUT/users/me/settingsAuthLiveUpdate notification settings
PUT/users/me/passwordAuthLiveChange password
DELETE/users/meAuthLiveRequest account deletion
GET/users/me/deletion-statusAuthLiveCheck deletion status
POST/users/me/cancel-deletionAuthLiveCancel deletion request
POST/users/me/data-exportAuthLiveRequest data export (GDPR)
GET/users/me/export-statusAuthLiveCheck export status
GET/users/me/export-historyAuthLiveGet past export requests
GET/users/:idAuthLiveGet user by ID

Challenges (9 endpoints) ​

MethodPathAuthStatusDescription
GET/v2/challengesOptionalLiveList challenges (paginated)
GET/v2/challenges/categories--LiveGet challenge categories
GET/v2/challenges/:idOptionalLiveGet challenge by ID
GET/v2/challenges/:id/discussion--LiveGet discussion posts
POST/v2/challengesAuthLiveCreate a challenge
PUT/v2/challenges/:idAuthLiveUpdate a challenge
POST/v2/challenges/:id/startAuthLiveStart a challenge
POST/v2/challenges/:id/submit-for-reviewAuthLiveSubmit for verification
POST/v2/challenges/:id/discussionAuthLiveCreate discussion post

User Challenges (4 endpoints) ​

MethodPathAuthStatusDescription
GET/v2/my-challengesAuthLiveList user's challenges
GET/v2/my-challenges/statsAuthLiveChallenge completion stats
GET/v2/my-challenges/status-mapAuthLiveChallenge status map
PUT/v2/my-challenges/:id/statusAuthLiveUpdate challenge status

Track Records (8 endpoints) ​

MethodPathAuthStatusDescription
GET/v2/track-records/:idAuthLiveGet track record
POST/v2/track-records/:id/entriesAuthLiveAdd entry
PUT/v2/track-records/:id/entries/:entryIdAuthLiveUpdate entry
POST/v2/track-records/:id/entries/:entryId/mediaAuthLiveAdd media to entry
POST/v2/track-records/:id/submitAuthLiveSubmit for verification
POST/v2/track-records/:id/verifyAuthLiveVerify track record
POST/v2/track-records/:id/entries/:entryId/voteAuthLiveVote on entry
POST/v2/track-records/:id/entries/:entryId/commentsAuthLiveComment on entry

Gamification (5 endpoints) ​

MethodPathAuthStatusDescription
GET/v2/gamification/badges--LiveList all badges
GET/v2/gamification/badges/earnedAuthLiveGet user's earned badges
GET/v2/gamification/leaderboard--LiveGet leaderboard
GET/v2/gamification/statsAuthLiveGet user's XP stats
GET/v2/gamification/xp-historyAuthLiveGet XP event history

Explore (8 endpoints) ​

MethodPathAuthStatusDescription
GET/v2/exploreOptionalLiveGet explore page data
GET/v2/explore/searchOptionalLiveSearch challenges
GET/v2/explore/savedAuthLiveGet saved challenges
POST/v2/explore/savedAuthLiveSave a challenge
DELETE/v2/explore/saved/:challengeIdAuthLiveRemove saved challenge
POST/v2/explore/dealers-choice/dealAuthLiveDeal random challenges
POST/v2/explore/dealers-choice/selectAuthLiveSelect a dealt challenge
POST/v2/explore/dealers-choice/passAuthLivePass on dealt challenges

Learning Paths (3 endpoints) ​

MethodPathAuthStatusDescription
GET/v2/learning-pathsAuthLiveList learning paths
GET/v2/learning-paths/:idAuthLiveGet path details
POST/v2/learning-paths/:id/enrollAuthLiveEnroll in path

Schools (29 endpoints) ​

MethodPathAuthStatusDescription
GET/v2/schools/meAuthLiveGet user's school
GET/v2/schools/:idAuthLiveGet school details
GET/v2/schools/:id/classesAuthLiveList classes
POST/v2/schools/:id/classesAuth+RoleLiveCreate class
PUT/v2/schools/:id/classes/:classIdAuth+RoleLiveUpdate class
GET/v2/schools/:id/classes/:classId/statsAuthLiveClass statistics
GET/v2/schools/:id/rosterAuthLiveStudent roster
POST/v2/schools/:id/rosterAuth+RoleLiveAdd student
POST/v2/schools/:id/roster/importAuth+RoleLiveBulk import roster
DELETE/v2/schools/:id/roster/:studentIdAuth+RoleLiveRemove student
PUT/v2/schools/:id/roster/:studentId/suspendAuth+RoleLiveSuspend student
PUT/v2/schools/:id/roster/:studentId/reinstateAuth+RoleLiveReinstate student
GET/v2/schools/:id/teachersAuthLiveTeacher roster
POST/v2/schools/:id/teachersAuth+RoleLiveAdd teacher
GET/v2/schools/:id/assignmentsAuthLiveList assignments
POST/v2/schools/:id/assignmentsAuth+RoleLiveCreate assignment
GET/v2/schools/assignments/:id/progressAuthLiveAssignment progress
PUT/v2/schools/assignments/:idAuth+RoleLiveUpdate assignment
GET/v2/schools/:id/gradesAuthLiveList grade levels
POST/v2/schools/:id/gradesAuth+RoleLiveCreate grade level
PUT/v2/schools/:id/grades/:gradeIdAuth+RoleLiveUpdate grade level
DELETE/v2/schools/:id/grades/:gradeIdAuth+RoleLiveDelete grade level
GET/v2/schools/:id/surveysAuthLiveList surveys
POST/v2/schools/:id/surveysAuth+RoleLiveCreate survey
PUT/v2/schools/:id/surveys/:surveyIdAuth+RoleLiveUpdate survey
DELETE/v2/schools/:id/surveys/:surveyIdAuth+RoleLiveDelete survey
GET/v2/schools/:id/purchase-requestsAuthLiveList purchase requests
POST/v2/schools/:id/purchase-requestsAuthLiveCreate purchase request
PUT/v2/schools/:id/purchase-requests/:requestId/reviewAuth+RoleLiveReview request

Vendor (7 endpoints) ​

MethodPathAuthStatusDescription
GET/v2/vendor/profileAuthLiveGet vendor profile
PUT/v2/vendor/profileAuthLiveUpdate vendor profile
POST/v2/vendor/onboardingAuthLiveSubmit onboarding
GET/v2/vendor/challengesAuthLiveGet vendor's challenges
GET/v2/vendor/analyticsAuthLiveVendor analytics
POST/v2/vendor/eventsAuthLiveCreate event
POST/v2/vendor/team/inviteAuthLiveInvite team member

Gifts (5 endpoints) ​

MethodPathAuthStatusDescription
POST/v2/giftsAuthLiveSend a gift
GET/v2/giftsAuthLiveList gifts
POST/v2/gifts/:id/acceptAuthLiveAccept gift
POST/v2/gifts/:id/declineAuthLiveDecline gift
DELETE/v2/gifts/:idAuthLiveCancel gift

Invitations (4 endpoints) ​

MethodPathAuthStatusDescription
POST/v2/invitationsAuthLiveCreate invitation
GET/v2/invitationsAuthLiveList invitations
POST/v2/invitations/:id/respondAuthLiveRespond to invitation
DELETE/v2/invitations/:idAuthLiveCancel invitation

Admin (15 endpoints) ​

MethodPathAuthStatusDescription
GET/v2/admin/usersAdminLiveList all users
GET/v2/admin/users/:idAdminLiveGet user detail
PUT/v2/admin/users/:idAdminLiveUpdate user
GET/v2/admin/challenges/approval-queueAdminLivePending approvals
POST/v2/admin/challenges/:id/approveAdminLiveApprove challenge
GET/v2/admin/flagged-contentAdminLiveFlagged content
POST/v2/admin/flagged-content/:id/resolveAdminLiveResolve flag
GET/v2/admin/audit-logsAdminStubAudit logs (empty)
GET/v2/admin/vendorsAdminLiveList vendors
POST/v2/admin/vendors/:id/approveAdminLiveApprove vendor
GET/v2/admin/analyticsAdminLivePlatform analytics
GET/v2/admin/schoolsAdminLiveList schools
GET/v2/admin/reviewsAdminLiveList reviews
GET/v2/admin/ordersAdminLiveList orders
POST/v2/admin/couponsAdminLiveCreate coupon

Notifications (5 endpoints) ​

MethodPathAuthStatusDescription
GET/v2/notificationsAuthLiveGet notifications
PUT/v2/notifications/:id/readAuthLiveMark as read
PUT/v2/notifications/read-allAuthLiveMark all as read
GET/v2/notifications/preferencesAuthLiveGet preferences
PUT/v2/notifications/preferencesAuthLiveUpdate preferences

Portfolios (4 endpoints) ​

MethodPathAuthStatusDescription
GET/v2/portfoliosAuthLiveList portfolios
POST/v2/portfoliosAuthLiveCreate portfolio
PUT/v2/portfolios/:idAuthLiveUpdate portfolio
GET/v2/portfolios/:idAuthLiveGet portfolio

Reflections (9 endpoints) ​

MethodPathAuthStatusDescription
GET/v2/reflections/promptsAuthLiveList prompts
POST/v2/reflections/promptsAuthLiveCreate prompt
PUT/v2/reflections/prompts/:idAuthLiveUpdate prompt
DELETE/v2/reflections/prompts/:idAuthLiveDelete prompt
GET/v2/reflections/question-bankAuthLiveGet question bank
GET/v2/reflections/responsesAuthLiveGet responses
POST/v2/reflections/responsesAuthLiveSubmit response
GET/v2/reflections/user/:userIdAuthLiveGet user reflections
GET/v2/reflections/analyticsAuthLiveReflection analytics

Payments (10 endpoints) ​

MethodPathAuthStatusDescription
GET/v2/payments/methodsAuthLiveGet payment methods
POST/v2/payments/checkoutAuthStubCreate checkout session
POST/v2/payments/create-intentAuthPartialCreate payment intent
POST/v2/payments/confirmAuthLiveConfirm payment
GET/v2/payments/status/:idAuthLiveGet payment status
POST/v2/payments/calculate-taxAuthStubCalculate tax (flat 8%)
GET/v2/payments/ordersAuthLiveList orders
GET/v2/payments/orders/:idAuthLiveGet order detail
POST/v2/payments/orders/:id/refundAuthLiveRequest refund
POST/v2/payments/apply-couponAuthLiveApply coupon

Communities (24 endpoints) ​

MethodPathAuthStatusDescription
GET/v2/communitiesOptionalLiveList communities
POST/v2/communitiesAuthLiveCreate community
GET/v2/communities/:idOptionalLiveGet community
PUT/v2/communities/:idAuthLiveUpdate community
POST/v2/communities/:id/joinAuthLiveJoin community
POST/v2/communities/:id/leaveAuthLiveLeave community
GET/v2/communities/:id/members--LiveGet members
PUT/v2/communities/:id/members/:userIdAuthLiveUpdate member role
GET/v2/communities/:id/feed--LiveGet feed
POST/v2/communities/:id/feedAuthLiveCreate feed item
POST/v2/communities/feed-items/:id/likeAuthLiveLike feed item
POST/v2/communities/feed-items/:id/commentsAuthLiveComment on feed
POST/v2/communities/:id/assignmentsAuthLiveCreate assignment
GET/v2/communities/:id/assignments--LiveList assignments
POST/v2/communities/:id/goalsAuthLiveCreate goal
GET/v2/communities/:id/goals--LiveList goals
GET/v2/communities/:id/goals/:goalId--LiveGet goal
PUT/v2/communities/:id/goals/:goalIdAuthLiveUpdate goal
POST/v2/communities/:id/goals/:goalId/joinAuthLiveJoin goal
POST/v2/communities/:id/goals/:goalId/contributeAuthLiveContribute to goal
GET/v2/communities/:id/goals/:goalId/leaderboard--LiveGoal leaderboard
POST/v2/communities/content-reportsAuthLiveReport content
POST/v2/communities/batch-shareAuthLiveBatch share
POST/v2/communities/:id/inviteAuthLiveInvite to community

Events (6 endpoints) ​

MethodPathAuthStatusDescription
GET/v2/eventsOptionalLiveList events
GET/v2/events/my-registrationsAuthLiveMy registrations
GET/v2/events/challenge/:challengeId--LiveEvents for challenge
GET/v2/events/:idOptionalLiveGet event
POST/v2/events/:id/registerAuthLiveRegister for event
DELETE/v2/events/:id/registerAuthLiveCancel registration

Onboarding (5 endpoints) ​

MethodPathAuthStatusDescription
GET/v2/onboardingAuthPartialGet state (in-memory)
POST/v2/onboarding/initAuthPartialInitialize (in-memory)
POST/v2/onboarding/complete-stepAuthPartialComplete step (in-memory)
POST/v2/onboarding/completeAuthPartialFinish onboarding (in-memory)
GET/v2/onboarding/guided-tourAuthLiveGet guided tour config

System (1 endpoint) ​

MethodPathAuthStatusDescription
GET/health--LiveHealth check

Request/Response Examples ​

Register ​

bash
curl -X POST http://localhost:8000/api/portal/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "MyPassword123!",
    "displayName": "Jane Doe",
    "dateOfBirth": "2000-01-15"
  }'
json
{
  "success": true,
  "data": {
    "user": {
      "id": "a1b2c3d4-...",
      "email": "user@example.com",
      "displayName": "Jane Doe",
      "role": "user",
      "accountTier": "standard"
    },
    "tokens": {
      "accessToken": "eyJhbG...",
      "refreshToken": "eyJhbG...",
      "expiresAt": "2026-02-14T12:15:00.000Z"
    }
  }
}

List Challenges ​

bash
curl http://localhost:8000/api/portal/v2/challenges?page=1&limit=10
json
{
  "success": true,
  "data": [
    {
      "id": "f5e6d7c8-...",
      "title": "Rock Climbing 101",
      "difficulty": "beginner",
      "baseXp": 100,
      "isFree": true,
      "status": "approved"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 42,
    "totalPages": 5,
    "hasMore": true
  }
}

Health Dashboard ​

When the server is running, visit the live HTML dashboard for a visual overview of all endpoint implementation status:

http://localhost:8000/api/portal/health/dashboard

The dashboard shows per-module coverage bars, filterable endpoint lists, and overall live/partial/stub counts.

See Also ​

DoCurious Platform Documentation

Copyright 2026 DoCurious