{"openapi":"3.0.0","info":{"title":"ClinicHub API","version":"1.0.0","description":"API documentation for the ClinicHub platform","contact":{"name":"ClinicHub Support","url":"https://clinichub24.com"}},"servers":[{"url":"https://clinic-hub-apis.vercel.app","description":"Production Server"},{"url":"http://localhost:3006","description":"Development Server"},{"url":"https://api.clinichub24.com","description":"Legacy Production Server"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}}},"security":[{"bearerAuth":[]}],"paths":{"/api/billing/claims":{"get":{"tags":["Billing"],"summary":"Fetch Insurance Claims","description":"Retrieves a list of insurance claims for the current organization, optionally filtered by status.","parameters":[{"in":"query","name":"status","required":false,"schema":{"type":"string"},"description":"Filter claims by status (e.g., PENDING, PAID, REJECTED)."}],"responses":{"200":{"description":"A list of insurance claims.","content":{"application/json":{"schema":{"type":"object","properties":{"claims":{"type":"array","items":{"type":"object"}},"total":{"type":"integer"}}}}}},"400":{"description":"Missing organization context."},"401":{"description":"Unauthorized."}}},"post":{"tags":["Billing"],"summary":"Create Insurance Claim","description":"Creates a new insurance claim for a patient.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["patientId","claimNumber","insuranceCompany","serviceDate","submissionDate","billedAmount"],"properties":{"patientId":{"type":"string"},"claimNumber":{"type":"string"},"insuranceCompany":{"type":"string"},"serviceDate":{"type":"string","format":"date"},"submissionDate":{"type":"string","format":"date"},"billedAmount":{"type":"number"},"status":{"type":"string"}}}}}},"responses":{"201":{"description":"Claim created successfully."}}}},"/api/billing/dashboard":{"get":{"tags":["Billing"],"summary":"Fetch Billing Dashboard Metrics","description":"Returns aggregated metrics for the billing dashboard, including revenue, pending invoices, insurance claims, and aging reports.","responses":{"200":{"description":"Dashboard metrics retrieved successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"revenue":{"type":"object"},"pendingInvoices":{"type":"object"},"claims":{"type":"object"},"collections":{"type":"object"},"recentActivity":{"type":"array"},"alerts":{"type":"array"}}}}}},"400":{"description":"Missing organization context."},"401":{"description":"Unauthorized."}}}},"/api/billing/payments":{"get":{"tags":["Billing"],"summary":"Fetch Payments","description":"Retrieves a list of payments for the current organization, including invoice and patient details.","responses":{"200":{"description":"A list of payments.","content":{"application/json":{"schema":{"type":"object","properties":{"payments":{"type":"array","items":{"type":"object"}},"total":{"type":"integer"}}}}}},"400":{"description":"Missing organization context."},"401":{"description":"Unauthorized."}}},"post":{"tags":["Billing"],"summary":"Create Payments","description":"Creates new payment records and updates the status of associated invoices.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount","paymentMethod","allocations"],"properties":{"paymentDate":{"type":"string","format":"date-time"},"amount":{"type":"number"},"paymentMethod":{"type":"string"},"transactionId":{"type":"string"},"notes":{"type":"string"},"allocations":{"type":"array","items":{"type":"object","properties":{"invoiceId":{"type":"string"},"amount":{"type":"number"}}}}}}}}},"responses":{"200":{"description":"Payments created successfully."},"400":{"description":"Missing required fields or context."}}}},"/api/calendar/google/callback":{"get":{"tags":["Calendar"],"summary":"Google Calendar OAuth Callback","description":"Handles OAuth callback from Google after user grants calendar access.","parameters":[{"in":"query","name":"code","required":true,"schema":{"type":"string"},"description":"Authorization code from Google."},{"in":"query","name":"state","required":true,"schema":{"type":"string"},"description":"Base64 encoded state object containing providerId and nonce."}],"responses":{"302":{"description":"Redirects to calendar settings page with success or error status."}}}},"/api/chat":{"post":{"tags":["AI"],"summary":"AI Support Chat","description":"Interactive support assistant powered by Gemini AI with access to system statistics, pricing, and feature information.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["messages"],"properties":{"messages":{"type":"array","items":{"type":"object","properties":{"role":{"type":"string","enum":["user","assistant"]},"content":{"type":"string"}}}}}}}}},"responses":{"200":{"description":"Streaming AI response."},"429":{"description":"Rate limit exceeded."}}}},"/api/documents/serve/{documentId}":{"get":{"tags":["Documents"],"summary":"Serve Document","description":"Serves a document via a stateless signed URL. Supports Patient, Clinic, and Organization documents.","parameters":[{"in":"path","name":"documentId","required":true,"schema":{"type":"string"},"description":"The ID of the document to serve."},{"in":"query","name":"token","required":true,"schema":{"type":"string"},"description":"Security token for signature verification."},{"in":"query","name":"exp","required":true,"schema":{"type":"integer"},"description":"Expiry timestamp (ms)."},{"in":"query","name":"uid","required":true,"schema":{"type":"string"},"description":"User ID of the requester."}],"responses":{"200":{"description":"The document file.","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Missing required parameters."},"403":{"description":"Invalid or expired signed URL."},"404":{"description":"Document not found."}}}},"/api/hr/attendance":{"post":{"tags":["HR"],"summary":"Log Attendance (External Device)","description":"API Endpoint for external attendance devices (Punching Machines) to log staff IN/OUT events with geofencing.","parameters":[{"in":"header","name":"x-clinic-api-key","required":true,"schema":{"type":"string"},"description":"The unique API key for the clinic."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["staffId","type","latitude","longitude"],"properties":{"staffId":{"type":"string"},"type":{"type":"string","enum":["IN","OUT"]},"latitude":{"type":"number"},"longitude":{"type":"number"}}}}}},"responses":{"200":{"description":"Attendance logged successfully."},"401":{"description":"Unauthorized or missing API Key."},"404":{"description":"Staff record not found."},"429":{"description":"Rate limit exceeded."}}}},"/api/notifications/send":{"post":{"tags":["Notifications"],"summary":"Send Immediate Notification","description":"Sends a notification via SMS, EMAIL, WHATSAPP, PUSH, or IN_APP channels. Requires authentication and appropriate staff roles.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["recipientContact","channel","category","messageBody"],"properties":{"patientId":{"type":"string"},"recipientContact":{"type":"string"},"channel":{"type":"string","enum":["SMS","EMAIL","WHATSAPP","PUSH","IN_APP"]},"category":{"type":"string","enum":["APPOINTMENT_REMINDER","APPOINTMENT_CONFIRMATION","LAB_RESULT_READY","PRESCRIPTION_READY","PAYMENT_DUE","PATIENT_REGISTRATION","GENERAL_ANNOUNCEMENT"]},"templateId":{"type":"string"},"subject":{"type":"string"},"messageBody":{"type":"string"}}}}}},"responses":{"200":{"description":"Notification sent successfully."},"400":{"description":"Validation error or failed to send."},"401":{"description":"Unauthorized."}}}},"/api/organizations/validate-slug":{"get":{"tags":["Organizations"],"summary":"Validate Organization Slug","description":"Checks if a slug is available for a new organization or an existing one during update.","parameters":[{"in":"query","name":"slug","required":true,"schema":{"type":"string"},"description":"The slug to validate."},{"in":"query","name":"excludeId","required":false,"schema":{"type":"string"},"description":"Organization ID to exclude from validation (used when updating)."}],"responses":{"200":{"description":"Validation result.","content":{"application/json":{"schema":{"type":"object","properties":{"available":{"type":"boolean"},"slug":{"type":"string"}}}}}},"400":{"description":"Missing slug parameter."},"401":{"description":"Unauthorized."}}}},"/api/v1/admin/audit/export":{"post":{"summary":"Export audit logs for legal discovery","tags":["Admin","Security"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditExport"}}}},"responses":{"200":{"description":"Audit log export initiated"}}}},"/api/v1/admin/rbac/permissions":{"get":{"summary":"Get Granular RBAC permissions list","tags":["Admin","Security"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"module","schema":{"type":"string"}}],"responses":{"200":{"description":"Permissions list fetched successfully"}}}},"/api/v1/admin/security/ip-whitelist":{"post":{"summary":"Add IP to whitelist for organization or clinic","tags":["Admin","Security"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IPWhitelist"}}}},"responses":{"200":{"description":"IP added to whitelist"}}}},"/api/v1/admin/support/impersonate":{"post":{"summary":"Secure logged support impersonation","tags":["Admin","Security"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupportImpersonate"}}}},"responses":{"200":{"description":"Impersonation initiated successfully"}}}},"/api/v1/ai/grounding/verify":{"post":{"summary":"Verify AI claims against trusted medical sources","tags":["AI","Compliance"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GroundingVerify"}}}},"responses":{"200":{"description":"Verification successful"}}}},"/api/v1/ai/patient-summary":{"post":{"tags":["AI"],"summary":"Generate Patient Summary Agent","description":"Uses an autonomous AI agent to analyze the patient's record (allergies, conditions, medications) and provide a holistic clinical summary.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["patientId"],"properties":{"patientId":{"type":"string"},"encounterContext":{"type":"string","description":"Optional context like \"pre-visit analysis\" or \"post-discharge summary\"."}}}}}},"responses":{"200":{"description":"AI summary generated successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object"},"metadata":{"type":"object"}}}}}},"400":{"description":"Validation error."},"401":{"description":"Unauthorized."},"404":{"description":"Patient not found."}}}},"/api/v1/ai/soap/quality":{"post":{"tags":["AI"],"summary":"Audit SOAP Note Quality","description":"Analyzes the clinical quality, completeness, and structure of a SOAP note for medical encounters.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["encounterId","patientId","noteType"],"properties":{"encounterId":{"type":"string"},"patientId":{"type":"string"},"noteType":{"type":"string","enum":["SUBJECTIVE","OBJECTIVE","ASSESSMENT","PLAN","FULL"]},"content":{"type":"string"}}}}}},"responses":{"200":{"description":"Analysis report including scores and suggestions."},"401":{"description":"Unauthorized."},"429":{"description":"AI quota exceeded."}}}},"/api/v1/billing/aging-report":{"get":{"summary":"AR Aging Report","tags":["Billing"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"clinicId","schema":{"type":"string"}}],"responses":{"200":{"description":"Aging report generated successfully"}}}},"/api/v1/billing/claims/submit/edi":{"post":{"summary":"Submit claims via EDI 837 (Availity Bridge)","tags":["Billing"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EDIClaimSubmission"}}}},"responses":{"200":{"description":"Claims submitted successfully"},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"}}}},"/api/v1/billing/dunning/trigger":{"post":{"summary":"Trigger automated dunning reminders","tags":["Billing"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DunningTrigger"}}}},"responses":{"200":{"description":"Dunning workflow triggered successfully"}}}},"/api/v1/billing/eligibility/check":{"post":{"summary":"Real-time insurance eligibility check (270/271)","tags":["Billing"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EligibilityCheck"}}}},"responses":{"200":{"description":"Eligibility check performed successfully"}}}},"/api/v1/billing/era/import":{"post":{"summary":"Import ERA 835 files","tags":["Billing"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ERAImport"}}}},"responses":{"200":{"description":"ERA imported successfully"}}}},"/api/v1/diagnostics/imaging/upload":{"post":{"tags":["Diagnostics & Lab"],"summary":"Register Imaging Study","description":"Registers a new imaging study (DICOM) and links it to an order.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["imagingOrderId","studyInstanceUid"],"properties":{"imagingOrderId":{"type":"string"},"studyInstanceUid":{"type":"string"},"modality":{"type":"string"},"bodyPart":{"type":"string"},"seriesCount":{"type":"integer"},"instanceCount":{"type":"integer"},"viewerUrl":{"type":"string"}}}}}},"responses":{"200":{"description":"Imaging study registered successfully."}}}},"/api/v1/diagnostics/imaging/viewer-token":{"get":{"tags":["Diagnostics & Lab"],"summary":"Get Imaging Viewer Token","description":"Generates a signed access token for the zero-footprint DICOM viewer.","security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"studyId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Viewer token generated successfully."}}}},"/api/v1/diagnostics/lab/alert/critical":{"post":{"tags":["Diagnostics & Lab"],"summary":"Trigger Critical Alert","description":"Escalates a critical lab result to the ordering provider.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["labResultId","criticalValue","criticalType","providerId","notificationMethod"],"properties":{"labResultId":{"type":"string"},"criticalValue":{"type":"string"},"criticalType":{"type":"string","enum":["HIGH","LOW"]},"providerId":{"type":"string"},"notificationMethod":{"type":"string","enum":["PHONE","PAGE","IN_PERSON","APP_NOTIFICATION"]}}}}}},"responses":{"200":{"description":"Critical alert triggered and logged."}}}},"/api/v1/diagnostics/lab/queue":{"get":{"tags":["Diagnostics & Lab"],"summary":"Get Lab Fulfillment Queue","description":"Returns a list of lab orders pending specimen collection or processing.","security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"clinicId","schema":{"type":"string"}},{"in":"query","name":"labId","schema":{"type":"string"}},{"in":"query","name":"status","schema":{"type":"string","enum":["SUBMITTED","SPECIMEN_PENDING","SPECIMEN_COLLECTED","RECEIVED","PROCESSING"]}},{"in":"query","name":"priority","schema":{"type":"string","enum":["ROUTINE","URGENT","STAT"]}},{"in":"query","name":"search","schema":{"type":"string"}}],"responses":{"200":{"description":"Lab queue retrieved successfully."},"401":{"description":"Unauthorized."}}}},"/api/v1/diagnostics/lab/results/import":{"post":{"tags":["Diagnostics & Lab"],"summary":"Bulk Import Lab Results","description":"Imports lab results from LIS or external providers. Supports HL7-derived JSON.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["results"],"properties":{"source":{"type":"string"},"results":{"type":"array","items":{"type":"object","required":["labOrderId","testName","value"],"properties":{"labOrderId":{"type":"string"},"testName":{"type":"string"},"value":{"type":"string"},"isCritical":{"type":"boolean"}}}}}}}}},"responses":{"200":{"description":"Results imported successfully."}}}},"/api/v1/org/financial-export/erp":{"get":{"summary":"Export financial data for NetSuite/QuickBooks bridge","tags":["Organization","Finance","RCM"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"startDate","required":true,"schema":{"type":"string","format":"date-time"}},{"in":"query","name":"endDate","required":true,"schema":{"type":"string","format":"date-time"}},{"in":"query","name":"erpType","required":true,"schema":{"type":"string","enum":["NetSuite","QuickBooks","Xero","Custom"]}},{"in":"query","name":"format","schema":{"type":"string","enum":["CSV","JSON","XML"]}},{"in":"query","name":"includePHI","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Export successful"}}}},"/api/v1/org/sync/item-master":{"post":{"summary":"Sync item master prices and availability across clinics","tags":["Organization","Inventory","Sync"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ItemMasterSync"}}}},"responses":{"200":{"description":"Sync successful"}}}},"/api/v1/patient/allergies/{id}":{"patch":{"tags":["Patient Portal"],"summary":"Update Allergy","description":"Updates an existing allergy record for the authenticated patient.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"The allergy ID."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reaction":{"type":"string"},"severity":{"type":"string"},"status":{"type":"string"}}}}}},"responses":{"200":{"description":"Allergy updated successfully."},"401":{"description":"Unauthorized."},"404":{"description":"Allergy not found."}}},"delete":{"tags":["Patient Portal"],"summary":"Delete Allergy","description":"Removes an allergy record for the authenticated patient.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"The allergy ID."}],"responses":{"204":{"description":"Allergy deleted successfully."},"401":{"description":"Unauthorized."},"404":{"description":"Allergy not found."}}}},"/api/v1/patient/allergies":{"get":{"tags":["Patient Portal"],"summary":"My Allergies","description":"Returns a list of active allergies recorded for the authenticated patient.","responses":{"200":{"description":"Allergies retrieved successfully."},"401":{"description":"Unauthorized."}}},"post":{"tags":["Patient Portal"],"summary":"Report Allergy","description":"Allows the patient to record a new allergy or sensitivity.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["allergen","type","reaction","severity"],"properties":{"allergen":{"type":"string"},"type":{"type":"string","enum":["medication","food","environmental","other"]},"reaction":{"type":"string"},"severity":{"type":"string","enum":["mild","moderate","severe"]},"onsetDate":{"type":"string","format":"date"},"notes":{"type":"string"}}}}}},"responses":{"201":{"description":"Allergy reported successfully."}}}},"/api/v1/patient/appointment-requests":{"get":{"tags":["Patient Portal"],"summary":"My Appointment Requests","description":"Returns a list of appointment requests made by the authenticated patient.","parameters":[{"in":"query","name":"status","schema":{"type":"string"},"description":"Filter by request status (e.g., PENDING, COMPLETED)"}],"responses":{"200":{"description":"Appointment requests retrieved successfully."},"401":{"description":"Unauthorized."}}}},"/api/v1/patient/appointments/{id}/feedback":{"get":{"tags":["Patient Portal"],"summary":"Get Appointment Feedback","description":"Returns the feedback submitted for a specific appointment.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"The appointment ID."}],"responses":{"200":{"description":"Feedback retrieved successfully."},"401":{"description":"Unauthorized."},"404":{"description":"Feedback not found."}}},"post":{"tags":["Patient Portal"],"summary":"Submit Appointment Feedback","description":"Allows the patient to submit feedback for a completed appointment.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"The appointment ID."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["providerRating","waitTime","staffCourtesy","facilityCleanliness"],"properties":{"providerRating":{"type":"integer","minimum":1,"maximum":5},"waitTime":{"type":"string","enum":["0-10","10-20","20-30","30-45","45+"]},"staffCourtesy":{"type":"string","enum":["excellent","very-good","good","fair","poor"]},"facilityCleanliness":{"type":"string","enum":["excellent","very-good","good","fair","poor"]},"wouldRecommend":{"type":"boolean"},"comments":{"type":"string"}}}}}},"responses":{"201":{"description":"Feedback submitted successfully."},"400":{"description":"Invalid feedback data."},"401":{"description":"Unauthorized."},"409":{"description":"Feedback already submitted."}}}},"/api/v1/patient/appointments/{id}":{"get":{"tags":["Patient Portal"],"summary":"Appointment Details","description":"Returns detailed information for a specific appointment.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"The appointment ID."}],"responses":{"200":{"description":"Appointment details retrieved successfully."},"401":{"description":"Unauthorized."},"404":{"description":"Appointment not found."}}},"patch":{"tags":["Patient Portal"],"summary":"Cancel Appointment","description":"Allows the patient to cancel a specific appointment.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"The appointment ID."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["action"],"properties":{"action":{"type":"string","enum":["cancel"]},"reason":{"type":"string"},"notes":{"type":"string"}}}}}},"responses":{"200":{"description":"Appointment cancelled successfully."},"400":{"description":"Invalid request data."},"401":{"description":"Unauthorized."},"404":{"description":"Appointment not found."}}}},"/api/v1/patient/appointments/request-options":{"get":{"tags":["Patient Portal"],"summary":"Appointment Request Options","description":"Returns available clinics, providers, and appointment types for the authenticated patient to schedule a new appointment.","responses":{"200":{"description":"Request options retrieved successfully."},"401":{"description":"Unauthorized."}}}},"/api/v1/patient/appointments":{"get":{"tags":["Patient Portal"],"summary":"My Appointments","description":"Returns a list of appointments for the authenticated patient, with optional status and date range filters.","parameters":[{"in":"query","name":"status","schema":{"type":"string","enum":["all","SCHEDULED","CONFIRMED","COMPLETED","CANCELLED","NO_SHOW"]},"description":"Filter by appointment status."},{"in":"query","name":"dateRange","schema":{"type":"string","enum":["upcoming","past","all"]},"description":"Filter by date range category."}],"responses":{"200":{"description":"Appointments retrieved successfully."},"401":{"description":"Unauthorized."}}},"post":{"tags":["Patient Portal"],"summary":"Request Appointment","description":"Allows a patient to request a new appointment at a specific clinic with a specific provider.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["clinicId","providerId","appointmentType","preferredDate","reason"],"properties":{"clinicId":{"type":"string"},"providerId":{"type":"string"},"appointmentType":{"type":"string"},"preferredDate":{"type":"string","format":"date"},"reason":{"type":"string"},"requestedTime":{"type":"string","example":"14:30"},"notes":{"type":"string"}}}}}},"responses":{"201":{"description":"Appointment requested successfully."},"400":{"description":"Invalid request data."}}}},"/api/v1/patient/auth/login":{"post":{"tags":["Patient Portal"],"summary":"Patient Login","description":"Authenticate a patient using email and password to receive a session token.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","password"],"properties":{"email":{"type":"string"},"password":{"type":"string"}}}}}},"responses":{"200":{"description":"Login successful."},"401":{"description":"Invalid credentials."}}}},"/api/v1/patient/auth/logout":{"post":{"tags":["Patient Portal"],"summary":"Patient Logout","description":"Invalidate the current session token.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Logout successful."},"401":{"description":"Unauthorized."}}}},"/api/v1/patient/auth/register":{"post":{"tags":["Patient Portal"],"summary":"Patient Registration","description":"Register a new patient account with portal access.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["firstName","lastName","email","password","dateOfBirth","gender"],"properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"password":{"type":"string"},"dateOfBirth":{"type":"string","format":"date"},"gender":{"type":"string","enum":["MALE","FEMALE","OTHER","UNKNOWN"]}}}}}},"responses":{"201":{"description":"Registration successful."},"400":{"description":"Invalid input or user already exists."}}}},"/api/v1/patient/auth":{"get":{"tags":["Patient Portal"],"summary":"Get Current Session","description":"Returns the current patient's authentication and session information.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Current session info retrieved successfully."},"401":{"description":"Unauthorized."}}}},"/api/v1/patient/care-plans":{"get":{"tags":["Patient Portal"],"summary":"My Care Plans","description":"Returns a list of active and historical care plans for the authenticated patient.","responses":{"200":{"description":"Care plans retrieved successfully."},"401":{"description":"Unauthorized."}}}},"/api/v1/patient/consent/form":{"post":{"tags":["Patient Engagement"],"summary":"Submit Digital Consent","description":"Submits a digitally signed consent form.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["consentType","title"],"properties":{"consentType":{"type":"string"},"title":{"type":"string"},"version":{"type":"string"},"signatureUrl":{"type":"string"},"witnessName":{"type":"string"},"notes":{"type":"string"}}}}}},"responses":{"201":{"description":"Consent submitted successfully."},"400":{"description":"Invalid input."}}}},"/api/v1/patient/context":{"get":{"tags":["Patient Portal"],"summary":"Patient Session Context","description":"Returns contextual information for the authenticated patient's current session.","responses":{"200":{"description":"Context retrieved successfully."},"401":{"description":"Unauthorized."}}}},"/api/v1/patient/dashboard":{"get":{"tags":["Patient Portal"],"summary":"Patient Dashboard Metrics","description":"Returns a comprehensive overview of the authenticated patient's health data, including upcoming appointments, recent lab results, vitals, and billing status.","responses":{"200":{"description":"Dashboard data retrieved successfully."},"401":{"description":"Unauthorized."}}}},"/api/v1/patient/documents":{"get":{"tags":["Patient Portal"],"summary":"My Documents","description":"Returns a list of medical documents and files for the authenticated patient.","parameters":[{"in":"query","name":"documentType","schema":{"type":"string"},"description":"Filter by document type"},{"in":"query","name":"dateRange","schema":{"type":"string","enum":["all","recent","past-year"]},"description":"Filter by date range"}],"responses":{"200":{"description":"Documents retrieved successfully."},"401":{"description":"Unauthorized."}}}},"/api/v1/patient/health-book":{"get":{"tags":["Patient Portal"],"summary":"My Health Book Timeline","description":"Returns a chronological timeline of all health events (encounters, labs, vitals) for the authenticated patient.","parameters":[{"in":"query","name":"type","schema":{"type":"array","items":{"type":"string"}},"description":"Filter by entry types (e.g., ENCOUNTER, LAB_RESULT)."},{"in":"query","name":"startDate","schema":{"type":"string","format":"date"}},{"in":"query","name":"endDate","schema":{"type":"string","format":"date"}},{"in":"query","name":"page","schema":{"type":"integer","default":1}},{"in":"query","name":"limit","schema":{"type":"integer","default":20}}],"responses":{"200":{"description":"Health book retrieved successfully."},"401":{"description":"Unauthorized."}}},"post":{"tags":["Patient Portal"],"summary":"Sync Health Book","description":"Triggers a synchronization process to aggregate recent clinical records into the health book timeline.","responses":{"200":{"description":"Sync completed successfully."}}}},"/api/v1/patient/health-summary/conditions":{"get":{"tags":["Patient Portal"],"summary":"My Health Conditions","description":"Returns a list of active and historical conditions (Problems List) recorded for the authenticated patient.","responses":{"200":{"description":"Health conditions retrieved successfully."},"401":{"description":"Unauthorized."}}}},"/api/v1/patient/health-summary/family-history":{"get":{"tags":["Patient Portal"],"summary":"My Family History","description":"Returns the recorded family medical history for the authenticated patient.","responses":{"200":{"description":"Family history retrieved successfully."},"401":{"description":"Unauthorized."}}}},"/api/v1/patient/health-summary/imaging-results":{"get":{"tags":["Patient Portal"],"summary":"My Imaging Results","description":"Returns released (FINAL) imaging results for the authenticated patient.","responses":{"200":{"description":"Imaging results retrieved successfully."},"401":{"description":"Unauthorized."}}}},"/api/v1/patient/health-summary/immunizations/{id}/certificate":{"get":{"tags":["Patient Portal"],"summary":"Vaccination Certificate","description":"Returns a verifiable digital vaccination certificate for a specific record.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Certificate generated successfully."},"404":{"description":"Vaccination record not found."}}}},"/api/v1/patient/health-summary/immunizations/{id}":{"get":{"tags":["Patient Portal"],"summary":"Vaccination Detail","description":"Returns the full clinical details of a specific vaccination record.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Vaccination record retrieved successfully."},"404":{"description":"Vaccination record not found."}}}},"/api/v1/patient/health-summary/immunizations":{"get":{"tags":["Patient Portal"],"summary":"My Immunizations","description":"Returns the immunization history recorded for the authenticated patient.","responses":{"200":{"description":"Immunizations retrieved successfully."},"401":{"description":"Unauthorized."}}}},"/api/v1/patient/health-summary/surgeries":{"get":{"tags":["Patient Portal"],"summary":"My Surgical History","description":"Returns the surgical history recorded for the authenticated patient.","responses":{"200":{"description":"Surgical history retrieved successfully."},"401":{"description":"Unauthorized."}}}},"/api/v1/patient/immunizations/{id}":{"patch":{"tags":["Patient Portal"],"summary":"Update Immunization","description":"Updates an existing vaccination record for the authenticated patient.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"The immunization ID."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"vaccineName":{"type":"string"},"doseNumber":{"type":"integer"},"notes":{"type":"string"}}}}}},"responses":{"200":{"description":"Immunization updated successfully."},"401":{"description":"Unauthorized."},"404":{"description":"Immunization not found."}}},"delete":{"tags":["Patient Portal"],"summary":"Delete Immunization","description":"Removes a vaccination record for the authenticated patient.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"The immunization ID."}],"responses":{"204":{"description":"Immunization deleted successfully."},"401":{"description":"Unauthorized."},"404":{"description":"Immunization not found."}}}},"/api/v1/patient/immunizations":{"get":{"tags":["Patient Portal"],"summary":"My Immunizations","description":"Returns a list of vaccination records for the authenticated patient.","responses":{"200":{"description":"Vaccination records retrieved successfully."},"401":{"description":"Unauthorized."}}},"post":{"tags":["Patient Portal"],"summary":"Report Vaccination","description":"Allows the patient to record a new vaccination record.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["vaccineName","givenDate"],"properties":{"vaccineName":{"type":"string"},"vaccineCode":{"type":"string"},"doseNumber":{"type":"integer"},"givenDate":{"type":"string","format":"date-time"},"administeredBy":{"type":"string"},"batchNumber":{"type":"string"},"manufacturer":{"type":"string"},"expirationDate":{"type":"string","format":"date"},"site":{"type":"string"},"route":{"type":"string"},"notes":{"type":"string"}}}}}},"responses":{"201":{"description":"Vaccination record created successfully."}}}},"/api/v1/patient/insurance":{"get":{"tags":["Patient Portal"],"summary":"My Insurance","description":"Returns insurance information for the authenticated patient.","responses":{"200":{"description":"Insurance information retrieved successfully."},"401":{"description":"Unauthorized."}}}},"/api/v1/patient/interop/apple-health":{"post":{"tags":["Interoperability"],"summary":"Ingest Apple Health data","description":"Ingests patient health data from Apple HealthKit.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["dataType","records"],"properties":{"dataType":{"type":"string","enum":["STEPS","HEART_RATE","SLEEP","VITALS","ACTIVITY"]},"records":{"type":"array","items":{"type":"object","properties":{"value":{"type":"number"},"unit":{"type":"string"},"startDate":{"type":"string","format":"date-time"},"endDate":{"type":"string","format":"date-time"}}}},"deviceInfo":{"type":"object"}}}}}},"responses":{"200":{"description":"Data ingested successfully."},"400":{"description":"Invalid input."}}}},"/api/v1/patient/invoices":{"get":{"tags":["Patient Portal"],"summary":"My Invoices","description":"Returns a list of all open and paid invoices associated with the authenticated patient's account.","responses":{"200":{"description":"Invoices retrieved successfully."},"401":{"description":"Unauthorized."}}}},"/api/v1/patient/lab-results":{"get":{"tags":["Patient Portal"],"summary":"My Lab Results","description":"Returns a list of laboratory test results and diagnostic reports for the authenticated patient.","parameters":[{"in":"query","name":"category","schema":{"type":"string"},"description":"Filter by lab category (e.g., Blood Work, Imaging)."},{"in":"query","name":"dateRange","schema":{"type":"string","enum":["all","recent","past-year"]},"description":"Filter by date range."}],"responses":{"200":{"description":"Lab results retrieved successfully."},"401":{"description":"Unauthorized."}}}},"/api/v1/patient/messages/recipients":{"get":{"tags":["Patient Portal"],"summary":"My Message Recipients","description":"Returns a list of eligible recipients (providers, staff) that the authenticated patient can send messages to.","responses":{"200":{"description":"Recipients list retrieved successfully."},"401":{"description":"Unauthorized."}}}},"/api/v1/patient/messages":{"get":{"tags":["Patient Portal","Messaging"],"summary":"My Messages","description":"Returns a paginated list of messages for the authenticated patient.","parameters":[{"in":"query","name":"page","schema":{"type":"integer","default":1}},{"in":"query","name":"limit","schema":{"type":"integer","default":20}},{"in":"query","name":"search","schema":{"type":"string"},"description":"Search by message subject or sender."},{"in":"query","name":"isRead","schema":{"type":"string","enum":[true,false]}}],"responses":{"200":{"description":"Messages retrieved successfully."},"401":{"description":"Unauthorized."}}},"post":{"tags":["Patient Portal","Messaging"],"summary":"Send Message","description":"Allows the authenticated patient to send a message to a clinic staff member or provider.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["recipientId","subject","body"],"properties":{"recipientId":{"type":"string"},"subject":{"type":"string"},"body":{"type":"string"},"messageType":{"type":"string","enum":["GENERAL","APPOINTMENT","BILLING","PHARMACY","LAB","CLINICAL"]},"priority":{"type":"string","enum":["LOW","NORMAL","HIGH","URGENT"]},"attachments":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"201":{"description":"Message sent successfully."},"400":{"description":"Invalid message payload."}}}},"/api/v1/patient/payment-plans":{"get":{"tags":["Patient Portal","Billing"],"summary":"My Payment Plans","description":"Returns active and historical installment-based payment plans for the authenticated patient.","responses":{"200":{"description":"Payment plans retrieved successfully."},"401":{"description":"Unauthorized."}}}},"/api/v1/patient/payments":{"get":{"tags":["Patient Portal","Billing"],"summary":"My Payment History","description":"Returns a history of all payment transactions for the authenticated patient.","responses":{"200":{"description":"Payment history retrieved successfully."},"401":{"description":"Unauthorized."}}}},"/api/v1/patient/portal/proxy-invite":{"post":{"tags":["Patient Engagement"],"summary":"Invite family member as proxy","description":"Sends an invitation to a family member to manage or view patient records.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","relationship","permissions"],"properties":{"email":{"type":"string","format":"email"},"relationship":{"type":"string"},"permissions":{"type":"array","items":{"type":"string"}},"expiresAt":{"type":"string","format":"date-time"}}}}}},"responses":{"200":{"description":"Invite sent successfully."},"400":{"description":"Invalid input."},"401":{"description":"Unauthorized."}}}},"/api/v1/patient/prescriptions":{"get":{"tags":["Patient Portal"],"summary":"My Prescriptions","description":"Returns a list of prescriptions for the authenticated patient, with optional status and date range filters.","parameters":[{"in":"query","name":"status","schema":{"type":"string","enum":["DRAFT","ACTIVE","COMPLETED","CANCELLED","EXPIRED"]},"description":"Filter by prescription status."},{"in":"query","name":"dateRange","schema":{"type":"string","enum":["active","all","expired"]},"description":"Filter by date range category."}],"responses":{"200":{"description":"Prescriptions retrieved successfully."},"401":{"description":"Unauthorized."}}}},"/api/v1/patient/profile/{patientId}":{"get":{"tags":["Patient Portal"],"summary":"Patient Profile Details","description":"Returns the full profile details for the authenticated patient. The patientId must match the authenticated session.","parameters":[{"in":"path","name":"patientId","required":true,"schema":{"type":"string"},"description":"The patient ID."}],"responses":{"200":{"description":"Profile details retrieved successfully."},"401":{"description":"Unauthorized."},"403":{"description":"Access denied for requested patient profile."}}},"put":{"tags":["Patient Portal"],"summary":"Update Patient Profile","description":"Updates the profile information for the authenticated patient.","parameters":[{"in":"path","name":"patientId","required":true,"schema":{"type":"string"},"description":"The patient ID."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"phone":{"type":"string"},"address":{"type":"string"}}}}}},"responses":{"200":{"description":"Profile updated successfully."},"401":{"description":"Unauthorized."},"403":{"description":"Access denied for requested patient profile."}}}},"/api/v1/patient/profile":{"get":{"tags":["Patient Portal"],"summary":"My Profile","description":"Returns the full profile details for the authenticated patient.","responses":{"200":{"description":"Profile retrieved successfully."},"401":{"description":"Unauthorized."},"404":{"description":"Profile not found."}}},"put":{"tags":["Patient Portal"],"summary":"Update My Profile","description":"Allows the authenticated patient to update their personal information and contact details.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"phone":{"type":"string"},"address":{"type":"string"},"gender":{"type":"string","enum":["MALE","FEMALE","OTHER","UNKNOWN"]}}}}}},"responses":{"200":{"description":"Profile updated successfully."},"400":{"description":"Invalid profile data."},"401":{"description":"Unauthorized."}}}},"/api/v1/patient/programs":{"get":{"tags":["Patient Portal"],"summary":"My Health Programs","description":"Returns a list of long-term health programs (e.g., Weight Management, RPM) the authenticated patient is enrolled in.","responses":{"200":{"description":"Programs retrieved successfully."},"401":{"description":"Unauthorized."}}}},"/api/v1/patient/receipts":{"get":{"tags":["Patient Portal","Billing"],"summary":"My Receipts","description":"Returns a list of all receipts for point-of-service/copay payments made by the authenticated patient.","responses":{"200":{"description":"Receipts retrieved successfully."},"401":{"description":"Unauthorized."}}}},"/api/v1/patient/records/fhir-r5":{"get":{"tags":["Interoperability"],"summary":"Export FHIR R5 Patient Record","description":"Returns the patient's record in FHIR R5 format.","responses":{"200":{"description":"FHIR record retrieved successfully.","content":{"application/fhir+json":{"schema":{"type":"object"}}}},"401":{"description":"Unauthorized."}}}},"/api/v1/patient/statements":{"get":{"tags":["Patient Portal","Billing"],"summary":"My Billing Statements","description":"Returns a list of generated billing statements for the authenticated patient.","responses":{"200":{"description":"Statements retrieved successfully."},"401":{"description":"Unauthorized."}}}},"/api/v1/patient/vaccinations/schedule":{"get":{"tags":["Patient Portal"],"summary":"My Vaccination Schedule","description":"Returns the upcoming and historical vaccination schedule for the authenticated patient.","responses":{"200":{"description":"Schedule retrieved successfully."},"401":{"description":"Unauthorized."}}}},"/api/v1/patient/video-sessions":{"get":{"tags":["Patient Portal","Telemedicine"],"summary":"My Video Sessions","description":"Returns a history of past and upcoming telemedicine (video) sessions for the authenticated patient.","responses":{"200":{"description":"Video sessions retrieved successfully."},"401":{"description":"Unauthorized."}}},"post":{"tags":["Patient Portal","Telemedicine"],"summary":"Join Video Session","description":"Generates an access token and join URL for a specific telemedicine appointment.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["appointmentId"],"properties":{"appointmentId":{"type":"string"}}}}}},"responses":{"200":{"description":"Join data (token/URL) generated successfully."},"400":{"description":"Missing appointmentId or failed to join."}}}},"/api/v1/patient/vitals":{"get":{"tags":["Patient Portal"],"summary":"My Vitals History","description":"Returns a history of vitals (Blood Pressure, Heart Rate, Temperature, Weight, etc.) for the authenticated patient.","parameters":[{"in":"query","name":"timeRange","schema":{"type":"string","enum":["7d","30d","90d","1y"]},"description":"Time range for fetching vitals."}],"responses":{"200":{"description":"Vitals history retrieved successfully."},"401":{"description":"Unauthorized."}}},"post":{"tags":["Patient Portal"],"summary":"Record Vitals","description":"Allows the patient to self-record their vitals measurements.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"bloodPressureSystolic":{"type":"number"},"bloodPressureDiastolic":{"type":"number"},"heartRate":{"type":"number"},"temperature":{"type":"number"},"weight":{"type":"number"},"height":{"type":"number"},"oxygenSaturation":{"type":"number"},"notes":{"type":"string"},"recordedAt":{"type":"string","format":"date-time"}}}}}},"responses":{"201":{"description":"Vitals recorded successfully."}}}},"/api/v1/patient/waitlist/join":{"post":{"tags":["Patient Portal"],"summary":"Join Waitlist","description":"Allows the authenticated patient to join a provider's or clinic's waitlist for an appointment.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["providerId","clinicId","visitReason","appointmentType","preferredDate","preferredTimeOfDay"],"properties":{"providerId":{"type":"string"},"clinicId":{"type":"string"},"visitReason":{"type":"string"},"appointmentType":{"type":"string"},"preferredDate":{"type":"string"},"preferredTimeOfDay":{"type":"string"},"notes":{"type":"string"},"contactPhone":{"type":"string"},"contactEmail":{"type":"string"}}}}}},"responses":{"200":{"description":"Successfully joined waitlist."},"400":{"description":"Invalid input data."},"401":{"description":"Unauthorized."}}}},"/api/v1/patient/waitlist/status":{"get":{"tags":["Patient Portal"],"summary":"My Waitlist Status","description":"Returns the status of the authenticated patient's current waitlist entries.","responses":{"200":{"description":"Waitlist status retrieved successfully."},"401":{"description":"Unauthorized."}}}},"/api/v1/pharmacy/dispense":{"post":{"tags":["Pharmacy Operations"],"summary":"Dispense Medication","description":"Creates a dispensing record for a prescription item.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["pharmacyId","prescriptionId","prescriptionItemId","dispensedById","quantityDispensed"],"properties":{"pharmacyId":{"type":"string"},"prescriptionId":{"type":"string"},"prescriptionItemId":{"type":"string"},"dispensedById":{"type":"string"},"quantityDispensed":{"type":"integer"},"lotNumber":{"type":"string"},"expirationDate":{"type":"string","format":"date-time"},"isControlledSubstance":{"type":"boolean"},"scheduleClass":{"type":"string"},"notes":{"type":"string"}}}}}},"responses":{"200":{"description":"Medication dispensed successfully."},"400":{"description":"Validation error."},"401":{"description":"Unauthorized."}}}},"/api/v1/pharmacy/inventory":{"get":{"tags":["Pharmacy Operations"],"summary":"Get Pharmacy Inventory","description":"Returns a list of inventory items with batch details for a specific pharmacy.","security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"pharmacyId","required":true,"schema":{"type":"string"}},{"in":"query","name":"search","schema":{"type":"string"}},{"in":"query","name":"category","schema":{"type":"string"}},{"in":"query","name":"lowStock","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Inventory retrieved successfully."}}}},"/api/v1/pharmacy/orders":{"post":{"tags":["Pharmacy Operations"],"summary":"Create Supplier Order","description":"Creates a new purchase order for pharmacy supplies.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["pharmacyId","supplierId","items"],"properties":{"pharmacyId":{"type":"string"},"supplierId":{"type":"string"},"totalAmount":{"type":"number"},"notes":{"type":"string"},"items":{"type":"array","items":{"type":"object","required":["inventoryItemId","quantity"],"properties":{"inventoryItemId":{"type":"string"},"quantity":{"type":"integer"},"unitCost":{"type":"number"}}}}}}}}},"responses":{"201":{"description":"Purchase order created successfully."},"400":{"description":"Validation error."}}}},"/api/v1/pharmacy/verify":{"post":{"tags":["Pharmacy Operations"],"summary":"Verify Dispensing","description":"Final pharmacist verification for a dispensing record.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["dispensingRecordId","verifiedById"],"properties":{"dispensingRecordId":{"type":"string"},"verifiedById":{"type":"string"},"notes":{"type":"string"}}}}}},"responses":{"200":{"description":"Dispensing record verified successfully."},"400":{"description":"Validation error or unauthorized pharmacist."}}}},"/api/v1/pharmacy/witness":{"post":{"tags":["Pharmacy Operations"],"summary":"Witness Narcotics Dispensing","description":"Records a second-person witness for controlled substance dispensing.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["dispensingRecordId","witnessId","verificationMethod"],"properties":{"dispensingRecordId":{"type":"string"},"witnessId":{"type":"string"},"verificationMethod":{"type":"string","enum":["BIOMETRIC","PASSWORD","SMART_CARD"]},"notes":{"type":"string"}}}}}},"responses":{"200":{"description":"Witness recorded successfully."},"400":{"description":"Validation error."}}}},"/api/v1/provider/care-pathway/assign":{"post":{"summary":"Assign care pathway to patient","tags":["Clinical","Provider"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CarePathwayAssign"}}}},"responses":{"200":{"description":"Care pathway assigned successfully"}}}},"/api/v1/provider/clinical-decision-support":{"get":{"summary":"Get Guideline-grounded suggestions (CDS)","tags":["Clinical","Provider"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"patientId","schema":{"type":"string"}},{"in":"query","name":"ruleType","schema":{"type":"string"}}],"responses":{"200":{"description":"CDS suggestions fetched"}}}},"/api/v1/provider/doctor/appointments":{"get":{"tags":["Provider Portal"],"summary":"Doctor's Appointments","description":"Returns a list of appointments for the authenticated doctor. Defaults to today's appointments if no date is provided.","parameters":[{"in":"query","name":"date","schema":{"type":"string","format":"date"},"description":"The date to fetch appointments for (YYYY-MM-DD)."}],"responses":{"200":{"description":"Appointments retrieved successfully."},"401":{"description":"Unauthorized."}}}},"/api/v1/provider/doctor/dashboard":{"get":{"tags":["Provider Portal"],"summary":"Doctor's Dashboard Metrics","description":"Returns a summarized view of today's appointments, pending tasks, and alerts for the authenticated doctor.","responses":{"200":{"description":"Dashboard metrics retrieved successfully."},"401":{"description":"Unauthorized."},"500":{"description":"Internal server error."}}}},"/api/v1/provider/doctor/encounters/{id}":{"get":{"tags":["Provider Portal"],"summary":"Get Encounter Details","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Details retrieved successfully."},"404":{"description":"Encounter not found."}}},"put":{"tags":["Provider Portal"],"summary":"Update Encounter","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Updated successfully."}}}},"/api/v1/provider/doctor/encounters/{id}/sign":{"post":{"tags":["Provider Portal"],"summary":"Sign Encounter","description":"Signs a clinical encounter by updating its status to SIGNED.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Encounter signed successfully."},"400":{"description":"Failed to sign encounter."},"401":{"description":"Unauthorized."}}}},"/api/v1/provider/doctor/encounters":{"get":{"tags":["Provider Portal"],"summary":"List Encounters","description":"Returns a paginated list of clinical encounters for the authenticated doctor.","parameters":[{"in":"query","name":"page","schema":{"type":"integer","default":1}},{"in":"query","name":"limit","schema":{"type":"integer","default":20}},{"in":"query","name":"search","schema":{"type":"string"}},{"in":"query","name":"status","schema":{"type":"string","enum":["SCHEDULED","IN_PROGRESS","COMPLETED","CANCELLED"]}},{"in":"query","name":"patientId","schema":{"type":"string"}},{"in":"query","name":"appointmentId","schema":{"type":"string"}},{"in":"query","name":"date","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Encounters retrieved successfully."},"401":{"description":"Unauthorized."}}},"post":{"tags":["Provider Portal"],"summary":"Create Encounter","description":"Creates a new clinical encounter for a patient.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["patientId"],"properties":{"patientId":{"type":"string"},"appointmentId":{"type":"string"},"notes":{"type":"string"},"encounterType":{"type":"string"},"reasonForVisit":{"type":"string"}}}}}},"responses":{"201":{"description":"Encounter created successfully."},"400":{"description":"Invalid input or validation error."}}}},"/api/v1/provider/doctor/patients":{"get":{"tags":["Provider Portal"],"summary":"Search & List Patients","description":"Returns a paginated list of patients accessible to the authenticated doctor. Supports search by name/identifier.","parameters":[{"in":"query","name":"page","schema":{"type":"integer","default":1}},{"in":"query","name":"limit","schema":{"type":"integer","default":20}},{"in":"query","name":"search","schema":{"type":"string"},"description":"Search by patient name, ID, or phone number."}],"responses":{"200":{"description":"Patients retrieved successfully."},"401":{"description":"Unauthorized."}}}},"/api/v1/provider/doctor/prescriptions":{"get":{"tags":["Provider Portal"],"summary":"Doctor's Prescriptions","description":"Returns a paginated list of prescriptions for the authenticated doctor's clinic.","parameters":[{"in":"query","name":"page","schema":{"type":"integer","default":1}},{"in":"query","name":"limit","schema":{"type":"integer","default":20}},{"in":"query","name":"status","schema":{"type":"string","enum":["DRAFT","ACTIVE","COMPLETED","CANCELLED","EXPIRED"]}},{"in":"query","name":"search","schema":{"type":"string"},"description":"Search by patient name or prescription ID."},{"in":"query","name":"patientId","schema":{"type":"string"}}],"responses":{"200":{"description":"Prescriptions retrieved successfully."},"401":{"description":"Unauthorized."}}},"post":{"tags":["Provider Portal"],"summary":"Create Prescription","description":"Allows the authenticated doctor to issue a new prescription for a patient.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["patientId","items"],"properties":{"patientId":{"type":"string"},"notes":{"type":"string"},"items":{"type":"array","items":{"type":"object","required":["medicationName","dosage","frequency"],"properties":{"medicationName":{"type":"string"},"dosage":{"type":"string"},"frequency":{"type":"string"},"duration":{"type":"string"}}}}}}}}},"responses":{"201":{"description":"Prescription created successfully."},"400":{"description":"Invalid request data."}}}},"/api/v1/provider/doctor/prescriptions/templates":{"get":{"tags":["Provider Portal"],"summary":"Prescription Templates","description":"Returns a list of standardized prescription templates for common conditions/medications.","parameters":[{"in":"query","name":"search","schema":{"type":"string"},"description":"Search by template name or medication."},{"in":"query","name":"category","schema":{"type":"string"}},{"in":"query","name":"condition","schema":{"type":"string"}},{"in":"query","name":"limit","schema":{"type":"integer","default":20}}],"responses":{"200":{"description":"Prescription templates retrieved successfully."},"401":{"description":"Unauthorized."}}}},"/api/v1/provider/doctor/queue/{id}/status":{"patch":{"tags":["Provider Portal"],"summary":"Update Queue Status","description":"Updates the status of a specific queue entry (e.g., from WAITING to CALLED or IN_PROGRESS).","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"},"description":"The queue entry ID."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["WAITING","CALLED","IN_PROGRESS","COMPLETED","CANCELLED"]}}}}}},"responses":{"200":{"description":"Queue status updated successfully."},"400":{"description":"Invalid status provided."},"401":{"description":"Unauthorized."},"403":{"description":"Forbidden - Entry doesn't belong to the authenticated doctor."},"404":{"description":"Queue item not found."}}}},"/api/v1/provider/doctor/queue/next":{"post":{"tags":["Provider Portal"],"summary":"Call Next Patient","description":"Automatically calls the next waiting patient in the doctor's queue based on priority and time.","responses":{"200":{"description":"Next patient called successfully or queue is empty."},"401":{"description":"Unauthorized."}}}},"/api/v1/provider/doctor/queue":{"get":{"tags":["Provider Portal"],"summary":"Doctor's Patient Queue","description":"Returns the active patient queue for the authenticated doctor. Includes waiting, called, and in-progress patients.","parameters":[{"in":"query","name":"clinicId","schema":{"type":"string"},"description":"Optional clinic ID filter. Defaults to current clinic context."}],"responses":{"200":{"description":"Patient queue retrieved successfully."},"400":{"description":"Clinic context missing."},"401":{"description":"Unauthorized."},"404":{"description":"Provider profile not found."}}}},"/api/v1/provider/doctor/results":{"get":{"tags":["Provider Portal"],"summary":"Doctor's Lab Results","description":"Returns a paginated list of laboratory results for the authenticated doctor's clinic.","parameters":[{"in":"query","name":"page","schema":{"type":"integer","default":1}},{"in":"query","name":"limit","schema":{"type":"integer","default":20}},{"in":"query","name":"status","schema":{"type":"string","enum":["PENDING","COMPLETED","REVIEWED","CANCELLED"]}},{"in":"query","name":"search","schema":{"type":"string"},"description":"Search by patient name or result identifier."},{"in":"query","name":"patientId","schema":{"type":"string"},"description":"Filter results for a specific patient."}],"responses":{"200":{"description":"Lab results retrieved successfully."},"401":{"description":"Unauthorized."}}}},"/api/v1/provider/doctor/settings":{"get":{"tags":["Provider Portal"],"summary":"Doctor's Profile Settings","description":"Returns the professional profile, bio, and contact information for the authenticated doctor.","responses":{"200":{"description":"Profile settings retrieved successfully."},"401":{"description":"Unauthorized."}}},"patch":{"tags":["Provider Portal"],"summary":"Update Doctor Profile","description":"Allows the doctor to update their professional biography and specialization.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"bio":{"type":"string"},"specialization":{"type":"string"}}}}}},"responses":{"200":{"description":"Profile updated successfully."},"401":{"description":"Unauthorized."},"404":{"description":"Profile not found."}}}},"/api/v1/provider/doctor/video-sessions":{"get":{"tags":["Provider Portal","Telemedicine"],"summary":"Active Video Sessions","description":"Returns a list of all currently active telemedicine sessions for the authenticated doctor.","responses":{"200":{"description":"Video sessions retrieved successfully."},"401":{"description":"Unauthorized."}}},"post":{"tags":["Provider Portal","Telemedicine"],"summary":"Start Video Session","description":"Creates or initiates a new telemedicine session for a specific appointment.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["appointmentId","patientId"],"properties":{"appointmentId":{"type":"string"},"patientId":{"type":"string"}}}}}},"responses":{"201":{"description":"Video session created successfully."},"400":{"description":"Invalid session data."}}}},"/api/v1/provider/encounters/autosave":{"post":{"summary":"Autosave encounter draft","tags":["Clinical","Provider"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EncounterAutosave"}}}},"responses":{"200":{"description":"Encounter draft saved"}}}},"/api/v1/provider/referrals/outbound":{"post":{"summary":"Create outbound specialist referral","tags":["Clinical","Provider"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OutboundReferral"}}}},"responses":{"200":{"description":"Referral created successfully"}}}},"/api/v1/safety/code-blue/log":{"post":{"summary":"High-speed emergency event logger (Code Blue)","tags":["Safety","Emergency"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CodeBlueLog"}}}},"responses":{"200":{"description":"Emergency event logged"}}}},"/api/v1/safety/incident-report":{"post":{"summary":"Report an incident or near-miss","tags":["Safety","Compliance"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IncidentReport"}}}},"responses":{"200":{"description":"Incident report filed successfully"}}}}},"tags":[]}