API Reference

API Reference

All endpoints are Next.js Route Handlers under src/app/api/. Each protected handler is force-dynamic and verifies the JWT via verifyAuth(). Auth is carried by the httpOnly token cookie.

Legend: 🔓 public · 🔑 authenticated · 🩺 doctor · 🛡️ admin

Authentication — /api/auth

Method	Route	Access	Description
POST	/api/auth/register	🔓	Create a patient account (rate-limited 5/15min). Returns JWT cookie
POST	/api/auth/register/doctor	🔓	Create a doctor account (verified: false, pending review)
POST	/api/auth/login	🔓	Authenticate. If 2FA enabled, returns { requires2FA, userId } without issuing the JWT
GET	/api/auth/check	🔑	Returns { authenticated, user }; used by AuthContext on mount
GET	/api/auth/logout	🔑	Clears the session cookie
GET	/api/auth/2fa/setup	🔑	Generates a TOTP secret + provisioning URI (rendered as QR client-side)
POST	/api/auth/2fa/setup	🔑	Verifies the first code, enables 2FA, returns one-time recovery codes
POST	/api/auth/2fa/verify	🔓*	Verifies a code during the login challenge, then issues the JWT (*scoped to a pending userId)
POST	/api/auth/2fa/disable	🔑	Disables 2FA after verifying a current code
GET	/api/auth/google	🔑	Begins Google OAuth (Calendar)
GET	/api/auth/google/callback	🔑	OAuth callback; persists tokens to the doctor record
GET	/api/auth/google/status	🔑	{ connected: boolean }

Mood — /api/mood

Method	Route	Access	Description
GET	/api/mood?days=30	🔑	Returns { moods: [...] } within the window
POST	/api/mood	🔑	Logs { mood (1–10), activities[], notes }

Assessments — /api/assessment

Method	Route	Access	Description
GET	/api/assessment?limit=N	🔑	Returns { assessments: [...] } (newest first) — rate-limited
POST	/api/assessment	🔑	Saves PHQ-9/GAD-7 scores, answers, and severities
GET	/api/assessment/[id]	🔑	Returns one assessment's full breakdown

AI Chat — /api/chat

Method	Route	Access	Description
GET	/api/chat	🔑	Returns prior { messages }
POST	/api/chat	🔑	Sends a message; replies via OpenAI gpt-4o-mini (rate-limited 30/min). Injects recent mood + latest assessment as context. Falls back to keyword→specialist matching without an API key

Doctors — /api/doctors

Method	Route	Access	Description
GET	/api/doctors?specialty=...	🔑	Lists verified doctors, optional specialty filter
GET	/api/doctors/[id]	🔑	One doctor; with ?date=YYYY-MM-DD returns { availableSlots } generated from the doctor's workingHours and existing bookings (no Google Calendar required)
POST	/api/doctors/[id] (body: { rating, comment })	🔑	Submit a review (patient-only, one per completed appointment); recomputes averageRating

Slot generation: Available time slots are produced by src/app/lib/slotGenerator.js — it reads the doctor's workingHours from MongoDB and subtracts already-booked slots. No Google Calendar credentials needed.

Appointments — /api/appointments

Method	Route	Access	Description
GET	/api/appointments	🔑	Patient's appointments
POST	/api/appointments	🔑	Book { doctorId, dateTime, notes, useGoogleCalendar }. Slot validated against slotGenerator — no Google Calendar required for booking
DELETE	/api/appointments/[id]	🔑	Cancel an appointment
POST	/api/appointments/sync	🔑	Sync confirmed appointments to Google Calendar

Doctor portal — /api/doctor

Method	Route	Access	Description
GET	/api/doctor/stats	🩺	Upcoming count, total patients, pending reviews, avg rating
GET	/api/doctor/appointments?limit=N	🩺	Doctor's upcoming appointments
GET / PUT	/api/doctor/profile	🩺	Read/update profile incl. education, experience, working hours
GET	/api/doctor/reviews	🩺	Reviews for the doctor

Admin — /api/admin

Method	Route	Access	Description
GET	`/api/admin/doctors?status=pending	verified	rejected`
POST	/api/admin/doctors/[id]/verify	🛡️	Approve or reject ({ verified, rejected, rejectionReason })
POST	/api/admin/doctors/[id]/force-verify	🛡️	Force-verify a doctor

User & misc

Method	Route	Access	Description
GET	/api/user/profile	🔑	Current user profile (name, DOB, gender, phone, address, emergencyContact, twoFactorAuth status)
PUT	/api/user/profile	🔑	Update profile fields. UI: /settings/profile
GET	/api/resources	🔑	Paginated resource library. Falls back to bundled 102-item seed if collection is empty
GET	/api/resources/saved	🔑	User's bookmarked resources
POST	/api/resources/saved	🔑	Bookmark { resourceId }
DELETE	/api/resources/saved/[id]	🔑	Remove bookmark
GET	/api/recommendations	🔑	Personalized resource + doctor recommendations based on latest PHQ-9/GAD-7 and mood trends
GET	/api/dashboard/export	🔑	Export dashboard data as JSON

Related

• Authentication-and-Security · Architecture