API Reference
REST API authentication, base URL, standard response format, rate limits, and full endpoint listing.
Base URL and authentication
Production: https://doctor.clinit.app
Local dev: http://localhost:3000
All protected routes require a Bearer token:
Authorization: Bearer <accessToken>
Access tokens are obtained via POST /api/auth/login.
Tokens expire in 15 minutes. Use POST /api/auth/refresh to rotate.
Standard response format:
Success: { ...data } HTTP 200 or 201
Error: { "error": "message" } HTTP 400, 401, 403, 404, 409, 429, or 500
Authentication endpoints
POST /api/auth/login Login — returns accessToken and refreshToken
POST /api/auth/clinics Discover clinics for an email (pre-login)
POST /api/auth/refresh Rotate refresh token
GET /api/auth/me Current user profile
POST /api/auth/logout Invalidate refresh token
POST /api/auth/forgot-password Send password reset email
POST /api/auth/reset-password Reset via token from email
POST /api/auth/change-password Change password (authenticated)
POST /api/auth/2fa/setup Generate TOTP secret and QR URI
POST /api/auth/2fa/verify Enable 2FA by confirming TOTP code
POST /api/auth/2fa/verify-login Verify TOTP at login
POST /api/auth/2fa/disable Disable 2FA (password required)
Patient and appointment endpoints
Patients:
GET /api/patients List patients (search, page, limit)
POST /api/patients Create patient
GET /api/patients/[id] Patient profile
PATCH /api/patients/[id] Update patient
DELETE /api/patients/[id] Soft delete
GET /api/patients/[id]/history Clinical history (chronological)
GET /api/patients/[id]/sessions All session SOAP notes
GET /api/patients/[id]/billing Invoice list and balance
GET /api/patients/[id]/vitals Vital sign history
POST /api/patients/import Bulk CSV import
Appointments:
GET /api/appointments List (date, doctorId, status)
POST /api/appointments Create appointment
GET /api/appointments/[id] Single appointment with patient data
PATCH /api/appointments/[id] Update details
PATCH /api/appointments/[id]/status Transition status
GET /api/appointments/available-slots Available slots (doctorId, date, duration)
GET /api/appointments/active-session Currently in-chair appointment
POST /api/appointments/checkin Mark patient arrived
POST /api/appointments/auto-recur Generate recurring series
Billing and analytics endpoints
Billing:
GET/POST /api/billing/invoices List or create invoices
POST /api/billing/invoices/[id]/pay Record payment
POST /api/billing/invoices/[id]/installments Set up instalment plan
GET /api/billing/invoices/summary Revenue summary stats
GET/POST /api/billing/claims Insurance claims
GET /api/billing/overdue Overdue invoices
GET /api/billing/commissions Doctor commission breakdown
Analytics (requires CLINIC_OWNER or ADMIN role):
GET /api/analytics/revenue Revenue over time (from, to, groupBy)
GET /api/analytics/appointments Appointment trends (from, to, status)
GET /api/analytics/doctor-performance Per-doctor KPIs (from, to, doctorId)
GET /api/analytics/patients Patient growth stats (from, to)
GET /api/analytics/patient-ltv Lifetime value per patient
GET /api/analytics/cohort Monthly retention cohort (year)
GET /api/analytics/procedure-profitability Revenue per procedure (from, to)
GET /api/analytics/referral-sources Patient source breakdown
Error codes
400 — Bad Request: missing or invalid fields
401 — Unauthorized: missing, expired, or invalid token
403 — Forbidden: authenticated but insufficient role
404 — Not Found: resource does not exist or belongs to a different clinic
409 — Conflict: duplicate record or booking collision
423 — Locked: account locked after too many failed attempts
429 — Too Many Requests: rate limit exceeded
502 — Bad Gateway: upstream service error
503 — Service Unavailable: external service not configured
500 — Internal Server Error: unexpected error