{"openapi":"3.0.3","info":{"title":"VelaDent API","version":"1.0.0","description":"HTTP API for the VelaDent dashboard. See the **Authentication** tag for sign-in, session, profile, org discovery, and SAML endpoints. Clinical and org-scoped resources are listed under their respective tags.\n\n### Authentication\n1. `POST /api/auth/login` with `{ \"email\", \"password\" }` (optional `organizationId` for org domain login).\n2. Copy `accessToken` from the response (or rely on the httpOnly session cookie).\n3. In Swagger UI, click **Authorize** and enter: `Bearer <accessToken>` (or just the token, depending on UI).\n4. Org domain login: `POST /api/v1/auth/organization/discover` then sign in with the returned `organizationId`.\n\n### Organization id\nUse the user's `organizationId` from login (seed example: `org_acme_test`).\nClinical data is resolved via `CLINICAL_ORG_ID_<LOGIN_DOMAIN>` in server env.\n\n_Docs are enabled in development. Set `ENABLE_API_DOCS=true` to expose in production._"},"servers":[{"url":"https://veladent-mono-me10d5cmf-compliwise.vercel.app","description":"API origin"}],"tags":[{"name":"Authentication","description":"Sign-in, session, profile, organization domain discovery, and SAML SSO callback/exchange (not versioned under `/api/auth` except v1 discover/ACS)."},{"name":"Appointments","description":"Organization-scoped appointment and staff-block management (legacy `appointments` table)."},{"name":"Doctor schedules","description":"Organization-scoped doctor availability schedules (`weekly`, `specific`, and `unavailable` blocks)."},{"name":"Doctors","description":"Organization-scoped clinical doctors with user profile details."},{"name":"Clinic rooms","description":"Organization-scoped clinic treatment rooms for scheduling, availability, and bookings."},{"name":"Patient family","description":"Link patients in a household, manage share-accounts flags, and book sequential family appointments."},{"name":"Short notice","description":"Short-notice list, calendar gaps, and patient outreach for earlier appointment slots."},{"name":"Sites","description":"Organization site management, site access metadata, and active site switching."},{"name":"Patients","description":"Organization-scoped patient CRUD (legacy `patients` table)."},{"name":"Patient notes","description":"Organization-scoped patient notes with privacy, pagination, stats, and popup settings."},{"name":"Note templates","description":"Organization-scoped reusable note templates (quick notes) with sharing and search."},{"name":"Patient images","description":"Organization-scoped patient image upload and listing via Supabase Storage."},{"name":"Patient QR code","description":"Organization-scoped patient consent-form QR code generation as PNG."},{"name":"PDF signing","description":"Organization-scoped consent form signing, batch download, and resend via email."},{"name":"Patient consent forms","description":"Public token-based consent form viewing/upload and org-scoped form management."},{"name":"Patient appointments","description":"Organization-scoped appointment booking (legacy `patient_appointments` table)."},{"name":"Medical history","description":"Organization-scoped medical history records plus public token-based form retrieval/submission."},{"name":"Course of treatment","description":"Organization-scoped COT and treatment plans (legacy clinical tables)."},{"name":"Charting","description":"Organization-scoped dental charting visits and procedure entries (legacy `chartings` table)."},{"name":"Perio charting","description":"Organization-scoped periodontal charting, measurements, BPE assessments, display payload, and summary."},{"name":"Quick plans","description":"Provider quick treatment plan templates and apply-to-patient flow (legacy `quick_plans` tables)."},{"name":"Tasks","description":"Organization-scoped task management with status updates and subtasks (legacy `tasks` and `task_subtasks`)."},{"name":"Palette","description":"User-specific charting palette management for base and treatment popovers."},{"name":"Organization pricing","description":"Organization-scoped pricing settings, procedure pricing, currencies, and conversion flows."},{"name":"Organization charting procedure types","description":"Organization-scoped charting procedure type catalog with custom names and charting levels."},{"name":"Tooth history","description":"Organization-scoped unified tooth timeline (charting, COT and appointments) and tooth-specific history."},{"name":"Recalls","description":"Patient visit history, due recalls, and quick visit creation from the recalls workflow."},{"name":"Doctor chat","description":"Organization-scoped doctor-to-doctor messaging between clinical users."},{"name":"RBAC","description":"Organization-scoped roles, permissions, and clinical user role assignments."},{"name":"Inbox","description":"Organization-scoped email inbox threads, messages, and replies."},{"name":"Session recordings","description":"AI scribe: patient session audio capture, direct-to-worker upload, and diarized transcripts. Audio itself is never persisted."},{"name":"Clinical note drafts","description":"AI scribe: generated-but-unreviewed notes. Never surfaces in the patient record until finalized."}],"paths":{"/api/auth/login":{"post":{"tags":["Authentication"],"summary":"Sign in with email and password","description":"Verifies credentials and returns a JWT plus user profile. Also sets an httpOnly session cookie. When `organizationId` is supplied, enforces org password-login policy and membership.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoginRequest"}}}},"responses":{"200":{"description":"Login successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoginResponse"}}}},"400":{"description":"Validation error"},"401":{"description":"Invalid credentials"},"403":{"description":"Forbidden — organization policy blocks this sign-in method"},"500":{"description":"Internal server error"}}}},"/api/auth/logout":{"post":{"tags":["Authentication"],"summary":"Sign out","description":"Clears the httpOnly session cookie.","security":[],"responses":{"204":{"description":"Signed out"}}}},"/api/auth/session/establish":{"post":{"tags":["Authentication"],"summary":"Establish session cookie from Bearer token","description":"Sets the httpOnly session cookie from the request `Authorization: Bearer` token. Used after account switch when the client already holds a JWT.","security":[{"bearerAuth":[]}],"responses":{"204":{"description":"Session cookie set"},"401":{"description":"Authentication required"}}}},"/api/auth/me":{"get":{"tags":["Authentication"],"summary":"Get current user profile","description":"Returns the authenticated user's profile. Accepts Bearer token or session cookie.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Current user profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthUserProfile"}}}},"401":{"description":"Unauthorized — missing, invalid, or expired credentials"}}},"patch":{"tags":["Authentication"],"summary":"Update current user profile","description":"Updates the authenticated user's display name and/or avatar.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateProfileRequest"}}}},"responses":{"200":{"description":"Updated profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthUserProfile"}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized — missing, invalid, or expired credentials"}}}},"/api/auth/saml/exchange":{"post":{"tags":["Authentication"],"summary":"Exchange SAML sign-in code for session","description":"Redeems a one-time code created after SAML ACS success. Sets an httpOnly session cookie and returns the user profile (no `accessToken` in the body).","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SamlExchangeRequest"}}}},"responses":{"200":{"description":"Sign-in successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SamlExchangeResponse"}}}},"400":{"description":"Validation error"},"401":{"description":"Invalid, expired, or already-used sign-in code"}}}},"/api/v1/auth/organization/discover":{"post":{"tags":["Authentication"],"summary":"Discover organization login methods by domain","description":"Resolves which sign-in methods are available for an organization domain (password, SSO, LDAP). Returns SSO entry URLs and SAML SP metadata hints without exposing secrets.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DiscoverOrganizationRequest"}}}},"responses":{"200":{"description":"Organization and login flags","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DiscoverOrganizationResponse"}}}},"400":{"description":"Validation error"},"404":{"description":"Organization not found for this domain"}}}},"/api/v1/auth/saml/acs":{"post":{"tags":["Authentication"],"summary":"SAML Assertion Consumer Service (ACS)","description":"IdP callback endpoint. Accepts `application/x-www-form-urlencoded` POST with `SAMLResponse` (and optional `RelayState`). Returns HTML that completes the browser sign-in flow (not JSON).","security":[],"requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"SAMLResponse":{"type":"string","description":"Base64-encoded SAML assertion from the IdP."},"RelayState":{"type":"string","description":"Optional relay state from the IdP."}}}}}},"responses":{"200":{"description":"HTML completion page","content":{"text/html":{"schema":{"type":"string"}}}},"400":{"description":"HTML error page (e.g. missing SAMLResponse)","content":{"text/html":{"schema":{"type":"string"}}}}}}},"/api/v1/organizations/{organizationId}/appointments":{"get":{"tags":["Appointments"],"summary":"List appointments","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}}],"responses":{"200":{"description":"Appointments list"},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"}}},"post":{"tags":["Appointments"],"summary":"Create appointment","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}}],"responses":{"201":{"description":"Appointment created"},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"409":{"description":"Time-slot conflict"}}}},"/api/v1/organizations/{organizationId}/appointments/{appointmentId}":{"get":{"tags":["Appointments"],"summary":"Get appointment by id","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"appointmentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Appointment details"},"404":{"description":"Appointment not found"}}},"put":{"tags":["Appointments"],"summary":"Update appointment","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"appointmentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Appointment updated"},"400":{"description":"Validation error"},"403":{"description":"Forbidden"},"404":{"description":"Appointment not found"},"409":{"description":"Time-slot conflict"}}},"delete":{"tags":["Appointments"],"summary":"Delete appointment","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"appointmentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Appointment deleted"},"403":{"description":"Forbidden"},"404":{"description":"Appointment not found"}}}},"/api/v1/organizations/{organizationId}/doctor-schedules":{"post":{"tags":["Doctor schedules"],"summary":"Create a doctor schedule","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDoctorScheduleBody"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","required":["schedule","correlationId"],"properties":{"schedule":{"$ref":"#/components/schemas/DoctorSchedule"},"correlationId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"503":{"description":"Clinical org not linked or misconfigured"}}},"get":{"tags":["Doctor schedules"],"summary":"List doctor schedules","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"doctorId","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"scheduleType","in":"query","schema":{"type":"string","enum":["weekly","specific","unavailable"]}},{"name":"activeOnly","in":"query","schema":{"type":"string","enum":["true","false"]}}],"responses":{"200":{"description":"Schedules list","content":{"application/json":{"schema":{"type":"object","required":["schedules","correlationId"],"properties":{"schedules":{"type":"array","items":{"$ref":"#/components/schemas/DoctorSchedule"}},"correlationId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/doctor-schedules/{scheduleId}":{"put":{"tags":["Doctor schedules"],"summary":"Update a doctor schedule","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"scheduleId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateDoctorScheduleBody"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","required":["schedule","correlationId"],"properties":{"schedule":{"$ref":"#/components/schemas/DoctorSchedule"},"correlationId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"503":{"description":"Clinical org not linked or misconfigured"}}},"delete":{"tags":["Doctor schedules"],"summary":"Delete a doctor schedule","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"scheduleId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","required":["id","correlationId"],"properties":{"id":{"type":"string","format":"uuid"},"correlationId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/doctors":{"get":{"tags":["Doctors"],"summary":"List organization doctors","description":"Retrieves all doctors for the organization, including user name and avatar. Results are ordered by creation date (newest first).","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}}],"responses":{"200":{"description":"Doctors retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DoctorsListResponse"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/clinic-rooms":{"get":{"tags":["Clinic rooms"],"summary":"List clinic rooms","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"activeOnly","in":"query","schema":{"type":"boolean"}},{"name":"status","in":"query","schema":{"type":"string","enum":["vacant","inuse","unavailable"]}}],"responses":{"200":{"description":"Clinic rooms list"},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"409":{"description":"Conflict"},"503":{"description":"Clinical org not linked or misconfigured"}}},"post":{"tags":["Clinic rooms"],"summary":"Create clinic room","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateClinicRoomBody"}}}},"responses":{"201":{"description":"Created"},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"409":{"description":"Conflict"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/clinic-rooms/statuses":{"get":{"tags":["Clinic rooms"],"summary":"List allowed clinic room statuses","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}}],"responses":{"200":{"description":"Status values"},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"409":{"description":"Conflict"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/clinic-rooms/availability-for-slot":{"get":{"tags":["Clinic rooms"],"summary":"Rooms available for a time window","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}}],"responses":{"200":{"description":"Availability per room"},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"409":{"description":"Conflict"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/clinic-rooms/bulk":{"post":{"tags":["Clinic rooms"],"summary":"Create clinic rooms in bulk","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateClinicRoomBulkBody"}}}},"responses":{"201":{"description":"Bulk insert result"},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"409":{"description":"Conflict"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/clinic-rooms/{id}":{"patch":{"tags":["Clinic rooms"],"summary":"Update clinic room","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateClinicRoomBody"}}}},"responses":{"200":{"description":"Updated"},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"409":{"description":"Conflict"},"503":{"description":"Clinical org not linked or misconfigured"}}},"delete":{"tags":["Clinic rooms"],"summary":"Delete clinic room","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Deleted"},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"409":{"description":"Conflict"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/clinic-rooms/{roomId}/bookings":{"get":{"tags":["Clinic rooms"],"summary":"Booked intervals for one room on a calendar day","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"roomId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"date","in":"query","required":true,"schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Room bookings"},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"409":{"description":"Conflict"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/clinic-rooms/{roomId}/available-slots":{"get":{"tags":["Clinic rooms"],"summary":"Free slots for one room on a day","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"roomId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Available slots"},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"409":{"description":"Conflict"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/patient-family/patient/{patientId}":{"get":{"tags":["Patient family"],"summary":"List linked family members","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"patientId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Family members list"},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"409":{"description":"Conflict"},"503":{"description":"Clinical org not linked or misconfigured"}}},"post":{"tags":["Patient family"],"summary":"Link a family member","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"patientId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LinkFamilyMemberBody"}}}},"responses":{"201":{"description":"Linked"},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"409":{"description":"Conflict"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/patient-family/patient/{patientId}/booking-summary":{"get":{"tags":["Patient family"],"summary":"Family booking summary","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"patientId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Summary"},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"409":{"description":"Conflict"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/patient-family/patient/{patientId}/book":{"post":{"tags":["Patient family"],"summary":"Book sequential family appointments","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"patientId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FamilyBookingBody"}}}},"responses":{"201":{"description":"Booked"},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"409":{"description":"Conflict"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/patient-family/patient/{patientId}/member/{memberPatientId}":{"patch":{"tags":["Patient family"],"summary":"Update family member settings","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"patientId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"memberPatientId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateFamilyMemberBody"}}}},"responses":{"200":{"description":"Updated"},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"409":{"description":"Conflict"},"503":{"description":"Clinical org not linked or misconfigured"}}},"delete":{"tags":["Patient family"],"summary":"Unlink family member","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"patientId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"memberPatientId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Unlinked"},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"409":{"description":"Conflict"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/short-notice/entries":{"post":{"tags":["Short notice"],"summary":"Add appointment to short notice list","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateShortNoticeEntryBody"}}}},"responses":{"201":{"description":"Entry created"},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"409":{"description":"Conflict"},"503":{"description":"Clinical org not linked or misconfigured"}}},"get":{"tags":["Short notice"],"summary":"List short notice entries","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"doctorId","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"patientId","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Entry list"},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"409":{"description":"Conflict"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/short-notice/summary":{"get":{"tags":["Short notice"],"summary":"Dashboard summary stats","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}}],"responses":{"200":{"description":"Summary"},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"409":{"description":"Conflict"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/short-notice/gaps":{"get":{"tags":["Short notice"],"summary":"Calendar gaps with match counts","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}}],"responses":{"200":{"description":"Gaps"},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"409":{"description":"Conflict"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/short-notice/gaps/open":{"post":{"tags":["Short notice"],"summary":"Open or resume filling a gap","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}}],"responses":{"200":{"description":"Gap opened with matches"},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"409":{"description":"Conflict"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/sites":{"get":{"tags":["Sites"],"summary":"List accessible organization sites","description":"Returns active sites visible to the authenticated user and the user's active site id when set.","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"includeInactive","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"ORG_ADMIN and PLATFORM_ADMIN only."}],"responses":{"200":{"description":"Sites list","content":{"application/json":{"schema":{"type":"object","properties":{"activeSiteId":{"type":"string","nullable":true},"sites":{"type":"array","items":{"$ref":"#/components/schemas/Site"}},"correlationId":{"type":"string","format":"uuid"}}}}}},"401":{"description":"Unauthorized"}}},"post":{"tags":["Sites"],"summary":"Create organization site","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSiteBody"}}}},"responses":{"201":{"description":"Site created"},"400":{"description":"Validation error"},"403":{"description":"Requires ORG_ADMIN"},"409":{"description":"Site code already exists"}}}},"/api/v1/organizations/{organizationId}/sites/access-levels":{"get":{"tags":["Sites"],"summary":"List site access level metadata","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}}],"responses":{"200":{"description":"Site access level metadata","content":{"application/json":{"schema":{"type":"object","properties":{"levels":{"type":"array","items":{"$ref":"#/components/schemas/SiteAccessLevel"}},"selectItems":{"type":"array","items":{"type":"object"}},"defaultLevel":{"type":"string","example":"VIEW"}}}}}},"401":{"description":"Unauthorized"}}}},"/api/v1/organizations/{organizationId}/sites/{siteId}/switch":{"post":{"tags":["Sites"],"summary":"Switch active site","description":"Persists the selected active site on the authenticated user. Site-scoped patient, appointment, patient appointment, and task APIs use this active site as their data context.","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"siteId","in":"path","required":true,"schema":{"type":"string","example":"cmqqdljlo00077knkz8vgr66b"}}],"responses":{"200":{"description":"Active site switched","content":{"application/json":{"schema":{"type":"object","properties":{"activeSiteId":{"type":"string"},"site":{"$ref":"#/components/schemas/Site"},"correlationId":{"type":"string","format":"uuid"}}}}}},"400":{"description":"Cannot switch to inactive site"},"403":{"description":"Insufficient permissions"},"404":{"description":"Site not found"}}}},"/api/v1/organizations/{organizationId}/sites/{siteId}":{"put":{"tags":["Sites"],"summary":"Update organization site","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"siteId","in":"path","required":true,"schema":{"type":"string","example":"cmqqdljlo00077knkz8vgr66b"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSiteBody"}}}},"responses":{"200":{"description":"Site updated"},"400":{"description":"Validation error"},"403":{"description":"Insufficient permissions"},"404":{"description":"Site not found"}}}},"/api/v1/organizations/{organizationId}/recalls/patient/{patientId}/visits":{"get":{"tags":["Recalls"],"summary":"List patient visit history for recalls","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"patientId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"limit","in":"query","schema":{"type":"integer","default":50}},{"name":"visitType","in":"query","schema":{"type":"string"}},{"name":"startDate","in":"query","schema":{"type":"string","format":"date"}},{"name":"endDate","in":"query","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Visit history with pagination and statistics"},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"404":{"description":"Patient not found"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/recalls/patient/{patientId}/recalls-due":{"get":{"tags":["Recalls"],"summary":"Get recalls due for a patient","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"patientId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Computed recall items based on last visit"},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"404":{"description":"Patient not found"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/recalls/patient/{patientId}/visit":{"post":{"tags":["Recalls"],"summary":"Create a visit entry from the recalls page","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"patientId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRecallVisitBody"}}}},"responses":{"201":{"description":"Visit created"},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"404":{"description":"Patient not found"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/patients":{"get":{"tags":["Patients"],"summary":"List patients","description":"Returns patients for the organization's linked legacy clinical tenant. Supports search via `q`.","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test","description":"New auth organization id (cuid), not the legacy clinical uuid."}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":25}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}},{"name":"q","in":"query","description":"Search reference, name, phone, email, alt reference","schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Patient list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatientListResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"401":{"description":"Missing or invalid JWT","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"403":{"description":"User cannot access this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"503":{"description":"Legacy clinical organization not linked or misconfigured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}}}},"post":{"tags":["Patients"],"summary":"Create patient","description":"Creates a patient in the legacy clinical org. Reference number is assigned server-side (`P-XXXXXXXX`).","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test","description":"New auth organization id (cuid), not the legacy clinical uuid."}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePatientBody"}}}},"responses":{"201":{"description":"Patient created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatientDetailResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"401":{"description":"Missing or invalid JWT","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"403":{"description":"User cannot access this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"503":{"description":"Legacy clinical organization not linked or misconfigured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}}}}},"/api/v1/organizations/{organizationId}/patients/{patientId}":{"get":{"tags":["Patients"],"summary":"Get patient by id","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test","description":"New auth organization id (cuid), not the legacy clinical uuid."}},{"name":"patientId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Patient detail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatientDetailResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"401":{"description":"Missing or invalid JWT","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"403":{"description":"User cannot access this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"404":{"description":"Patient not found in this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"503":{"description":"Legacy clinical organization not linked or misconfigured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}}}},"patch":{"tags":["Patients"],"summary":"Update patient","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test","description":"New auth organization id (cuid), not the legacy clinical uuid."}},{"name":"patientId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePatientBody"}}}},"responses":{"200":{"description":"Patient updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatientDetailResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"401":{"description":"Missing or invalid JWT","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"403":{"description":"User cannot access this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"404":{"description":"Patient not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"503":{"description":"Legacy clinical organization not linked or misconfigured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}}}},"delete":{"tags":["Patients"],"summary":"Delete patient","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test","description":"New auth organization id (cuid), not the legacy clinical uuid."}},{"name":"patientId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Patient deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatientDeleteResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"401":{"description":"Missing or invalid JWT","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"403":{"description":"User cannot access this organization","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"404":{"description":"Patient not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"503":{"description":"Legacy clinical organization not linked or misconfigured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}}}}},"/api/v1/organizations/{organizationId}/patient-notes":{"post":{"tags":["Patient notes"],"summary":"Create a patient note","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePatientNoteBody"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","required":["note","correlationId"],"properties":{"note":{"$ref":"#/components/schemas/PatientNote"},"correlationId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/patient-notes/patient/{patientId}":{"get":{"tags":["Patient notes"],"summary":"List notes for a patient","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"patientId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"noteType","in":"query","schema":{"type":"string"}},{"name":"isPrivate","in":"query","schema":{"type":"string","enum":["true","false"]}}],"responses":{"200":{"description":"Notes list with pagination","content":{"application/json":{"schema":{"type":"object","required":["notes","pagination","correlationId"],"properties":{"notes":{"type":"array","items":{"$ref":"#/components/schemas/PatientNote"}},"pagination":{"$ref":"#/components/schemas/PatientNotesPagination"},"correlationId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/patient-notes/patient/{patientId}/stats":{"get":{"tags":["Patient notes"],"summary":"Get note statistics for a patient","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"patientId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Statistics","content":{"application/json":{"schema":{"type":"object","required":["stats","correlationId"],"properties":{"stats":{"$ref":"#/components/schemas/PatientNoteStats"},"correlationId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/patient-notes/patient/{patientId}/popup":{"get":{"tags":["Patient notes"],"summary":"Get active popup notes for a patient","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"patientId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Popup notes","content":{"application/json":{"schema":{"type":"object","required":["notes","total","correlationId"],"properties":{"notes":{"type":"array","items":{"$ref":"#/components/schemas/PatientNote"}},"total":{"type":"integer","minimum":0},"correlationId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/patient-notes/{noteId}":{"get":{"tags":["Patient notes"],"summary":"Get a patient note by id","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"noteId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Note","content":{"application/json":{"schema":{"type":"object","required":["note","correlationId"],"properties":{"note":{"$ref":"#/components/schemas/PatientNote"},"correlationId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"503":{"description":"Clinical org not linked or misconfigured"}}},"patch":{"tags":["Patient notes"],"summary":"Update a patient note","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"noteId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePatientNoteBody"}}}},"responses":{"200":{"description":"Updated note","content":{"application/json":{"schema":{"type":"object","required":["note","correlationId"],"properties":{"note":{"$ref":"#/components/schemas/PatientNote"},"correlationId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"503":{"description":"Clinical org not linked or misconfigured"}}},"delete":{"tags":["Patient notes"],"summary":"Delete a patient note","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"noteId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","required":["id","correlationId"],"properties":{"id":{"type":"string","format":"uuid"},"correlationId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/patient-notes/{noteId}/popup-setting":{"patch":{"tags":["Patient notes"],"summary":"Update popup setting for a note","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"noteId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchPatientNotePopupBody"}}}},"responses":{"200":{"description":"Updated note","content":{"application/json":{"schema":{"type":"object","required":["note","correlationId"],"properties":{"note":{"$ref":"#/components/schemas/PatientNote"},"correlationId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/note-templates":{"post":{"tags":["Note templates"],"summary":"Create a note template","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateNoteTemplateBody"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","required":["template","correlationId"],"properties":{"template":{"$ref":"#/components/schemas/NoteTemplate"},"correlationId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"503":{"description":"Clinical org not linked or misconfigured"}}},"get":{"tags":["Note templates"],"summary":"List note templates for the organization","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"siteId","in":"query","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"category","in":"query","schema":{"type":"string"}},{"name":"search","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Templates list with pagination","content":{"application/json":{"schema":{"type":"object","required":["templates","pagination","correlationId"],"properties":{"templates":{"type":"array","items":{"$ref":"#/components/schemas/NoteTemplate"}},"pagination":{"$ref":"#/components/schemas/NoteTemplatesPagination"},"correlationId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/note-templates/install-starters":{"post":{"tags":["Note templates"],"summary":"Install the shared starter note templates for this org","description":"Idempotent — templates whose title already exists as a shared template for this site are skipped rather than duplicated. Requires ORG_ADMIN or above.","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"siteId","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Installed/skipped starter titles","content":{"application/json":{"schema":{"type":"object","required":["installed","skipped","correlationId"],"properties":{"installed":{"type":"array","items":{"type":"string"}},"skipped":{"type":"array","items":{"type":"string"}},"correlationId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/note-templates/{templateId}":{"get":{"tags":["Note templates"],"summary":"Get a note template by id","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"templateId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Template","content":{"application/json":{"schema":{"type":"object","required":["template","correlationId"],"properties":{"template":{"$ref":"#/components/schemas/NoteTemplate"},"correlationId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"503":{"description":"Clinical org not linked or misconfigured"}}},"patch":{"tags":["Note templates"],"summary":"Update a note template","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"templateId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateNoteTemplateBody"}}}},"responses":{"200":{"description":"Updated template","content":{"application/json":{"schema":{"type":"object","required":["template","correlationId"],"properties":{"template":{"$ref":"#/components/schemas/NoteTemplate"},"correlationId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"503":{"description":"Clinical org not linked or misconfigured"}}},"delete":{"tags":["Note templates"],"summary":"Delete a note template","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"templateId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","required":["id","correlationId"],"properties":{"id":{"type":"string","format":"uuid"},"correlationId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/note-templates/{templateId}/generate":{"post":{"tags":["Note templates"],"summary":"Generate a draft clinical note from a transcript using this template","description":"Generating from a template is a read (own OR shared) — not creator-only. Does not create a PatientNote; the result is a ClinicalNoteDraft that must be reviewed and finalized separately.","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"templateId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateNoteBody"}}}},"responses":{"200":{"description":"Generated draft","content":{"application/json":{"schema":{"type":"object","required":["draft","correlationId"],"properties":{"draft":{"$ref":"#/components/schemas/ClinicalNoteDraft"},"correlationId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"413":{"description":"Transcript too long"},"422":{"description":"generation_truncated | ai_declined | schema mismatch"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/email-templates/upload":{"post":{"tags":["Email templates"],"summary":"Upload or upsert an email template","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadEmailTemplateBody"}}}},"responses":{"201":{"description":"Uploaded template","content":{"application/json":{"schema":{"type":"object","required":["template","correlationId"],"properties":{"template":{"$ref":"#/components/schemas/EmailTemplate"},"correlationId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"502":{"description":"Storage upload failed"},"503":{"description":"Clinical org not linked or storage misconfigured"}}}},"/api/v1/organizations/{organizationId}/email-templates":{"get":{"tags":["Email templates"],"summary":"List email templates for the organization","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"templateName","in":"query","schema":{"type":"string"}},{"name":"title","in":"query","schema":{"type":"string"}},{"name":"version","in":"query","schema":{"type":"string"}},{"name":"includeInactive","in":"query","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Templates list","content":{"application/json":{"schema":{"type":"object","required":["templates","total","correlationId"],"properties":{"templates":{"type":"array","items":{"$ref":"#/components/schemas/EmailTemplate"}},"total":{"type":"integer","minimum":0},"correlationId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"502":{"description":"Storage upload failed"},"503":{"description":"Clinical org not linked or storage misconfigured"}}}},"/api/v1/organizations/{organizationId}/email-templates/{templateId}":{"get":{"tags":["Email templates"],"summary":"Get an email template by id","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"templateId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Template","content":{"application/json":{"schema":{"type":"object","required":["template","correlationId"],"properties":{"template":{"$ref":"#/components/schemas/EmailTemplate"},"correlationId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"502":{"description":"Storage upload failed"},"503":{"description":"Clinical org not linked or storage misconfigured"}}},"patch":{"tags":["Email templates"],"summary":"Update an email template","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"templateId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateEmailTemplateBody"}}}},"responses":{"200":{"description":"Updated template","content":{"application/json":{"schema":{"type":"object","required":["template","correlationId"],"properties":{"template":{"$ref":"#/components/schemas/EmailTemplate"},"correlationId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"502":{"description":"Storage upload failed"},"503":{"description":"Clinical org not linked or storage misconfigured"}}},"delete":{"tags":["Email templates"],"summary":"Delete an email template","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"templateId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","required":["id","correlationId"],"properties":{"id":{"type":"string","format":"uuid"},"correlationId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"502":{"description":"Storage upload failed"},"503":{"description":"Clinical org not linked or storage misconfigured"}}}},"/api/v1/organizations/{organizationId}/patient-images/{patientId}":{"post":{"tags":["Patient images"],"summary":"Upload a patient image","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"patientId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["image"],"properties":{"image":{"type":"string","format":"binary"}}}}}},"responses":{"201":{"description":"Image uploaded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatientImageUploadResponse"}}}},"400":{"description":"Validation error or missing image file"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Patient not found"},"500":{"description":"Storage operation failed"},"503":{"description":"Clinical org or Supabase storage not configured"}}}},"/api/v1/organizations/{organizationId}/patient-images/{patientId}/images":{"get":{"tags":["Patient images"],"summary":"List patient image URLs","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"patientId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Image URLs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatientImagesListResponse"}}}},"400":{"description":"Validation error or missing image file"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Patient not found"},"500":{"description":"Storage operation failed"},"503":{"description":"Clinical org or Supabase storage not configured"}}}},"/api/v1/organizations/{organizationId}/qr/generate-qr/{patientId}":{"get":{"tags":["Patient QR code"],"summary":"Generate patient consent-forms QR code","description":"Returns a PNG QR code that points to the patient consent forms page in the portal.","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"patientId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"PNG QR image","content":{"image/png":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Patient not found"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/pdf-signing/sign":{"post":{"tags":["PDF signing"],"summary":"Sign consent forms and send to patient","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["certificate","passphrase","recipientEmail","patientId","forms"],"properties":{"certificate":{"type":"string","format":"binary"},"pdf":{"type":"string","format":"binary"},"passphrase":{"type":"string"},"recipientEmail":{"type":"string","format":"email"},"patientId":{"type":"string","format":"uuid"},"forms":{"type":"string","description":"JSON array of form objects"},"sendAs":{"type":"string","enum":["pdf","link"]},"expiryInMinutes":{"type":"integer"}}}}}},"responses":{"200":{"description":"Consent forms processed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignConsentFormsResponse"}}}},"400":{"description":"Validation error or missing required fields"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Patient, form, or template not found"},"500":{"description":"PDF processing, storage, or email failed"},"503":{"description":"Clinical org or Supabase storage not configured"}}}},"/api/v1/organizations/{organizationId}/pdf-signing/multi-forms-download":{"post":{"tags":["PDF signing"],"summary":"Batch process consent form templates with patient info","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["patientId","forms"],"properties":{"patientId":{"type":"string","format":"uuid"},"forms":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"200":{"description":"Forms processed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MultiFormsDownloadResponse"}}}},"400":{"description":"Validation error or missing required fields"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Patient, form, or template not found"},"500":{"description":"PDF processing, storage, or email failed"},"503":{"description":"Clinical org or Supabase storage not configured"}}}},"/api/v1/organizations/{organizationId}/pdf-signing/resend":{"post":{"tags":["PDF signing"],"summary":"Resend a pending consent form email","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["formId"],"properties":{"formId":{"type":"string","format":"uuid"},"extendExpiry":{"type":"boolean"},"expiryMinutes":{"type":"integer"}}}}}},"responses":{"200":{"description":"Consent form resent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResendConsentFormResponse"}}}},"400":{"description":"Validation error or missing required fields"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Patient, form, or template not found"},"500":{"description":"PDF processing, storage, or email failed"},"503":{"description":"Clinical org or Supabase storage not configured"}}}},"/api/v1/consent-forms/{patientId}/patients/{token}":{"get":{"tags":["Patient consent forms"],"summary":"View consent form via token (public)","security":[],"parameters":[{"name":"patientId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"token","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Consent form retrieved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConsentFormViewResponse"}}}},"400":{"description":"Validation error or missing required fields"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden — already signed or link expired"},"404":{"description":"Patient, form, or file not found"},"500":{"description":"Storage or database operation failed"},"503":{"description":"Supabase storage not configured"}}}},"/api/v1/consent-forms/{patientId}":{"post":{"tags":["Patient consent forms"],"summary":"Upload signed consent form (public)","security":[],"parameters":[{"name":"patientId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["organization_id","consent_file"],"properties":{"organization_id":{"type":"string","description":"Auth organization id (e.g. org_acme_test) or legacy clinical organization UUID."},"token":{"type":"string"},"consent_file":{"type":"string","format":"binary"}}}}}},"responses":{"200":{"description":"Consent form uploaded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadConsentFormResponse"}}}},"400":{"description":"Validation error or missing required fields"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden — already signed or link expired"},"404":{"description":"Patient, form, or file not found"},"500":{"description":"Storage or database operation failed"},"503":{"description":"Supabase storage not configured"}}}},"/api/v1/organizations/{organizationId}/consent-forms/certificate":{"get":{"tags":["Patient consent forms"],"summary":"Get organization signing certificate","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}}],"responses":{"200":{"description":"Certificate URL"},"400":{"description":"Validation error or missing required fields"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden — already signed or link expired"},"404":{"description":"Patient, form, or file not found"},"500":{"description":"Storage or database operation failed"},"503":{"description":"Supabase storage not configured"}}}},"/api/v1/organizations/{organizationId}/consent-forms/patients/{patientId}/token":{"get":{"tags":["Patient consent forms"],"summary":"Get latest consent form token for patient","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"patientId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Token retrieved"},"400":{"description":"Validation error or missing required fields"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden — already signed or link expired"},"404":{"description":"Patient, form, or file not found"},"500":{"description":"Storage or database operation failed"},"503":{"description":"Supabase storage not configured"}}}},"/api/v1/organizations/{organizationId}/consent-forms/forms/{formId}":{"get":{"tags":["Patient consent forms"],"summary":"Get consent form by ID","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"formId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Consent form detail"},"400":{"description":"Validation error or missing required fields"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden — already signed or link expired"},"404":{"description":"Patient, form, or file not found"},"500":{"description":"Storage or database operation failed"},"503":{"description":"Supabase storage not configured"}}}},"/api/v1/organizations/{organizationId}/consent-forms/patients/{patientId}/templates":{"get":{"tags":["Patient consent forms"],"summary":"List processed consent form templates for patient","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"patientId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Processed templates"},"400":{"description":"Validation error or missing required fields"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden — already signed or link expired"},"404":{"description":"Patient, form, or file not found"},"500":{"description":"Storage or database operation failed"},"503":{"description":"Supabase storage not configured"}}}},"/api/v1/organizations/{organizationId}/consent-forms/patients/{patientId}":{"get":{"tags":["Patient consent forms"],"summary":"List consent forms with status for patient","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"patientId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Consent forms with status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConsentFormsStatusResponse"}}}},"400":{"description":"Validation error or missing required fields"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden — already signed or link expired"},"404":{"description":"Patient, form, or file not found"},"500":{"description":"Storage or database operation failed"},"503":{"description":"Supabase storage not configured"}}}},"/api/v1/organizations/{organizationId}/patient-appointments":{"get":{"tags":["Patient appointments"],"summary":"List patient appointments","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"date","in":"query","schema":{"type":"string","format":"date"}},{"name":"doctorId","in":"query","schema":{"oneOf":[{"type":"string","format":"uuid"},{"type":"string","enum":["all"]}]}},{"name":"patientId","in":"query","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Appointments list","content":{"application/json":{"schema":{"type":"object","properties":{"appointments":{"type":"array","items":{"$ref":"#/components/schemas/PatientAppointment"}},"correlationId":{"type":"string"}}}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"503":{"description":"Clinical org not linked"}}},"post":{"tags":["Patient appointments"],"summary":"Book an appointment (consultation or COT)","description":"Creates a consultation or COT treatment appointment. When visitId matches a prep/fit pairable procedure, may auto-book a paired fit slot and return pairedAppointment + prepFitPair.","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePatientAppointmentBody"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePatientAppointmentResponse"}}}},"400":{"description":"Validation error"},"404":{"description":"Doctor, patient, or COT context not found"},"409":{"description":"Time slot or prep/fit pairing conflict"},"503":{"description":"Clinical org or booked-by not configured"}}}},"/api/v1/organizations/{organizationId}/patient-appointments/available-slots":{"get":{"tags":["Patient appointments"],"summary":"List available booking slots for a doctor","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"doctorId","in":"query","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"date","in":"query","required":true,"schema":{"type":"string","format":"date"}},{"name":"durationMinutes","in":"query","schema":{"type":"integer","default":60,"minimum":15,"maximum":480}}],"responses":{"200":{"description":"Slot grid for the day","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvailableSlotsResponse"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Doctor not found"},"503":{"description":"Clinical org not linked"}}}},"/api/v1/organizations/{organizationId}/patient-appointments/waiting":{"get":{"tags":["Patient appointments"],"summary":"Waiting / schedule indicator feed for today","description":"Returns today's scheduled or confirmed appointments with delay and waiting metadata for the schedule side panel.","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}}],"responses":{"200":{"description":"Waiting list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WaitingListResponse"}}}},"401":{"description":"Unauthorized"},"503":{"description":"Clinical org not linked"}}}},"/api/v1/organizations/{organizationId}/patient-appointments/{appointmentId}":{"get":{"tags":["Patient appointments"],"summary":"Get appointment by id","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"appointmentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Appointment","content":{"application/json":{"schema":{"type":"object","properties":{"appointment":{"$ref":"#/components/schemas/PatientAppointment"},"correlationId":{"type":"string"}}}}}},"404":{"description":"Not found"}}},"put":{"tags":["Patient appointments"],"summary":"Update or reschedule appointment","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"appointmentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePatientAppointmentBody"}}}},"responses":{"200":{"description":"Updated"},"400":{"description":"Validation error"},"404":{"description":"Not found"},"409":{"description":"Time slot conflict"}}},"delete":{"tags":["Patient appointments"],"summary":"Delete appointment","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"appointmentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Deleted"},"404":{"description":"Not found"}}}},"/api/v1/organizations/{organizationId}/patient-appointments/{appointmentId}/lab-work":{"patch":{"tags":["Patient appointments"],"summary":"Update lab work status","description":"Sets lab workflow state (sent, received, overdue, none_required) for fit-related appointments.","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"appointmentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchLabWorkBody"}}}},"responses":{"200":{"description":"Lab work status updated","content":{"application/json":{"schema":{"type":"object","properties":{"appointment":{"$ref":"#/components/schemas/LabWorkPatchResult"},"correlationId":{"type":"string"}}}}}},"400":{"description":"Invalid labWorkStatus"},"404":{"description":"Appointment not found"}}}},"/api/v1/organizations/{organizationId}/patient-appointments/{appointmentId}/send-reminder-email":{"post":{"tags":["Patient appointments"],"summary":"Send manual appointment reminder email","description":"Requires RESEND_API_KEY and patient email. Appointment must be pending or confirmed.","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"appointmentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Email sent","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":true},"correlationId":{"type":"string"}}}}}},"400":{"description":"Not configured, no patient email, or not schedulable"},"404":{"description":"Appointment not found"}}}},"/api/v1/organizations/{organizationId}/patient-appointments/{appointmentId}/send-reminder-sms":{"post":{"tags":["Patient appointments"],"summary":"Send manual appointment reminder SMS","description":"Requires NOVU_API_KEY and patient phone. Appointment must be pending or confirmed.","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"appointmentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"SMS triggered","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","example":true},"correlationId":{"type":"string"}}}}}},"400":{"description":"Not configured, no patient phone, or not schedulable"},"404":{"description":"Appointment not found"}}}},"/api/v1/organizations/{organizationId}/medical-history":{"post":{"tags":["Medical history"],"summary":"Create medical history record","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["patientId","medicalHistoryData"],"properties":{"patientId":{"type":"string","format":"uuid"},"medicalHistoryData":{"type":"object","additionalProperties":true}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"medicalHistory":{"$ref":"#/components/schemas/MedicalHistoryRecord"},"correlationId":{"type":"string"}}}}}}}}},"/api/v1/organizations/{organizationId}/medical-history/{patientId}":{"get":{"tags":["Medical history"],"summary":"Get current medical history and timeline by patient","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"patientId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Medical history payload"}}},"put":{"tags":["Medical history"],"summary":"Update medical history for patient","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"patientId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["medicalHistoryData"],"properties":{"medicalHistoryData":{"type":"object","additionalProperties":true}}}}}},"responses":{"200":{"description":"Updated"}}},"delete":{"tags":["Medical history"],"summary":"Delete medical history record","description":"Route path is shared with patientId endpoints; this operation expects a medical history record id.","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Deleted"}}}},"/api/v1/organizations/{organizationId}/medical-history/{patientId}/summary":{"get":{"tags":["Medical history"],"summary":"Get medical history summary for patient","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"patientId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Summary","content":{"application/json":{"schema":{"type":"object","properties":{"summary":{"$ref":"#/components/schemas/MedicalHistorySummary"},"correlationId":{"type":"string"}}}}}}}}},"/api/v1/organizations/{organizationId}/medical-history/record/{recordId}":{"get":{"tags":["Medical history"],"summary":"Get medical history record by id","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"recordId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Record","content":{"application/json":{"schema":{"type":"object","properties":{"medicalHistory":{"$ref":"#/components/schemas/MedicalHistoryRecord"},"correlationId":{"type":"string"}}}}}}}}},"/api/v1/organizations/{organizationId}/medical-history/send-form-link/{patientId}":{"post":{"tags":["Medical history"],"summary":"Send medical history form link to patient email","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"patientId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Link sent"}}}},"/api/v1/medical-history/form-by-token":{"get":{"tags":["Medical history"],"summary":"Get medical history form by public token","parameters":[{"name":"token","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Form payload loaded"}}},"put":{"tags":["Medical history"],"summary":"Submit medical history form by public token","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["token","medicalHistoryData"],"properties":{"token":{"type":"string"},"medicalHistoryData":{"type":"object","additionalProperties":true}}}}}},"responses":{"200":{"description":"Form submitted"}}}},"/api/v1/organizations/{organizationId}/palette":{"get":{"tags":["Palette"],"summary":"Get user palette","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}}],"responses":{"200":{"description":"Palette list"}}},"post":{"tags":["Palette"],"summary":"Add procedures to palette","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}}],"responses":{"201":{"description":"Added procedures"}}}},"/api/v1/organizations/{organizationId}/palette/{procedureType}":{"delete":{"tags":["Palette"],"summary":"Remove procedure from palette","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"procedureType","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Procedure removed"}}}},"/api/v1/organizations/{organizationId}/course-of-treatments":{"post":{"tags":["Course of treatment"],"summary":"Create a course of treatment","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCourseOfTreatmentBody"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","required":["courseOfTreatment","correlationId"],"properties":{"courseOfTreatment":{"$ref":"#/components/schemas/CourseOfTreatment"},"correlationId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/course-of-treatments/patient/{patientId}/active":{"get":{"tags":["Course of treatment"],"summary":"List active courses of treatment for a patient","description":"Returns open/completed COTs for the patient with payor rules summary (NHS single-dentist, multiple private).","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"patientId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"payor","in":"query","schema":{"type":"string","enum":["NHS","Private"]}},{"name":"includeAllStatuses","in":"query","schema":{"type":"boolean"},"description":"Accepts true/false or \"true\"/\"false\""}],"responses":{"200":{"description":"Active COTs","content":{"application/json":{"schema":{"type":"object","required":["activeCots","summary","correlationId"],"properties":{"activeCots":{"type":"array","items":{"$ref":"#/components/schemas/CourseOfTreatment"}},"summary":{"$ref":"#/components/schemas/ActiveCotsSummary"},"correlationId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/course-of-treatments/{cotId}":{"put":{"tags":["Course of treatment"],"summary":"Update course of treatment","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"cotId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCourseOfTreatmentBody"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","required":["courseOfTreatment","updatedFields","correlationId"],"properties":{"courseOfTreatment":{"$ref":"#/components/schemas/CourseOfTreatment"},"updatedFields":{"type":"array","items":{"type":"string"}},"correlationId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"503":{"description":"Clinical org not linked or misconfigured"}}},"delete":{"tags":["Course of treatment"],"summary":"Delete course of treatment","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"cotId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","required":["id","title","correlationId"],"properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"correlationId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/course-of-treatments/{cotId}/status":{"patch":{"tags":["Course of treatment"],"summary":"Patch course of treatment status","description":"Setting status to \"Completed\" sets completedAt automatically.","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"cotId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchCotStatusBody"}}}},"responses":{"200":{"description":"Status updated","content":{"application/json":{"schema":{"type":"object","required":["courseOfTreatment","correlationId"],"properties":{"courseOfTreatment":{"$ref":"#/components/schemas/CourseOfTreatment"},"correlationId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/course-of-treatments/{cotId}/treatments":{"get":{"tags":["Course of treatment"],"summary":"List treatments for a COT","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"cotId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Treatments with visit progression","content":{"application/json":{"schema":{"type":"object","required":["cot","treatments","summary","correlationId"],"properties":{"cot":{"$ref":"#/components/schemas/CotBrief"},"treatments":{"type":"array","items":{"$ref":"#/components/schemas/TreatmentPlanWithVisits"}},"summary":{"$ref":"#/components/schemas/TreatmentsListSummary"},"correlationId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"503":{"description":"Clinical org not linked or misconfigured"}}},"post":{"tags":["Course of treatment"],"summary":"Add treatment plan to COT","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"cotId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTreatmentPlanBody"}}}},"responses":{"201":{"description":"Treatment plan created","content":{"application/json":{"schema":{"type":"object","required":["treatmentPlan","correlationId"],"properties":{"treatmentPlan":{"$ref":"#/components/schemas/TreatmentPlan"},"correlationId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/course-of-treatments/{cotId}/treatments/{treatmentPlanId}":{"put":{"tags":["Course of treatment"],"summary":"Update treatment plan","description":"Updating estimatedCost recalculates COT totalCost.","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"cotId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"treatmentPlanId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateTreatmentPlanBody"}}}},"responses":{"200":{"description":"Treatment plan updated","content":{"application/json":{"schema":{"type":"object","required":["treatmentPlan","cot","updatedFields","correlationId"],"properties":{"treatmentPlan":{"$ref":"#/components/schemas/TreatmentPlan"},"cot":{"$ref":"#/components/schemas/CotBrief"},"updatedFields":{"type":"array","items":{"type":"string"}},"correlationId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/course-of-treatments/{cotId}/treatments/{treatmentPlanId}/nhs-band":{"patch":{"tags":["Course of treatment"],"summary":"Patch NHS band on a treatment plan","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"cotId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"treatmentPlanId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchNhsBandBody"}}}},"responses":{"200":{"description":"NHS band updated","content":{"application/json":{"schema":{"type":"object","required":["treatmentPlan","cot","previousBand","newBand","correlationId"],"properties":{"treatmentPlan":{"allOf":[{"$ref":"#/components/schemas/TreatmentPlan"},{"type":"object","properties":{"chartings":{"$ref":"#/components/schemas/CotChartingSummary","nullable":true}}}]},"cot":{"$ref":"#/components/schemas/CotBrief"},"previousBand":{"type":"string","enum":["Band 1","Band 2","Band 3","Band 4","Band 5"],"nullable":true},"newBand":{"type":"string","enum":["Band 1","Band 2","Band 3","Band 4","Band 5"]},"correlationId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/course-of-treatments/{cotId}/treatments/{treatmentPlanId}/link-chartings":{"post":{"tags":["Course of treatment"],"summary":"Link chartings as follow-up visits on a treatment plan","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"cotId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"treatmentPlanId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LinkChartingsBody"}}}},"responses":{"201":{"description":"Chartings linked","content":{"application/json":{"schema":{"type":"object","required":["treatmentPlanId","linkedChartings","totalVisits","updatedStatus","correlationId"],"properties":{"treatmentPlanId":{"type":"string","format":"uuid"},"linkedChartings":{"type":"array","items":{"$ref":"#/components/schemas/TreatmentPlanChartingLink"}},"totalVisits":{"type":"integer"},"updatedStatus":{"type":"string"},"correlationId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/course-of-treatments/{cotId}/treatments/{treatmentPlanId}/available-slots":{"get":{"tags":["Course of treatment"],"summary":"List available COT treatment booking slots","description":"Org-wide slot grid for the date (not doctor-specific). Returns up to 20 slots; totalAvailableSlots is the full count.","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"cotId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"treatmentPlanId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"date","in":"query","required":true,"schema":{"type":"string","format":"date","example":"2026-06-01"}},{"name":"durationMinutes","in":"query","required":true,"schema":{"type":"integer","minimum":1,"maximum":480}}],"responses":{"200":{"description":"Available slots","content":{"application/json":{"schema":{"type":"object","required":["cotId","treatmentPlanId","date","durationMinutes","availableSlots","totalAvailableSlots","correlationId"],"properties":{"cotId":{"type":"string","format":"uuid"},"treatmentPlanId":{"type":"string","format":"uuid"},"date":{"type":"string","format":"date"},"durationMinutes":{"type":"integer"},"availableSlots":{"type":"array","items":{"$ref":"#/components/schemas/CotTreatmentSlot"}},"totalAvailableSlots":{"type":"integer"},"correlationId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/course-of-treatments/{cotId}/visits":{"get":{"tags":["Course of treatment"],"summary":"List visits across all treatment plans in a COT","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"cotId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","schema":{"type":"string","enum":["pending","completed","cancelled"]}},{"name":"treatmentPlanId","in":"query","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Visits list","content":{"application/json":{"schema":{"type":"object","required":["cot","visits","summary","correlationId"],"properties":{"cot":{"$ref":"#/components/schemas/CotBrief"},"visits":{"type":"array","items":{"$ref":"#/components/schemas/CotVisit"}},"summary":{"type":"object","properties":{"totalVisits":{"type":"integer"},"visitsByStatus":{"type":"object","additionalProperties":{"type":"integer"}},"schedulingSummary":{"type":"object"}}},"correlationId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/course-of-treatments/{cotId}/visits/{visitId}/status":{"patch":{"tags":["Course of treatment"],"summary":"Patch visit status","description":"Marking a visit \"completed\" may auto-complete the parent treatment plan when all visits are done.","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"cotId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"visitId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchVisitStatusBody"}}}},"responses":{"200":{"description":"Visit status updated","content":{"application/json":{"schema":{"type":"object","required":["visit","treatmentPlan","cot","correlationId"],"properties":{"visit":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"treatmentPlanId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending","completed","cancelled"]}}},"treatmentPlan":{"type":"object","properties":{"id":{"type":"string","format":"uuid"}}},"cot":{"$ref":"#/components/schemas/CotBrief"},"correlationId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/course-of-treatments/{cotId}/appointments":{"get":{"tags":["Course of treatment"],"summary":"List appointments for a COT","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"cotId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"COT appointments","content":{"application/json":{"schema":{"type":"object","required":["cot","appointments","summary","correlationId"],"properties":{"cot":{"$ref":"#/components/schemas/CotBrief"},"appointments":{"type":"array","items":{"$ref":"#/components/schemas/CotAppointmentListItem"}},"summary":{"type":"object","properties":{"totalAppointments":{"type":"integer"},"appointmentsByStatus":{"type":"object","additionalProperties":{"type":"integer"}}}},"correlationId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/course-of-treatments/{cotId}/appointments/{appointmentId}":{"put":{"tags":["Course of treatment"],"summary":"Update a COT-linked patient appointment","description":"Delegates to patient appointment update (reschedule and/or status). Same body as PUT /patient-appointments/{id}.","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"cotId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"appointmentId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePatientAppointmentBody"}}}},"responses":{"200":{"description":"Appointment updated","content":{"application/json":{"schema":{"type":"object","required":["appointment","cot","updatedFields","correlationId"],"properties":{"appointment":{"$ref":"#/components/schemas/CotAppointmentListItem"},"cot":{"$ref":"#/components/schemas/CotBrief"},"updatedFields":{"type":"array","items":{"type":"string"}},"correlationId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"409":{"description":"Scheduling or paired-fit conflict"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/charting/procedure-types":{"get":{"tags":["Charting"],"summary":"List allowed procedure types","description":"Returns the global procedure catalog (org-specific overrides not yet supported).","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}}],"responses":{"200":{"description":"Procedure types","content":{"application/json":{"schema":{"type":"object","required":["procedureTypes"],"properties":{"procedureTypes":{"type":"array","items":{"type":"string"}}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/charting/materials/{procedureType}":{"get":{"tags":["Charting"],"summary":"List materials for a procedure type","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"procedureType","in":"path","required":true,"schema":{"type":"string","example":"Crown"}}],"responses":{"200":{"description":"Materials for procedure","content":{"application/json":{"schema":{"type":"object","required":["procedureType","materials"],"properties":{"procedureType":{"type":"string"},"materials":{"type":"array","items":{"type":"string"}}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/charting/check-recent-checkup/{patientId}":{"get":{"tags":["Charting"],"summary":"Check for a recent check-up (24h window)","description":"Procedures require an examination/consultation/check_up/cleaning/follow_up within the last 24 hours unless isBaseCharting is true.","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"patientId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Recent check-up status","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/RecentCheckupResult"},{"type":"object","properties":{"correlationId":{"type":"string"}}}]}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/charting/check-duplicate":{"post":{"tags":["Charting"],"summary":"Check for duplicate procedure charting","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckDuplicateChartingBody"}}}},"responses":{"200":{"description":"Duplicate check result","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CheckDuplicateChartingResult"},{"type":"object","properties":{"correlationId":{"type":"string"}}}]}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/charting":{"get":{"tags":["Charting"],"summary":"List chartings for a patient","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"patientId","in":"query","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Charting entries","content":{"application/json":{"schema":{"type":"object","required":["chartings","correlationId"],"properties":{"chartings":{"type":"array","items":{"$ref":"#/components/schemas/Charting"}},"correlationId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"503":{"description":"Clinical org not linked or misconfigured"}}},"post":{"tags":["Charting"],"summary":"Create a charting entry","description":"Creates a visit/procedure charting row and may auto-create or link a treatment plan on the COT. Returns **201** on create, **200** when an exact duplicate is skipped (`duplicateSkipped: true`).","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateChartingBody"}}}},"responses":{"200":{"description":"Exact duplicate skipped","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CreateChartingResult"},{"type":"object","properties":{"correlationId":{"type":"string"}}}]}}}},"201":{"description":"Created","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/CreateChartingResult"},{"type":"object","properties":{"correlationId":{"type":"string"}}}]}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/charting/{patientId}/{toothNumber}/{surface}":{"get":{"tags":["Charting"],"summary":"List procedure chartings for a tooth surface","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"patientId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"toothNumber","in":"path","required":true,"schema":{"type":"string","pattern":"^(UR|UL|LL|LR)([1-8]|[A-E])$","example":"UR1"}},{"name":"surface","in":"path","required":true,"schema":{"type":"string","enum":["top","bottom","left","right","center","center_left","center_right","whole_tooth"]}}],"responses":{"200":{"description":"Procedure chartings on tooth/surface","content":{"application/json":{"schema":{"type":"object","required":["chartings","correlationId"],"properties":{"chartings":{"type":"array","items":{"$ref":"#/components/schemas/Charting"}},"correlationId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/charting/{chartingId}":{"patch":{"tags":["Charting"],"summary":"Update a charting entry","description":"Patch notes, dates, provider, or treatment-plan visit status (status requires a linked visit).","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"chartingId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PatchChartingBody"}}}},"responses":{"200":{"description":"Updated charting","content":{"application/json":{"schema":{"type":"object","required":["charting","correlationId"],"properties":{"charting":{"$ref":"#/components/schemas/Charting"},"correlationId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/perio-charting":{"post":{"tags":["Perio charting"],"summary":"Create perio chart","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePerioChartBody"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","required":["chart","correlationId"],"properties":{"chart":{"$ref":"#/components/schemas/PerioChart"},"correlationId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/perio-charting/patient/{patientId}":{"get":{"tags":["Perio charting"],"summary":"List perio charts by patient","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"patientId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"cotId","in":"query","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":10}},{"name":"chartType","in":"query","required":false,"schema":{"type":"string","enum":["full","partial","bpe"]}}],"responses":{"200":{"description":"Perio chart list","content":{"application/json":{"schema":{"type":"object","required":["data","availableTeeth","filteredByAvailableTeeth","pagination","correlationId"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PerioChart"}},"availableTeeth":{"type":"array","items":{"type":"string"}},"filteredByAvailableTeeth":{"type":"boolean","enum":[true]},"pagination":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}},"correlationId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/perio-charting/patient/{patientId}/summary":{"get":{"tags":["Perio charting"],"summary":"Summarize perio charts for patient","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"patientId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Summary rows","content":{"application/json":{"schema":{"type":"object","required":["summaries","correlationId"],"properties":{"summaries":{"type":"array","items":{"type":"object"}},"correlationId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/perio-charting/patient/{patientId}/bpe":{"get":{"tags":["Perio charting"],"summary":"List BPE assessments by patient","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"patientId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"perioChartId","in":"query","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":10}}],"responses":{"200":{"description":"BPE list","content":{"application/json":{"schema":{"type":"object","required":["data","pagination","correlationId"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/BpeAssessment"}},"pagination":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}},"correlationId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/perio-charting/bpe/{bpeId}":{"get":{"tags":["Perio charting"],"summary":"Get BPE assessment by id","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"bpeId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"BPE assessment","content":{"application/json":{"schema":{"type":"object","required":["bpe","correlationId"],"properties":{"bpe":{"$ref":"#/components/schemas/BpeAssessment"},"correlationId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/perio-charting/{chartId}":{"get":{"tags":["Perio charting"],"summary":"Get perio chart by id","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"chartId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Perio chart","content":{"application/json":{"schema":{"type":"object","required":["chart","correlationId"],"properties":{"chart":{"$ref":"#/components/schemas/PerioChart"},"correlationId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"503":{"description":"Clinical org not linked or misconfigured"}}},"put":{"tags":["Perio charting"],"summary":"Update perio chart","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"chartId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePerioChartBody"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","required":["chart","correlationId"],"properties":{"chart":{"$ref":"#/components/schemas/PerioChart"},"correlationId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"503":{"description":"Clinical org not linked or misconfigured"}}},"delete":{"tags":["Perio charting"],"summary":"Delete perio chart","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"chartId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","required":["success","correlationId"],"properties":{"success":{"type":"boolean","enum":[true]},"correlationId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/perio-charting/{chartId}/display":{"get":{"tags":["Perio charting"],"summary":"Get display payload for perio chart","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"chartId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Display object","content":{"application/json":{"schema":{"type":"object","required":["display","correlationId"],"properties":{"display":{"type":"object"},"correlationId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/perio-charting/{chartId}/bpe":{"post":{"tags":["Perio charting"],"summary":"Create BPE assessment for chart","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"chartId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateBpeBody"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","required":["bpe","correlationId"],"properties":{"bpe":{"$ref":"#/components/schemas/BpeAssessment"},"correlationId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/perio-charting/{chartId}/bpe/{bpeId}/accept-ai-recommendations":{"post":{"tags":["Perio charting"],"summary":"Accept AI recommendations and create treatment plans","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"chartId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"bpeId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcceptAiRecommendationsBody"}}}},"responses":{"201":{"description":"Accepted and treatment plans created","content":{"application/json":{"schema":{"type":"object","required":["result","correlationId"],"properties":{"result":{"type":"object"},"correlationId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/quick-plans/my-plans":{"get":{"tags":["Quick plans"],"summary":"List active quick plans for the current provider","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}}],"responses":{"200":{"description":"Quick plans","content":{"application/json":{"schema":{"type":"object","properties":{"plans":{"type":"array","items":{"$ref":"#/components/schemas/QuickPlan"}},"correlationId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"409":{"description":"Conflict (e.g. patient already has active COT)"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/quick-plans/patient/{patientId}/active-cot":{"get":{"tags":["Quick plans"],"summary":"Get patient's active course of treatment (helper for apply flow)","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"patientId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Active COT if any","content":{"application/json":{"schema":{"type":"object","properties":{"hasActiveCot":{"type":"boolean"},"activeCot":{"type":"object","nullable":true},"correlationId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"409":{"description":"Conflict (e.g. patient already has active COT)"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/quick-plans":{"post":{"tags":["Quick plans"],"summary":"Create a quick plan with services","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","payorType","cotType","services"],"properties":{"name":{"type":"string"},"icon":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"payorType":{"type":"string","enum":["NHS","Private"]},"cotType":{"type":"string","enum":["existing","new"]},"services":{"type":"array","minItems":1,"items":{"type":"object"}}}}}}},"responses":{"201":{"description":"Created quick plan","content":{"application/json":{"schema":{"type":"object","properties":{"plan":{"$ref":"#/components/schemas/QuickPlan"},"correlationId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"409":{"description":"Conflict (e.g. patient already has active COT)"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/quick-plans/{planId}":{"get":{"tags":["Quick plans"],"summary":"Get quick plan by id","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"planId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Quick plan","content":{"application/json":{"schema":{"type":"object","properties":{"plan":{"$ref":"#/components/schemas/QuickPlan"},"correlationId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"409":{"description":"Conflict (e.g. patient already has active COT)"},"503":{"description":"Clinical org not linked or misconfigured"}}},"put":{"tags":["Quick plans"],"summary":"Update quick plan (replace services when provided)","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"planId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Updated quick plan","content":{"application/json":{"schema":{"type":"object","properties":{"plan":{"$ref":"#/components/schemas/QuickPlan"},"correlationId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"409":{"description":"Conflict (e.g. patient already has active COT)"},"503":{"description":"Clinical org not linked or misconfigured"}}},"delete":{"tags":["Quick plans"],"summary":"Delete quick plan","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"planId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"correlationId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"409":{"description":"Conflict (e.g. patient already has active COT)"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/quick-plans/{planId}/apply":{"post":{"tags":["Quick plans"],"summary":"Apply quick plan to a patient (creates COT, charting, treatment plans)","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"planId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["patientId"],"properties":{"patientId":{"type":"string","format":"uuid"},"cotId":{"type":"string","format":"uuid"},"toothSelections":{"type":"array","items":{"type":"object"}}}}}}},"responses":{"201":{"description":"Apply result"},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"409":{"description":"Conflict (e.g. patient already has active COT)"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/tasks":{"post":{"tags":["Tasks"],"summary":"Create task","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}}],"responses":{"201":{"description":"Task created"},"400":{"description":"Validation error"}}}},"/api/v1/organizations/{organizationId}/tasks/assigned-by-me":{"get":{"tags":["Tasks"],"summary":"List tasks assigned by me","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}}],"responses":{"200":{"description":"Tasks list"}}}},"/api/v1/organizations/{organizationId}/tasks/assigned-to-me":{"get":{"tags":["Tasks"],"summary":"List tasks assigned to me","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}}],"responses":{"200":{"description":"Tasks list"}}}},"/api/v1/organizations/{organizationId}/tasks/{taskId}":{"get":{"tags":["Tasks"],"summary":"Get task by id","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"taskId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Task details"},"404":{"description":"Task not found"}}},"put":{"tags":["Tasks"],"summary":"Update task","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"taskId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Task updated"}}},"delete":{"tags":["Tasks"],"summary":"Delete task","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"taskId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Task deleted"}}}},"/api/v1/organizations/{organizationId}/tasks/{taskId}/status":{"patch":{"tags":["Tasks"],"summary":"Update task status","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"taskId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Status updated"}}}},"/api/v1/organizations/{organizationId}/tasks/{taskId}/subtasks":{"post":{"tags":["Tasks"],"summary":"Create subtask","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"taskId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"201":{"description":"Subtask created"}}}},"/api/v1/organizations/{organizationId}/tasks/{taskId}/subtasks/{subtaskId}":{"patch":{"tags":["Tasks"],"summary":"Update subtask","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"taskId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"subtaskId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Subtask updated"}}},"delete":{"tags":["Tasks"],"summary":"Delete subtask","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"taskId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"subtaskId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Subtask deleted"}}}},"/api/v1/organizations/{organizationId}/organization-pricing/procedure-types":{"get":{"tags":["Organization pricing"],"summary":"Get valid procedure types and materials","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}}],"responses":{"200":{"description":"Procedure type metadata"}}}},"/api/v1/organizations/{organizationId}/organization-pricing/settings":{"get":{"tags":["Organization pricing"],"summary":"Get organization pricing settings","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}}],"responses":{"200":{"description":"Settings loaded"}}},"put":{"tags":["Organization pricing"],"summary":"Update organization pricing settings","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["currencyCode"],"properties":{"currencyCode":{"type":"string","example":"USD"}}}}}},"responses":{"200":{"description":"Settings updated"}}}},"/api/v1/organizations/{organizationId}/organization-pricing/procedures":{"get":{"tags":["Organization pricing"],"summary":"List organization procedure pricing","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"activeOnly","in":"query","required":false,"schema":{"type":"boolean","default":true}}],"responses":{"200":{"description":"Procedure pricing list"}}},"post":{"tags":["Organization pricing"],"summary":"Create or update procedure pricing in bulk","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["pricing"],"properties":{"pricing":{"type":"array","items":{"type":"object","required":["procedureType","price"],"properties":{"procedureType":{"type":"string"},"procedureMaterial":{"type":"string","nullable":true},"price":{"type":"number","minimum":0}}}}}}}}},"responses":{"201":{"description":"Procedure pricing updated"}}}},"/api/v1/organizations/{organizationId}/organization-pricing/procedure-price":{"get":{"tags":["Organization pricing"],"summary":"Get single procedure price","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"procedureType","in":"query","required":true,"schema":{"type":"string"}},{"name":"procedureMaterial","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Procedure price"},"404":{"description":"Not found"}}}},"/api/v1/organizations/{organizationId}/organization-pricing/procedures/{id}":{"delete":{"tags":["Organization pricing"],"summary":"Delete procedure pricing entry","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Pricing deleted"}}}},"/api/v1/organizations/{organizationId}/organization-pricing/currencies":{"get":{"tags":["Organization pricing"],"summary":"List supported currencies","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}}],"responses":{"200":{"description":"Currencies list"}}}},"/api/v1/organizations/{organizationId}/organization-pricing/preview-conversion":{"post":{"tags":["Organization pricing"],"summary":"Preview currency conversion","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["fromCurrency","toCurrency"],"properties":{"fromCurrency":{"type":"string","example":"USD"},"toCurrency":{"type":"string","example":"GBP"},"customRate":{"type":"number","nullable":true}}}}}},"responses":{"200":{"description":"Conversion preview"}}}},"/api/v1/organizations/{organizationId}/organization-pricing/convert-prices":{"post":{"tags":["Organization pricing"],"summary":"Convert organization prices to target currency","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["fromCurrency","toCurrency"],"properties":{"fromCurrency":{"type":"string","example":"USD"},"toCurrency":{"type":"string","example":"GBP"},"mode":{"type":"string","enum":["auto_convert","keep_values"]},"customRate":{"type":"number","nullable":true}}}}}},"responses":{"200":{"description":"Prices converted"}}}},"/api/v1/organizations/{organizationId}/organization-pricing/price-in-currency":{"get":{"tags":["Organization pricing"],"summary":"Get procedure price converted to target currency","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"procedureType","in":"query","required":true,"schema":{"type":"string"}},{"name":"procedureMaterial","in":"query","required":false,"schema":{"type":"string"}},{"name":"targetCurrency","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Converted price"}}}},"/api/v1/organizations/{organizationId}/organization-pricing/exchange-rates":{"get":{"tags":["Organization pricing"],"summary":"Get exchange rates by base currency","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"baseCurrency","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Exchange rates"}}}},"/api/v1/organizations/{organizationId}/organization-charting-procedure-types":{"get":{"tags":["Organization charting procedure types"],"summary":"List organization charting procedure types","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}}],"responses":{"200":{"description":"Procedure types list","content":{"application/json":{"schema":{"type":"object","required":["items","correlationId"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/OrganizationChartingProcedureType"}},"correlationId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"503":{"description":"Clinical org not linked or misconfigured"}}},"post":{"tags":["Organization charting procedure types"],"summary":"Create organization charting procedure type","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOrganizationChartingProcedureTypeBody"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","required":["item","correlationId"],"properties":{"item":{"$ref":"#/components/schemas/OrganizationChartingProcedureType"},"correlationId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/organization-charting-procedure-types/bulk":{"post":{"tags":["Organization charting procedure types"],"summary":"Create organization charting procedure types in bulk","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOrganizationChartingProcedureTypeBulkBody"}}}},"responses":{"201":{"description":"Bulk insert result","content":{"application/json":{"schema":{"type":"object","required":["inserted","attempted","correlationId"],"properties":{"inserted":{"type":"integer"},"attempted":{"type":"integer"},"correlationId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/organization-charting-procedure-types/{id}":{"patch":{"tags":["Organization charting procedure types"],"summary":"Update organization charting procedure type","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateOrganizationChartingProcedureTypeBody"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"type":"object","required":["item","correlationId"],"properties":{"item":{"$ref":"#/components/schemas/OrganizationChartingProcedureType"},"correlationId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"503":{"description":"Clinical org not linked or misconfigured"}}},"delete":{"tags":["Organization charting procedure types"],"summary":"Delete organization charting procedure type","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","required":["id","correlationId"],"properties":{"id":{"type":"string","format":"uuid"},"correlationId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/tooth-history/patient/{patientId}":{"get":{"tags":["Tooth history"],"summary":"Get unified patient tooth history timeline","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"patientId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1}},{"name":"sortBy","in":"query","required":false,"schema":{"type":"string","enum":["date","tooth","plan"]}},{"name":"toothNumber","in":"query","required":false,"schema":{"type":"string"}},{"name":"dateFrom","in":"query","required":false,"schema":{"type":"string","format":"date"}},{"name":"dateTo","in":"query","required":false,"schema":{"type":"string","format":"date"}},{"name":"showAll","in":"query","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"Unified history payload"},"404":{"description":"Patient not found"}}}},"/api/v1/organizations/{organizationId}/tooth-history/patient/{patientId}/tooth/{toothNumber}":{"get":{"tags":["Tooth history"],"summary":"Get history timeline for a specific tooth","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"patientId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"toothNumber","in":"path","required":true,"schema":{"type":"string","example":"UR1"}}],"responses":{"200":{"description":"Tooth-specific timeline"},"404":{"description":"Patient not found"}}}},"/api/v1/organizations/{organizationId}/doctor-chat/conversations":{"get":{"tags":["Doctor chat"],"summary":"List conversations for the current user","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}}],"responses":{"200":{"description":"Conversation list"}}},"post":{"tags":["Doctor chat"],"summary":"Create or fetch a conversation with another user","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["recipientUserId"],"properties":{"recipientUserId":{"type":"string","format":"uuid"}}}}}},"responses":{"201":{"description":"Conversation created or returned"},"400":{"description":"Validation error"},"403":{"description":"Recipient unavailable"}}}},"/api/v1/organizations/{organizationId}/doctor-chat/conversations/{conversationId}/messages":{"get":{"tags":["Doctor chat"],"summary":"List messages in a conversation","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"conversationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"before","in":"query","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"Messages list"},"404":{"description":"Not found"}}},"post":{"tags":["Doctor chat"],"summary":"Send a message in a conversation","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"conversationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["content"],"properties":{"content":{"type":"string","minLength":1}}}}}},"responses":{"201":{"description":"Message sent"},"400":{"description":"Validation error"},"404":{"description":"Conversation not found"}}}},"/api/v1/organizations/{organizationId}/doctor-chat/conversations/{conversationId}/read":{"patch":{"tags":["Doctor chat"],"summary":"Mark unread messages as read","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"conversationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Read receipts updated"},"404":{"description":"Not found"}}}},"/api/v1/organizations/{organizationId}/rbac/roles":{"get":{"tags":["RBAC"],"summary":"List organization roles","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}}],"responses":{"200":{"description":"Roles list"},"403":{"description":"Forbidden"}}},"post":{"tags":["RBAC"],"summary":"Create organization role","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}}],"responses":{"201":{"description":"Role created"},"409":{"description":"Conflict"}}}},"/api/v1/organizations/{organizationId}/rbac/permissions":{"get":{"tags":["RBAC"],"summary":"List all permissions","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}}],"responses":{"200":{"description":"Permissions list"}}}},"/api/v1/organizations/{organizationId}/rbac/roles/{roleId}/permissions":{"get":{"tags":["RBAC"],"summary":"Get permissions for a role","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"roleId","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Role permissions"}}},"post":{"tags":["RBAC"],"summary":"Assign permissions to a role","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"roleId","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Permissions assigned"}}},"put":{"tags":["RBAC"],"summary":"Replace all permissions for a role","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"roleId","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Permissions replaced"}}}},"/api/v1/organizations/{organizationId}/rbac/roles/{roleId}/permissions/{permissionId}/check":{"get":{"tags":["RBAC"],"summary":"Check whether a role has a permission","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"roleId","in":"path","required":true,"schema":{"type":"integer"}},{"name":"permissionId","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Permission check result"}}}},"/api/v1/organizations/{organizationId}/rbac/users/{userId}/roles":{"get":{"tags":["RBAC"],"summary":"List roles assigned to a clinical user","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"userId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"User roles"}}},"post":{"tags":["RBAC"],"summary":"Assign a role to a clinical user","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"userId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"201":{"description":"Role assigned"}}}},"/api/v1/organizations/{organizationId}/rbac/users/{userId}/roles/{roleId}":{"delete":{"tags":["RBAC"],"summary":"Remove a role from a clinical user","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"userId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"roleId","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Role removed"}}}},"/api/v1/organizations/{organizationId}/inbox/threads":{"get":{"tags":["Inbox"],"summary":"List inbox threads","parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","default":1}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":20}},{"name":"search","in":"query","required":false,"schema":{"type":"string"}},{"name":"status","in":"query","required":false,"schema":{"type":"string"}},{"name":"hasUnread","in":"query","required":false,"schema":{"type":"boolean"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"threads":{"type":"array","items":{"$ref":"#/components/schemas/InboxThreadItem"}},"pagination":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}}}}}}}}}}}},"/api/v1/organizations/{organizationId}/inbox/threads/{threadId}/messages":{"get":{"tags":["Inbox"],"summary":"Get thread messages","parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"threadId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"thread":{"$ref":"#/components/schemas/EmailThread"},"messages":{"type":"array","items":{"$ref":"#/components/schemas/EmailMessage"}}}}}}}}}}}},"/api/v1/organizations/{organizationId}/inbox/threads/{threadId}/reply":{"post":{"tags":["Inbox"],"summary":"Reply to a thread","parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"threadId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendReplyBody"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"$ref":"#/components/schemas/EmailMessage"}}}}}}}}},"/api/v1/organizations/{organizationId}/inbox/messages":{"post":{"tags":["Inbox"],"summary":"Send a new email message","parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewEmailBody"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"thread":{"$ref":"#/components/schemas/EmailThread"},"message":{"$ref":"#/components/schemas/EmailMessage"}}}}}}}}}}},"/api/v1/organizations/{organizationId}/session-recordings":{"post":{"tags":["Session recordings"],"summary":"Create a session recording and get a direct-upload target","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSessionRecordingBody"}}}},"responses":{"201":{"description":"Created — includes the worker upload URL and token","content":{"application/json":{"schema":{"type":"object","required":["recording","uploadToken","uploadUrl","correlationId"],"properties":{"recording":{"$ref":"#/components/schemas/SessionRecording"},"uploadToken":{"type":"string"},"uploadUrl":{"type":"string"},"correlationId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"409":{"description":"Invalid state transition"},"503":{"description":"Clinical org not linked or misconfigured"}}},"get":{"tags":["Session recordings"],"summary":"List session recordings for the organization","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"patientId","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","schema":{"type":"string","enum":["awaiting_upload","uploading","transcribing","ready","failed"]}}],"responses":{"200":{"description":"Recordings list with pagination","content":{"application/json":{"schema":{"type":"object","required":["recordings","pagination","correlationId"],"properties":{"recordings":{"type":"array","items":{"$ref":"#/components/schemas/SessionRecording"}},"pagination":{"$ref":"#/components/schemas/SessionRecordingsPagination"},"correlationId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"409":{"description":"Invalid state transition"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/session-recordings/{recordingId}":{"get":{"tags":["Session recordings"],"summary":"Get a session recording by id","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"recordingId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Recording","content":{"application/json":{"schema":{"type":"object","required":["recording","correlationId"],"properties":{"recording":{"$ref":"#/components/schemas/SessionRecording"},"correlationId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"409":{"description":"Invalid state transition"},"503":{"description":"Clinical org not linked or misconfigured"}}},"delete":{"tags":["Session recordings"],"summary":"Discard a session recording","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"recordingId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object","required":["id","correlationId"],"properties":{"id":{"type":"string","format":"uuid"},"correlationId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"409":{"description":"Invalid state transition"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/session-recordings/{recordingId}/complete":{"patch":{"tags":["Session recordings"],"summary":"Mark a recording's browser-side capture as complete","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"recordingId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompleteSessionRecordingBody"}}}},"responses":{"200":{"description":"Updated recording","content":{"application/json":{"schema":{"type":"object","required":["recording","correlationId"],"properties":{"recording":{"$ref":"#/components/schemas/SessionRecording"},"correlationId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"409":{"description":"Invalid state transition"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/session-recordings/{recordingId}/retry":{"post":{"tags":["Session recordings"],"summary":"Reset a failed recording so the browser can re-upload","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"recordingId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"New upload target","content":{"application/json":{"schema":{"type":"object","required":["recording","uploadToken","uploadUrl","correlationId"],"properties":{"recording":{"$ref":"#/components/schemas/SessionRecording"},"uploadToken":{"type":"string"},"uploadUrl":{"type":"string"},"correlationId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"409":{"description":"Invalid state transition"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/session-recordings/{recordingId}/transcript":{"get":{"tags":["Session recordings"],"summary":"Get the diarized transcript for a recording","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"recordingId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Transcript","content":{"application/json":{"schema":{"type":"object","required":["transcript","correlationId"],"properties":{"transcript":{"$ref":"#/components/schemas/SessionTranscript"},"correlationId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"409":{"description":"Invalid state transition"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/session-recordings/{recordingId}/transcript/speakers":{"patch":{"tags":["Session recordings"],"summary":"Confirm/correct which speaker is the clinician vs patient","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"recordingId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSpeakerRoleMapBody"}}}},"responses":{"200":{"description":"Updated transcript","content":{"application/json":{"schema":{"type":"object","required":["transcript","correlationId"],"properties":{"transcript":{"$ref":"#/components/schemas/SessionTranscript"},"correlationId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"409":{"description":"Invalid state transition"},"503":{"description":"Clinical org not linked or misconfigured"}}}},"/api/v1/organizations/{organizationId}/clinical-note-drafts/{draftId}/finalize":{"post":{"tags":["Clinical note drafts"],"summary":"Finalize a generated draft into a signed PatientNote","description":"Only the draft creator or an org admin may finalize. Stamps approvedBy/approvedAt and aiGenerated=true on the created note.","security":[{"bearerAuth":[]}],"parameters":[{"name":"organizationId","in":"path","required":true,"schema":{"type":"string","example":"org_acme_test"}},{"name":"draftId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FinalizeNoteDraftBody"}}}},"responses":{"201":{"description":"Created PatientNote","content":{"application/json":{"schema":{"type":"object","required":["note","correlationId"],"properties":{"note":{"$ref":"#/components/schemas/PatientNote"},"correlationId":{"type":"string"}}}}}},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"},"404":{"description":"Resource not found"},"409":{"description":"Draft already finalized"},"503":{"description":"Clinical org not linked or misconfigured"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT from POST /api/auth/login"}},"schemas":{"AuthUserProfile":{"type":"object","required":["id","email","name","avatarUrl","organizationId","role"],"properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string","format":"email"},"name":{"type":"string","nullable":true},"avatarUrl":{"type":"string","nullable":true},"organizationId":{"type":"string","nullable":true,"example":"org_acme_test"},"role":{"type":"string","example":"USER"}}},"LoginRequest":{"type":"object","required":["email","password"],"properties":{"email":{"type":"string","format":"email","example":"alice@example.com"},"password":{"type":"string","format":"password","maxLength":72,"example":"Password123!"},"organizationId":{"type":"string","description":"When set (org domain login), password login must be enabled for this organization and the user must belong to it.","example":"org_acme_test"}}},"LoginResponse":{"type":"object","required":["accessToken","user"],"properties":{"accessToken":{"type":"string","description":"JWT access token. Also set as an httpOnly session cookie."},"user":{"$ref":"#/components/schemas/AuthUserProfile"}}},"UpdateProfileRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"avatarUrl":{"oneOf":[{"type":"string","description":"HTTPS image URL or data:image/… base64 payload (max 512KB)."},{"type":"null"}]}}},"SamlExchangeRequest":{"type":"object","required":["code"],"properties":{"code":{"type":"string","minLength":16,"maxLength":128,"description":"One-time sign-in code issued after SAML ACS success."}}},"SamlExchangeResponse":{"type":"object","required":["user"],"properties":{"user":{"$ref":"#/components/schemas/AuthUserProfile"}},"description":"Sets an httpOnly session cookie. Does not return accessToken in the JSON body."},"DiscoverOrganizationRequest":{"type":"object","required":["domain"],"properties":{"domain":{"type":"string","maxLength":128,"example":"acme","description":"Organization login domain. Trimmed and lowercased; optional scheme/path segments are stripped."}}},"DiscoverOrganizationResponse":{"type":"object","required":["organizationId","organizationName","domain","passwordLoginEnabled","ssoEnabled","ldapEnabled","ssoOnly","ssoEntryUrl","samlSpEntityId","samlAcsUrl","correlationId"],"properties":{"organizationId":{"type":"string","example":"org_acme_test"},"organizationName":{"type":"string","example":"ACME Corp (test)"},"domain":{"type":"string","example":"acme"},"passwordLoginEnabled":{"type":"boolean"},"ssoEnabled":{"type":"boolean"},"ldapEnabled":{"type":"boolean"},"ssoOnly":{"type":"boolean"},"ssoEntryUrl":{"type":"string","nullable":true,"description":"IdP SSO URL when configured — browser may navigate here for SP-initiated login."},"samlSpEntityId":{"type":"string","nullable":true,"description":"SAML SP Entity ID / Audience (null when SSO is off)."},"samlAcsUrl":{"type":"string","nullable":true,"description":"ACS URL for IdP configuration (null when SSO is off)."},"correlationId":{"type":"string"}}},"ErrorMessage":{"type":"object","required":["message"],"properties":{"message":{"type":"string","example":"Invalid credentials"}}},"Appointment":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"doctorId":{"type":"string","format":"uuid"},"patientId":{"type":"string","format":"uuid","nullable":true},"appointmentType":{"type":"string","enum":["patient","staff-block"]},"startTime":{"type":"string","format":"date-time"},"endTime":{"type":"string","format":"date-time"},"date":{"type":"string","format":"date"},"status":{"type":"string","nullable":true},"blockReason":{"type":"string","nullable":true},"bookedBy":{"type":"string","format":"uuid","nullable":true},"organizationId":{"type":"string","format":"uuid","nullable":true},"priority":{"type":"string","enum":["low","medium","high"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"start_time":{"type":"string"},"end_time":{"type":"string"}}},"DoctorSchedule":{"type":"object","required":["id","doctorId","organizationId","scheduleType","dayOfWeek","startHour","startMinute","endHour","endMinute","startDate","endDate","unavailableStartTime","unavailableEndTime","reason","notes","isActive"],"properties":{"id":{"type":"string","format":"uuid"},"doctorId":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid","nullable":true},"scheduleType":{"type":"string","enum":["weekly","specific","unavailable"]},"dayOfWeek":{"type":"integer","nullable":true,"minimum":0,"maximum":6},"startHour":{"type":"integer","nullable":true,"minimum":0,"maximum":23},"startMinute":{"type":"integer","nullable":true,"minimum":0,"maximum":59},"endHour":{"type":"integer","nullable":true,"minimum":0,"maximum":23},"endMinute":{"type":"integer","nullable":true,"minimum":0,"maximum":59},"startDate":{"type":"string","format":"date","nullable":true},"endDate":{"type":"string","format":"date","nullable":true},"unavailableStartTime":{"type":"string","format":"date-time","nullable":true},"unavailableEndTime":{"type":"string","format":"date-time","nullable":true},"reason":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"isActive":{"type":"boolean"}}},"CreateDoctorScheduleBody":{"type":"object","required":["doctorId","scheduleType"],"properties":{"doctorId":{"type":"string","format":"uuid"},"scheduleType":{"type":"string","enum":["weekly","specific","unavailable"]},"dayOfWeek":{"type":"integer","minimum":0,"maximum":6},"startHour":{"type":"integer","minimum":0,"maximum":23},"startMinute":{"type":"integer","minimum":0,"maximum":59},"endHour":{"type":"integer","minimum":0,"maximum":23},"endMinute":{"type":"integer","minimum":0,"maximum":59},"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date"},"unavailableStartTime":{"type":"string","format":"date-time"},"unavailableEndTime":{"type":"string","format":"date-time"},"reason":{"type":"string"},"notes":{"type":"string"},"isActive":{"type":"boolean"}}},"UpdateDoctorScheduleBody":{"type":"object","properties":{"scheduleType":{"type":"string","enum":["weekly","specific","unavailable"]},"dayOfWeek":{"type":"integer","nullable":true,"minimum":0,"maximum":6},"startHour":{"type":"integer","nullable":true,"minimum":0,"maximum":23},"startMinute":{"type":"integer","nullable":true,"minimum":0,"maximum":59},"endHour":{"type":"integer","nullable":true,"minimum":0,"maximum":23},"endMinute":{"type":"integer","nullable":true,"minimum":0,"maximum":59},"startDate":{"type":"string","format":"date","nullable":true},"endDate":{"type":"string","format":"date","nullable":true},"unavailableStartTime":{"type":"string","format":"date-time","nullable":true},"unavailableEndTime":{"type":"string","format":"date-time","nullable":true},"reason":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"isActive":{"type":"boolean"}}},"Doctor":{"type":"object","required":["id","userId","name","avatar","specialist","employmentType","licenseNumber","yearsOfExperience","consultationFee","workingDays","createdAt"],"properties":{"id":{"type":"string","format":"uuid"},"userId":{"type":"string","format":"uuid"},"name":{"type":"string","nullable":true},"avatar":{"type":"string","nullable":true},"specialist":{"type":"string"},"employmentType":{"type":"string"},"licenseNumber":{"type":"string","nullable":true},"yearsOfExperience":{"type":"integer","nullable":true},"consultationFee":{"type":"number","nullable":true},"workingDays":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time"}}},"DoctorsListResponse":{"type":"object","required":["doctors"],"properties":{"doctors":{"type":"array","items":{"$ref":"#/components/schemas/Doctor"}},"correlationId":{"type":"string"}}},"ClinicRoom":{"type":"object","required":["id","organizationId","name","status","sortOrder","isActive","notes","createdAt","updatedAt"],"properties":{"id":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"name":{"type":"string"},"status":{"type":"string","enum":["vacant","inuse","unavailable"]},"sortOrder":{"type":"integer"},"isActive":{"type":"boolean"},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"CreateClinicRoomBody":{"type":"object","required":["name"],"properties":{"name":{"type":"string","minLength":1,"maxLength":120},"status":{"type":"string","enum":["vacant","inuse","unavailable"]},"sortOrder":{"type":"integer"},"notes":{"type":"string","nullable":true},"isActive":{"type":"boolean"}}},"CreateClinicRoomBulkBody":{"type":"object","required":["items"],"properties":{"items":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/CreateClinicRoomBody"}}}},"UpdateClinicRoomBody":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"status":{"type":"string","enum":["vacant","inuse","unavailable"]},"sortOrder":{"type":"integer"},"notes":{"type":"string","nullable":true},"isActive":{"type":"boolean"}}},"FamilyMember":{"type":"object","properties":{"patientId":{"type":"string","format":"uuid"},"referenceNumber":{"type":"string"},"fullName":{"type":"string"},"dateOfBirth":{"type":"string","format":"date"},"shareAccounts":{"type":"boolean"},"isCurrentPatient":{"type":"boolean"},"linkedAt":{"type":"string","format":"date-time"}}},"LinkFamilyMemberBody":{"type":"object","required":["relatedPatientId"],"properties":{"relatedPatientId":{"type":"string","format":"uuid"},"shareAccounts":{"type":"boolean"}}},"UpdateFamilyMemberBody":{"type":"object","required":["shareAccounts"],"properties":{"shareAccounts":{"type":"boolean"}}},"FamilyBookingBody":{"type":"object","required":["doctorId","date","startTime","durationMinutes","patientIds"],"properties":{"doctorId":{"type":"string","format":"uuid"},"date":{"type":"string"},"startTime":{"type":"string"},"durationMinutes":{"type":"integer"},"patientIds":{"type":"array","items":{"type":"string","format":"uuid"}},"reason":{"type":"string"},"notes":{"type":"string"},"priority":{"type":"string","enum":["low","medium","high"]}}},"CreateShortNoticeEntryBody":{"type":"object","required":["sourceAppointmentId"],"properties":{"sourceAppointmentId":{"type":"string","format":"uuid"},"doctorId":{"type":"string","format":"uuid"},"isHighPriority":{"type":"boolean"}}},"ShortNoticeSummary":{"type":"object","properties":{"patientsOnList":{"type":"integer"},"totalSlots":{"type":"integer"},"slotsReadyToFill":{"type":"integer"},"lookaheadDays":{"type":"integer"}}},"Site":{"type":"object","required":["id","name","code","status","createdAt","effectiveTimezone","effectiveLanguage"],"properties":{"id":{"type":"string","example":"cmqqdljlo00077knkz8vgr66b"},"name":{"type":"string","example":"New York Clinic"},"code":{"type":"string","example":"NYC-01"},"logoUrl":{"type":"string","nullable":true},"address":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"location":{"type":"string","nullable":true},"timezone":{"type":"string","nullable":true,"example":"UTC+09:00"},"language":{"type":"string","nullable":true,"example":"en"},"effectiveTimezone":{"type":"string","nullable":true,"example":"UTC+09:00"},"effectiveLanguage":{"type":"string","nullable":true,"example":"en"},"status":{"type":"string","enum":["ACTIVE","INACTIVE"]},"accessLevel":{"type":"string","enum":["VIEW","MANAGE","ADMIN"],"nullable":true},"createdAt":{"type":"string","format":"date-time"}}},"CreateSiteBody":{"type":"object","required":["name","code"],"properties":{"name":{"type":"string","example":"New York Clinic"},"code":{"type":"string","example":"NYC-01"},"logoUrl":{"type":"string","nullable":true},"address":{"type":"string"},"phone":{"type":"string"},"location":{"type":"string"},"timezone":{"type":"string","example":"UTC+09:00"},"language":{"type":"string","example":"en"}}},"UpdateSiteBody":{"type":"object","properties":{"name":{"type":"string","example":"New York Clinic"},"status":{"type":"string","enum":["ACTIVE","INACTIVE"]},"logoUrl":{"type":"string","nullable":true},"address":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"location":{"type":"string","nullable":true},"timezone":{"type":"string","nullable":true,"example":"UTC+09:00"},"language":{"type":"string","nullable":true,"example":"en"}}},"SiteAccessLevel":{"type":"object","properties":{"value":{"type":"string","enum":["VIEW","MANAGE","ADMIN"]},"label":{"type":"string"},"description":{"type":"string"},"permissions":{"type":"array","items":{"type":"string"}}}},"RecallVisit":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"date":{"type":"string","format":"date-time"},"visitType":{"type":"string"},"procedureType":{"type":"string","nullable":true},"toothNumber":{"type":"string","nullable":true},"surface":{"type":"string","nullable":true},"provider":{"type":"string"},"service":{"type":"string"},"notes":{"type":"string","nullable":true},"status":{"type":"string","enum":["Completed","Planned"]},"cotTitle":{"type":"string","nullable":true},"cotStatus":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time","nullable":true}}},"CreateRecallVisitBody":{"type":"object","required":["visitType"],"properties":{"visitType":{"type":"string","enum":["procedure","consultation","examination","cleaning","follow_up","check_up"]},"toothNumber":{"type":"string"},"procedureType":{"type":"string"},"procedureMaterial":{"type":"string"},"surface":{"type":"string"},"notes":{"type":"string"},"provider":{"type":"string","description":"Optional clinical staff user id (UUID) or auth user id (resolved server-side)."},"planDate":{"type":"string","format":"date"},"visitDate":{"type":"string","format":"date"},"cotId":{"type":"string","format":"uuid"},"createdBy":{"type":"string","description":"Optional legacy clinical staff user id (UUID). When omitted or not found, the server resolves the acting clinical user."}}},"CorrelationId":{"type":"object","properties":{"correlationId":{"type":"string","format":"uuid","description":"Request correlation id (v1 routes)."}}},"PatientListItem":{"type":"object","required":["id","referenceNumber","fullName","gender","dateOfBirth","createdAt"],"properties":{"id":{"type":"string","format":"uuid"},"referenceNumber":{"type":"string","example":"P-A1B2C3D4"},"fullName":{"type":"string","example":"Jane Doe"},"gender":{"type":"string","enum":["male","female","other"]},"dateOfBirth":{"type":"string","format":"date","example":"1985-06-20"},"phoneNumber":{"type":"string","nullable":true},"email":{"type":"string","format":"email","nullable":true},"profileImageUrl":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"organizationId":{"type":"string","format":"uuid","nullable":true}}},"PatientDetail":{"allOf":[{"$ref":"#/components/schemas/PatientListItem"},{"type":"object","properties":{"address":{"type":"string","nullable":true},"age":{"type":"integer","nullable":true},"homePhone":{"type":"string","nullable":true},"postalCode":{"type":"string","nullable":true},"altReferenceNumber":{"type":"string","nullable":true},"payor":{"type":"string","enum":["nhs","private","insurance","other"],"nullable":true},"nhsNumber":{"type":"string","nullable":true}}}]},"CreatePatientBody":{"type":"object","required":["fullName","gender","dateOfBirth"],"properties":{"fullName":{"type":"string","minLength":1},"gender":{"type":"string","enum":["male","female","other"]},"dateOfBirth":{"type":"string","description":"ISO date string parseable by Date.parse","example":"1985-06-20"},"phoneNumber":{"type":"string"},"email":{"type":"string","format":"email"},"address":{"type":"string"},"age":{"oneOf":[{"type":"integer"},{"type":"string"}]},"homePhone":{"type":"string"},"postalCode":{"type":"string"},"altReferenceNumber":{"type":"string"},"payor":{"type":"string","enum":["nhs","private","insurance","other"]},"nhsNumber":{"type":"string","description":"Required when payor is nhs"}}},"UpdatePatientBody":{"type":"object","minProperties":1,"description":"At least one field required. NHS number required when setting payor to nhs.","properties":{"fullName":{"type":"string","minLength":1},"gender":{"type":"string","enum":["male","female","other"]},"dateOfBirth":{"type":"string"},"phoneNumber":{"type":"string"},"email":{"type":"string","format":"email"},"address":{"type":"string"},"age":{"oneOf":[{"type":"integer"},{"type":"string"}]},"homePhone":{"type":"string"},"postalCode":{"type":"string"},"altReferenceNumber":{"type":"string"},"payor":{"type":"string","enum":["nhs","private","insurance","other"]},"nhsNumber":{"type":"string"},"profileImageUrl":{"type":"string","nullable":true}}},"PatientListResponse":{"allOf":[{"type":"object","required":["patients"],"properties":{"patients":{"type":"array","items":{"$ref":"#/components/schemas/PatientListItem"}}}},{"$ref":"#/components/schemas/CorrelationId"}]},"PatientDetailResponse":{"allOf":[{"type":"object","required":["patient"],"properties":{"patient":{"$ref":"#/components/schemas/PatientDetail"}}},{"$ref":"#/components/schemas/CorrelationId"}]},"PatientDeleteResponse":{"allOf":[{"type":"object","required":["id"],"properties":{"id":{"type":"string","format":"uuid"}}},{"$ref":"#/components/schemas/CorrelationId"}]},"PatientNote":{"type":"object","required":["id","patientId","title","content","noteType","isPrivate","createdBy","createdAt","updatedAt","doNotPopup"],"properties":{"id":{"type":"string","format":"uuid"},"patientId":{"type":"string","format":"uuid"},"title":{"type":"string"},"content":{"type":"string"},"noteType":{"type":"string","example":"general"},"isPrivate":{"type":"boolean"},"createdBy":{"type":"string","format":"uuid"},"createdAt":{"type":"string","format":"date-time","nullable":true},"updatedAt":{"type":"string","format":"date-time","nullable":true},"doNotPopup":{"type":"boolean","nullable":true}}},"PatientNotesPagination":{"type":"object","required":["page","limit","total","totalPages"],"properties":{"page":{"type":"integer","minimum":1},"limit":{"type":"integer","minimum":1},"total":{"type":"integer","minimum":0},"totalPages":{"type":"integer","minimum":0}}},"PatientNoteStats":{"type":"object","required":["totalNotes","byType","byPrivacy"],"properties":{"totalNotes":{"type":"integer","minimum":0},"byType":{"type":"object","additionalProperties":{"type":"integer","minimum":0}},"byPrivacy":{"type":"object","required":["public","private"],"properties":{"public":{"type":"integer","minimum":0},"private":{"type":"integer","minimum":0}}}}},"CreatePatientNoteBody":{"type":"object","required":["patientId","title","content"],"properties":{"patientId":{"type":"string","format":"uuid"},"title":{"type":"string"},"content":{"type":"string"},"noteType":{"type":"string","default":"general"},"isPrivate":{"type":"boolean","default":false},"doNotPopup":{"type":"boolean","default":false}}},"UpdatePatientNoteBody":{"type":"object","properties":{"title":{"type":"string"},"content":{"type":"string"},"noteType":{"type":"string"},"isPrivate":{"type":"boolean"}}},"PatchPatientNotePopupBody":{"type":"object","required":["doNotPopup"],"properties":{"doNotPopup":{"type":"boolean"}}},"NoteTemplateCreator":{"type":"object","required":["id","fullName"],"properties":{"id":{"type":"string","format":"uuid"},"fullName":{"type":"string","nullable":true}}},"NoteTemplate":{"type":"object","required":["id","title","content","category","siteId","isShared","isActive","jsonContent","schemaVersion","createdBy","organizationId","createdAt","updatedAt","createdByUser"],"properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"content":{"type":"string","description":"Human-readable scaffold. Derived from jsonContent when present — never parsed back."},"category":{"type":"string","nullable":true},"siteId":{"type":"string"},"isShared":{"type":"boolean"},"isActive":{"type":"boolean"},"jsonContent":{"type":"object","nullable":true,"description":"Structured section/field definition (see @repo/note-templates). NULL is a permanent supported state — legacy plain-text template."},"schemaVersion":{"type":"integer"},"createdBy":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"createdAt":{"type":"string","format":"date-time","nullable":true},"updatedAt":{"type":"string","format":"date-time","nullable":true},"createdByUser":{"oneOf":[{"$ref":"#/components/schemas/NoteTemplateCreator"},{"type":"null"}]}}},"NoteTemplatesPagination":{"type":"object","required":["page","limit","total","totalPages"],"properties":{"page":{"type":"integer","minimum":1},"limit":{"type":"integer","minimum":1},"total":{"type":"integer","minimum":0},"totalPages":{"type":"integer","minimum":0}}},"CreateNoteTemplateBody":{"type":"object","required":["title","siteId"],"description":"content is required unless jsonContent is provided (content is then derived server-side).","properties":{"title":{"type":"string"},"content":{"type":"string"},"category":{"type":"string","nullable":true},"siteId":{"type":"string"},"isShared":{"type":"boolean","default":true},"isActive":{"type":"boolean","default":true},"jsonContent":{"type":"object"}}},"UpdateNoteTemplateBody":{"type":"object","properties":{"title":{"type":"string"},"content":{"type":"string"},"category":{"type":"string","nullable":true},"siteId":{"type":"string"},"isShared":{"type":"boolean"},"isActive":{"type":"boolean"},"jsonContent":{"type":"object"}}},"GenerateNoteBody":{"type":"object","required":["patientId"],"description":"Either transcript or recordingId is required.","properties":{"patientId":{"type":"string","format":"uuid"},"transcript":{"type":"string","maxLength":60000},"recordingId":{"type":"string","format":"uuid"},"appointmentId":{"type":"string","format":"uuid"},"cotId":{"type":"string","format":"uuid"}}},"GenerateNoteWarning":{"type":"object","required":["code","sectionKey","fieldKey","message"],"properties":{"code":{"type":"string"},"sectionKey":{"type":"string"},"fieldKey":{"type":"string"},"message":{"type":"string"}}},"ClinicalNoteDraft":{"type":"object","required":["id","patientId","organizationId","templateId","templateVersion","recordingId","appointmentId","cotId","values","renderedContent","suggestedTitle","status","model","usage","warnings","createdBy","finalizedNoteId","createdAt","updatedAt"],"properties":{"id":{"type":"string","format":"uuid"},"patientId":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"templateId":{"type":"string","format":"uuid","nullable":true},"templateVersion":{"type":"integer","nullable":true},"recordingId":{"type":"string","format":"uuid","nullable":true},"appointmentId":{"type":"string","format":"uuid","nullable":true},"cotId":{"type":"string","format":"uuid","nullable":true},"values":{"type":"object","nullable":true},"renderedContent":{"type":"string","nullable":true},"suggestedTitle":{"type":"string"},"status":{"type":"string","enum":["generating","generated","failed","finalized","discarded"]},"model":{"type":"string","nullable":true},"usage":{"type":"object","nullable":true},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/GenerateNoteWarning"}},"createdBy":{"type":"string","format":"uuid"},"finalizedNoteId":{"type":"string","format":"uuid","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"EmailTemplate":{"type":"object","required":["id","organizationId","name","version","subject","htmlPath","htmlContent","jsonContent","isActive","createdBy","createdAt","updatedAt"],"properties":{"id":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"name":{"type":"string"},"version":{"type":"string"},"subject":{"type":"string","nullable":true},"htmlPath":{"type":"string"},"htmlContent":{"type":"string","nullable":true},"jsonContent":{"description":"Raw drag-and-drop editor JSON used to edit the template.","nullable":true},"isActive":{"type":"boolean"},"createdBy":{"type":"string","format":"uuid","nullable":true},"createdAt":{"type":"string","format":"date-time","nullable":true},"updatedAt":{"type":"string","format":"date-time","nullable":true}}},"UploadEmailTemplateBody":{"type":"object","required":["templateName","htmlContent"],"properties":{"templateName":{"type":"string"},"version":{"type":"string","default":"v1"},"subject":{"type":"string"},"htmlContent":{"type":"string"},"jsonContent":{"description":"Raw drag-and-drop editor JSON used to edit the template."},"isActive":{"type":"boolean","default":true}}},"UpdateEmailTemplateBody":{"type":"object","properties":{"subject":{"type":"string"},"htmlContent":{"type":"string"},"jsonContent":{"description":"Raw drag-and-drop editor JSON used to edit the template. Send null to clear it.","nullable":true},"isActive":{"type":"boolean"}}},"PatientImageUploadResponse":{"type":"object","required":["url","path","correlationId"],"properties":{"url":{"type":"string","format":"uri"},"path":{"type":"string"},"correlationId":{"type":"string"}}},"PatientImagesListResponse":{"type":"object","required":["images","correlationId"],"properties":{"images":{"type":"array","items":{"type":"string","format":"uri"}},"correlationId":{"type":"string"}}},"SignConsentFormsResponse":{"type":"object","required":["success","message","mode","recipient","formsProcessed","correlationId"],"properties":{"success":{"type":"boolean"},"message":{"type":"string"},"mode":{"type":"string","enum":["pdf","link"]},"recipient":{"type":"string","format":"email"},"formsProcessed":{"type":"array","items":{"type":"object","properties":{"formName":{"type":"string"},"token":{"type":"string"},"formNamePath":{"type":"string","nullable":true},"success":{"type":"boolean"}}}},"links":{"type":"array","nullable":true,"items":{"type":"object","properties":{"formName":{"type":"string"},"link":{"type":"string"},"token":{"type":"string"}}}},"correlationId":{"type":"string"}}},"MultiFormsDownloadResponse":{"type":"object","required":["success","message","patientName","organizationName","forms","totalForms","successfulForms","correlationId"],"properties":{"success":{"type":"boolean"},"message":{"type":"string"},"patientName":{"type":"string"},"organizationName":{"type":"string"},"forms":{"type":"array","items":{"type":"object"}},"totalForms":{"type":"integer"},"successfulForms":{"type":"integer"},"correlationId":{"type":"string"}}},"ResendConsentFormResponse":{"type":"object","required":["message","email","formTitle","token","link","expirationExtended","pdfGenerated","correlationId"],"properties":{"message":{"type":"string"},"email":{"type":"string","format":"email"},"formTitle":{"type":"string"},"token":{"type":"string"},"link":{"type":"string"},"expirationExtended":{"type":"boolean"},"pdfGenerated":{"type":"boolean"},"correlationId":{"type":"string"}}},"ConsentFormViewResponse":{"type":"object","required":["success","formId","token","form","correlationId"],"properties":{"success":{"type":"boolean"},"formId":{"type":"string","format":"uuid"},"patientId":{"type":"string","format":"uuid","nullable":true},"organizationId":{"type":"string","format":"uuid","nullable":true},"token":{"type":"string"},"form":{"type":"object"},"correlationId":{"type":"string"}}},"UploadConsentFormResponse":{"type":"object","required":["success","message","data","correlationId"],"properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"type":"object"},"correlationId":{"type":"string"}}},"ConsentFormsStatusResponse":{"type":"object","required":["success","message","forms","totalCount","correlationId"],"properties":{"success":{"type":"boolean"},"message":{"type":"string"},"forms":{"type":"array","items":{"type":"object"}},"totalCount":{"type":"integer"},"correlationId":{"type":"string"}}},"PatientAppointment":{"type":"object","required":["id","doctorId","patientId","appointmentType","startTime","endTime","date","status","priority","bookedBy","durationMinutes","createdAt","updatedAt"],"properties":{"id":{"type":"string","format":"uuid"},"doctorId":{"type":"string","format":"uuid"},"patientId":{"type":"string","format":"uuid"},"appointmentType":{"type":"string","example":"consultation"},"startTime":{"type":"string","description":"Clinic-local naive datetime (yyyy-MM-ddTHH:mm:ss)"},"endTime":{"type":"string"},"date":{"type":"string","format":"date"},"status":{"type":"string","enum":["pending","confirmed","arrived","in_surgery","completed","did_not_attend","cancelled"]},"reason":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"priority":{"type":"string","enum":["low","medium","high"]},"bookedBy":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid","nullable":true},"durationMinutes":{"type":"integer"},"labWorkStatus":{"type":"string","nullable":true},"roomId":{"type":"string","format":"uuid","nullable":true},"cotId":{"type":"string","format":"uuid","nullable":true},"treatmentPlanId":{"type":"string","format":"uuid","nullable":true},"visitId":{"type":"string","format":"uuid","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"doctor":{"type":"object","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"specialist":{"type":"string"},"fullName":{"type":"string","nullable":true},"avatarUrl":{"type":"string","nullable":true}}},"patient":{"type":"object","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"fullName":{"type":"string"},"email":{"type":"string","nullable":true},"phoneNumber":{"type":"string","nullable":true}}}}},"AvailableSlot":{"type":"object","required":["startTime","endTime","available"],"properties":{"startTime":{"type":"string","description":"UTC slot start (yyyy-MM-ddTHH:mm:ss)"},"endTime":{"type":"string"},"available":{"type":"boolean"}}},"AvailableSlotsResponse":{"type":"object","required":["date","doctorId","durationMinutes","availableSlots","allSlots","correlationId"],"properties":{"date":{"type":"string","format":"date"},"doctorId":{"type":"string","format":"uuid"},"durationMinutes":{"type":"integer"},"availableSlots":{"type":"array","items":{"$ref":"#/components/schemas/AvailableSlot"}},"allSlots":{"type":"array","items":{"$ref":"#/components/schemas/AvailableSlot"}},"message":{"type":"string"},"correlationId":{"type":"string"}}},"WaitingAppointmentItem":{"type":"object","required":["id","patientId","doctorId","startTime","endTime","status","scheduleIndicator","scheduleDelayMinutes","startsInMinutes","isWaiting"],"properties":{"id":{"type":"string","format":"uuid"},"patientId":{"type":"string","format":"uuid"},"doctorId":{"type":"string","format":"uuid"},"patientName":{"type":"string","nullable":true},"doctorName":{"type":"string","nullable":true},"startTime":{"type":"string"},"endTime":{"type":"string"},"status":{"type":"string"},"reason":{"type":"string","nullable":true},"scheduleIndicator":{"type":"string","enum":["upcoming","on_time_window","late","very_late","completed_or_cancelled"]},"scheduleDelayMinutes":{"type":"integer"},"startsInMinutes":{"type":"integer"},"isWaiting":{"type":"boolean"}}},"WaitingListResponse":{"type":"object","required":["waiting","total","correlationId"],"properties":{"waiting":{"type":"array","items":{"$ref":"#/components/schemas/WaitingAppointmentItem"}},"total":{"type":"integer"},"correlationId":{"type":"string"}}},"PatchLabWorkBody":{"type":"object","required":["labWorkStatus"],"properties":{"labWorkStatus":{"type":"string","enum":["sent","received","overdue","none_required"]}}},"LabWorkPatchResult":{"type":"object","required":["id","labWorkApplicable","labWorkStatus"],"properties":{"id":{"type":"string","format":"uuid"},"labWorkApplicable":{"type":"boolean"},"labWorkStatus":{"type":"string","nullable":true,"enum":["sent","received","overdue","none_required"]}}},"ProcedurePairAppointmentSide":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"start_time":{"type":"string"},"end_time":{"type":"string"},"date":{"type":"string","format":"date"},"status":{"type":"string"},"reason":{"type":"string","nullable":true},"visit_id":{"type":"string","format":"uuid","nullable":true}}},"ProcedurePrepFitPair":{"type":"object","description":"Prep/fit pairing metadata (snake_case fields match legacy clinical API).","properties":{"pair_id":{"type":"string","format":"uuid"},"procedure_key":{"type":"string"},"my_role":{"type":"string","enum":["prep","fit"]},"prep_appointment_id":{"type":"string","format":"uuid"},"fit_appointment_id":{"type":"string","format":"uuid"},"prep":{"$ref":"#/components/schemas/ProcedurePairAppointmentSide"},"fit":{"$ref":"#/components/schemas/ProcedurePairAppointmentSide"}}},"CreatePatientAppointmentBody":{"type":"object","required":["doctorId","patientId","date","startTime"],"properties":{"doctorId":{"type":"string","format":"uuid"},"patientId":{"type":"string","format":"uuid"},"date":{"type":"string","format":"date","example":"2026-06-01"},"startTime":{"type":"string","example":"09:00:00","description":"Local clinic time or ISO datetime"},"endTime":{"type":"string","example":"09:30:00","description":"Required for consultations. For COT bookings, omit when duration is provided."},"reason":{"type":"string"},"notes":{"type":"string"},"priority":{"type":"string","enum":["low","medium","high"]},"cotId":{"type":"string","format":"uuid","description":"Course of treatment id (COT booking)"},"treatmentPlanId":{"type":"string","format":"uuid","description":"Required with cotId for COT bookings"},"visitId":{"type":"string","format":"uuid","description":"Treatment plan visit (prep side for auto pairing)"},"duration":{"type":"integer","description":"Minutes from startTime; may replace endTime for COT bookings"},"fitDate":{"type":"string","format":"date"},"fitStartTime":{"type":"string"},"fitEndTime":{"type":"string"},"fitDuration":{"type":"integer"}}},"CreatePatientAppointmentResponse":{"type":"object","required":["appointment","correlationId"],"properties":{"appointment":{"$ref":"#/components/schemas/PatientAppointment"},"pairedAppointment":{"$ref":"#/components/schemas/PatientAppointment","description":"Present when prep+fit auto-pairing created two bookings"},"prepFitPair":{"$ref":"#/components/schemas/ProcedurePrepFitPair"},"correlationId":{"type":"string"}}},"UpdatePatientAppointmentBody":{"type":"object","description":"Reschedule (date+startTime+endTime) and/or status-only update. cancellationReason required when status is cancelled.","properties":{"doctorId":{"type":"string","format":"uuid"},"patientId":{"type":"string","format":"uuid"},"date":{"type":"string","format":"date"},"startTime":{"type":"string"},"endTime":{"type":"string"},"reason":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"priority":{"type":"string","enum":["low","medium","high"]},"status":{"type":"string","enum":["pending","confirmed","arrived","in_surgery","completed","did_not_attend","cancelled"]},"cancellationReason":{"type":"string"}}},"MedicalHistoryRecord":{"type":"object","required":["id","patientId","createdBy","formData","lastUpdated","isCurrent","createdAt","updatedAt"],"properties":{"id":{"type":"string","format":"uuid"},"patientId":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid","nullable":true},"createdBy":{"type":"string","format":"uuid"},"createdByName":{"type":"string","nullable":true},"formData":{"type":"object","additionalProperties":true},"lastUpdated":{"type":"string","format":"date-time"},"isCurrent":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"deletedAt":{"type":"string","format":"date-time","nullable":true}}},"MedicalHistoryPatientInfo":{"type":"object","required":["id","name","medicalHistoryUpdated"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"lastMedicalUpdate":{"type":"string","format":"date-time","nullable":true},"medicalHistoryUpdated":{"type":"boolean"}}},"MedicalHistorySummary":{"type":"object","required":["hasMedicalHistory","lastUpdated","keyAlerts","allergies","medications","conditionsCount"],"properties":{"hasMedicalHistory":{"type":"boolean"},"lastUpdated":{"type":"string","format":"date-time","nullable":true},"keyAlerts":{"type":"array","items":{"type":"string"}},"allergies":{"type":"array","items":{"type":"string"}},"medications":{"type":"array","items":{"type":"string"}},"conditionsCount":{"type":"integer"}}},"PaletteResponse":{"type":"object","properties":{"palette":{"type":"array","items":{"type":"string"}},"availableProcedures":{"type":"array","items":{"type":"string"}},"paletteScope":{"type":"string","enum":["base","treatment"]}}},"CourseOfTreatment":{"type":"object","required":["id","patientId","title","status","payor","totalCost","createdBy"],"properties":{"id":{"type":"string","format":"uuid"},"patientId":{"type":"string","format":"uuid"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"status":{"type":"string","enum":["Open","Completed","Archived"]},"payor":{"type":"string","enum":["NHS","Private"]},"nhsTreatmentType":{"type":"string","enum":["Band 1","Band 2","Band 3","Band 4","Band 5"],"nullable":true},"totalCost":{"type":"number"},"createdBy":{"type":"string","format":"uuid"},"completedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time","nullable":true},"updatedAt":{"type":"string","format":"date-time","nullable":true},"organizationId":{"type":"string","format":"uuid","nullable":true}}},"CotBrief":{"type":"object","required":["id","patientId","title","status"],"properties":{"id":{"type":"string","format":"uuid"},"patientId":{"type":"string","format":"uuid"},"title":{"type":"string"},"status":{"type":"string"}}},"CreateCourseOfTreatmentBody":{"type":"object","required":["patientId","title","payor","createdBy"],"properties":{"patientId":{"type":"string","format":"uuid"},"title":{"type":"string"},"description":{"type":"string"},"payor":{"type":"string","enum":["NHS","Private"]},"nhsTreatmentType":{"type":"string","enum":["Band 1","Band 2","Band 3","Band 4","Band 5"],"description":"Required when payor is NHS"},"createdBy":{"type":"string","format":"uuid","description":"Clinical user id (legacy booked-by / creator)"}}},"UpdateCourseOfTreatmentBody":{"type":"object","description":"At least one field required","properties":{"title":{"type":"string"},"description":{"type":"string","nullable":true},"status":{"type":"string","enum":["Open","Completed","Archived"]},"payor":{"type":"string","enum":["NHS","Private"]},"nhsTreatmentType":{"type":"string","enum":["Band 1","Band 2","Band 3","Band 4","Band 5"],"nullable":true},"totalCost":{"type":"number","minimum":0}}},"PatchCotStatusBody":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["Open","Completed","Archived"]}}},"ActiveCotsSummary":{"type":"object","required":["totalActiveCots","nhsCots","privateCots","multiplePrivateAllowed","nhsSingleDentistRule"],"properties":{"totalActiveCots":{"type":"integer"},"nhsCots":{"type":"integer"},"privateCots":{"type":"integer"},"multiplePrivateAllowed":{"type":"boolean"},"nhsSingleDentistRule":{"type":"boolean"}}},"CotChartingSummary":{"type":"object","required":["id"],"properties":{"id":{"type":"string","format":"uuid"},"toothNumber":{"type":"string","nullable":true},"procedureType":{"type":"string","nullable":true},"surface":{"type":"string","nullable":true},"durationMinutes":{"type":"integer","nullable":true},"notes":{"type":"string","nullable":true},"planDate":{"type":"string","format":"date","nullable":true},"visitDate":{"type":"string","format":"date","nullable":true},"createdAt":{"type":"string","format":"date-time","nullable":true},"visitType":{"type":"string","nullable":true},"patientId":{"type":"string","format":"uuid","nullable":true}}},"TreatmentPlan":{"type":"object","required":["id","cotId","treatmentOrder","estimatedCost","status"],"properties":{"id":{"type":"string","format":"uuid"},"cotId":{"type":"string","format":"uuid"},"chartingId":{"type":"string","format":"uuid","nullable":true},"treatmentOrder":{"type":"integer"},"estimatedCost":{"type":"number"},"status":{"type":"string","enum":["Planned","In Progress","Completed","Cancelled"]},"notes":{"type":"string","nullable":true},"nhsBand":{"type":"string","enum":["Band 1","Band 2","Band 3","Band 4","Band 5"],"nullable":true},"createdAt":{"type":"string","format":"date-time","nullable":true},"updatedAt":{"type":"string","format":"date-time","nullable":true}}},"VisitProgressionItem":{"type":"object","required":["visitOrder","charting","status"],"properties":{"visitOrder":{"type":"integer"},"status":{"type":"string"},"charting":{"$ref":"#/components/schemas/CotChartingSummary"}}},"VisitProgression":{"type":"object","required":["totalVisits","completedVisits","visits"],"properties":{"totalVisits":{"type":"integer"},"completedVisits":{"type":"integer"},"nextVisit":{"type":"integer","nullable":true},"visits":{"type":"array","items":{"$ref":"#/components/schemas/VisitProgressionItem"}}}},"TreatmentPlanWithVisits":{"allOf":[{"$ref":"#/components/schemas/TreatmentPlan"},{"type":"object","required":["visitProgression"],"properties":{"primaryCharting":{"$ref":"#/components/schemas/CotChartingSummary","nullable":true},"linkedChartings":{"type":"array","items":{"$ref":"#/components/schemas/CotChartingSummary"}},"visitProgression":{"$ref":"#/components/schemas/VisitProgression"}}}]},"TreatmentsListSummary":{"type":"object","required":["totalTreatments","treatmentsByStatus","multiVisitSummary"],"properties":{"totalTreatments":{"type":"integer"},"treatmentsByStatus":{"type":"object","additionalProperties":{"type":"integer"}},"multiVisitSummary":{"type":"object","properties":{"totalMultiVisitTreatments":{"type":"integer"},"totalVisitsAcrossAllTreatments":{"type":"integer"},"completedVisits":{"type":"integer"}}}}},"CreateTreatmentPlanBody":{"type":"object","required":["chartingId","estimatedCost"],"properties":{"chartingId":{"type":"string","format":"uuid"},"estimatedCost":{"type":"number","minimum":0},"notes":{"type":"string"}}},"UpdateTreatmentPlanBody":{"type":"object","description":"At least one field required","properties":{"estimatedCost":{"type":"number","minimum":0},"status":{"type":"string","enum":["Planned","In Progress","Completed","Cancelled"]},"notes":{"type":"string","nullable":true}}},"PatchNhsBandBody":{"type":"object","required":["nhsBand"],"properties":{"nhsBand":{"type":"string","enum":["Band 1","Band 2","Band 3","Band 4","Band 5"]},"notes":{"type":"string"}}},"LinkChartingsBody":{"type":"object","required":["chartingIds"],"properties":{"chartingIds":{"type":"array","minItems":1,"items":{"type":"string","format":"uuid"}}}},"TreatmentPlanChartingLink":{"type":"object","required":["id","treatmentPlanId","chartingId","visitOrder","status"],"properties":{"id":{"type":"string","format":"uuid"},"treatmentPlanId":{"type":"string","format":"uuid"},"chartingId":{"type":"string","format":"uuid"},"visitOrder":{"type":"integer"},"status":{"type":"string","enum":["pending","completed","cancelled"]},"createdAt":{"type":"string","format":"date-time","nullable":true},"updatedAt":{"type":"string","format":"date-time","nullable":true}}},"CotVisit":{"type":"object","required":["id","treatmentPlanId","chartingId","visitOrder","status","treatment","visitSummary"],"properties":{"id":{"type":"string","format":"uuid"},"treatmentPlanId":{"type":"string","format":"uuid"},"chartingId":{"type":"string","format":"uuid"},"visitOrder":{"type":"integer"},"status":{"type":"string","enum":["pending","completed","cancelled"]},"createdAt":{"type":"string","format":"date-time","nullable":true},"updatedAt":{"type":"string","format":"date-time","nullable":true},"treatment":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"treatmentOrder":{"type":"integer"},"estimatedCost":{"type":"number"},"status":{"type":"string"},"notes":{"type":"string","nullable":true}}},"charting":{"$ref":"#/components/schemas/CotChartingSummary","nullable":true},"visitSummary":{"type":"object","properties":{"isPrimaryVisit":{"type":"boolean"},"isFollowUp":{"type":"boolean"},"needsAppointment":{"type":"boolean"},"isScheduled":{"type":"boolean"},"isCompleted":{"type":"boolean"},"isCancelled":{"type":"boolean"}}}}},"PatchVisitStatusBody":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["pending","completed","cancelled"]},"notes":{"type":"string"}}},"CotAppointmentListItem":{"type":"object","required":["id","doctorId","patientId","bookedBy","appointmentType","startTime","endTime","date","status","priority","durationMinutes"],"properties":{"id":{"type":"string","format":"uuid"},"doctorId":{"type":"string","format":"uuid"},"patientId":{"type":"string","format":"uuid"},"bookedBy":{"type":"string","format":"uuid"},"appointmentType":{"type":"string","example":"cot_treatment"},"startTime":{"type":"string"},"endTime":{"type":"string"},"date":{"type":"string","format":"date"},"status":{"type":"string"},"reason":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"priority":{"type":"string"},"durationMinutes":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"organizationId":{"type":"string","format":"uuid","nullable":true},"cotId":{"type":"string","format":"uuid","nullable":true},"treatmentPlanId":{"type":"string","format":"uuid","nullable":true},"visitId":{"type":"string","format":"uuid","nullable":true},"treatmentPlan":{"type":"object","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"estimatedCost":{"type":"number"},"status":{"type":"string"},"charting":{"$ref":"#/components/schemas/CotChartingSummary","nullable":true}}},"visit":{"type":"object","nullable":true,"properties":{"id":{"type":"string","format":"uuid"},"visitOrder":{"type":"integer"},"status":{"type":"string"},"charting":{"$ref":"#/components/schemas/CotChartingSummary","nullable":true}}}}},"CotTreatmentSlot":{"type":"object","required":["startTime","endTime","durationMinutes"],"properties":{"startTime":{"type":"string","example":"09:00:00"},"endTime":{"type":"string","example":"09:30:00"},"durationMinutes":{"type":"integer"}}},"Charting":{"type":"object","required":["id","patientId","visitType","toothNumber","surface","procedureType","procedureMaterial","durationMinutes","notes","createdBy","provider","planDate","visitDate","cotId","isBaseCharting","organizationId","providerFullName"],"properties":{"id":{"type":"string","format":"uuid"},"patientId":{"type":"string","format":"uuid"},"visitType":{"type":"string","enum":["procedure","consultation","examination","cleaning","follow_up","check_up"]},"toothNumber":{"type":"string","nullable":true,"example":"UR1"},"surface":{"type":"string","enum":["top","bottom","left","right","center","center_left","center_right","whole_tooth"],"nullable":true},"procedureType":{"type":"string","nullable":true,"example":"Crown"},"procedureMaterial":{"type":"string","nullable":true},"durationMinutes":{"type":"integer","nullable":true},"notes":{"type":"string","nullable":true},"createdBy":{"type":"string","format":"uuid","nullable":true},"provider":{"type":"string","format":"uuid","nullable":true},"planDate":{"type":"string","format":"date","nullable":true,"description":"YYYY-MM-DD"},"visitDate":{"type":"string","format":"date","nullable":true,"description":"YYYY-MM-DD"},"cotId":{"type":"string","format":"uuid","nullable":true},"isBaseCharting":{"type":"boolean"},"organizationId":{"type":"string","format":"uuid","nullable":true},"providerFullName":{"type":"string","nullable":true}}},"ChartingTreatmentPlanInfo":{"type":"object","required":["id","treatmentOrder","estimatedCost","status","nhsBand","autoCreated","action"],"properties":{"id":{"type":"string","format":"uuid"},"treatmentOrder":{"type":"integer"},"estimatedCost":{"type":"number"},"status":{"type":"string"},"nhsBand":{"type":"string","enum":["Band 1","Band 2","Band 3","Band 4","Band 5"],"nullable":true},"autoCreated":{"type":"boolean"},"action":{"type":"string","enum":["created","linked_visit"]}}},"ChartingCotInfo":{"type":"object","required":["cotId","autoAssigned","message"],"properties":{"cotId":{"type":"string","format":"uuid"},"autoAssigned":{"type":"boolean"},"message":{"type":"string"}}},"CreateChartingBody":{"type":"object","required":["patientId","visitType","createdBy"],"properties":{"patientId":{"type":"string","format":"uuid"},"visitType":{"type":"string","enum":["procedure","consultation","examination","cleaning","follow_up","check_up"]},"createdBy":{"type":"string","format":"uuid","description":"Clinical user id"},"toothNumber":{"type":"string","description":"Required for procedure visits (e.g. UR1)"},"procedureType":{"type":"string","description":"Required for procedure visits (e.g. Crown)"},"procedureMaterial":{"type":"string","description":"Required for Crown, Filling, Root Canal"},"surface":{"type":"string","enum":["top","bottom","left","right","center","center_left","center_right","whole_tooth"]},"durationMinutes":{"type":"integer","minimum":1,"maximum":480},"notes":{"type":"string"},"provider":{"type":"string","format":"uuid"},"planDate":{"type":"string","format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"visitDate":{"type":"string","format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"cotId":{"type":"string","format":"uuid","description":"Optional; auto-assigns patient's open COT when omitted"},"isBaseCharting":{"type":"boolean","description":"When true, skips treatment plan auto-create/link"}}},"PatchChartingBody":{"type":"object","description":"At least one field required","properties":{"notes":{"type":"string","nullable":true},"planDate":{"type":"string","format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"visitDate":{"type":"string","format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"provider":{"type":"string","format":"uuid","nullable":true},"status":{"type":"string","enum":["pending","completed","cancelled"],"description":"Updates treatment-plan visit status; completes plan when all visits are completed"}}},"CheckDuplicateChartingBody":{"$ref":"#/components/schemas/CreateChartingBody"},"CheckDuplicateChartingResult":{"type":"object","required":["isDuplicate","isExactDuplicate","existingCount","existingEntries"],"properties":{"isDuplicate":{"type":"boolean"},"isExactDuplicate":{"type":"boolean"},"existingCount":{"type":"integer"},"existingEntries":{"type":"array","items":{"type":"object","required":["id","notes","visitDate","planDate"],"properties":{"id":{"type":"string","format":"uuid"},"notes":{"type":"string","nullable":true},"visitDate":{"type":"string","format":"date","nullable":true},"planDate":{"type":"string","format":"date","nullable":true}}}}}},"RecentCheckupResult":{"type":"object","required":["hasRecentCheckup","recentCheckup"],"properties":{"hasRecentCheckup":{"type":"boolean"},"recentCheckup":{"type":"object","nullable":true,"required":["id","visitType","visitDate","planDate"],"properties":{"id":{"type":"string","format":"uuid"},"visitType":{"type":"string"},"visitDate":{"type":"string","format":"date","nullable":true},"planDate":{"type":"string","format":"date","nullable":true}}}}},"CreateChartingResult":{"type":"object","required":["charting","treatmentPlan","cotInfo","warning","duplicateSkipped"],"properties":{"charting":{"$ref":"#/components/schemas/Charting","nullable":true,"description":"Null when duplicateSkipped is true"},"treatmentPlan":{"$ref":"#/components/schemas/ChartingTreatmentPlanInfo","nullable":true},"cotInfo":{"$ref":"#/components/schemas/ChartingCotInfo","nullable":true},"warning":{"type":"object","nullable":true,"description":"Similar procedure entries on same tooth/surface","properties":{"type":{"type":"string","example":"similar_entries"},"message":{"type":"string"},"existingEntries":{"type":"array","items":{"type":"object"}}}},"duplicateSkipped":{"type":"boolean"}}},"PerioMeasurement":{"type":"object","required":["id","chartingId","toothNumber","pocketDepth","recession","mobility","bleeding","plaque","suppuration","furcationGrade","notes"],"properties":{"id":{"type":"string","format":"uuid"},"chartingId":{"type":"string","format":"uuid","nullable":true},"toothNumber":{"type":"string","nullable":true,"example":"UR1"},"pocketDepth":{"type":"array","items":{"type":"integer"}},"recession":{"type":"array","items":{"type":"integer"}},"mobility":{"type":"array","items":{"type":"integer"}},"bleeding":{"type":"array","items":{"type":"boolean"}},"plaque":{"type":"array","items":{"type":"boolean"}},"suppuration":{"type":"array","items":{"type":"boolean"}},"furcationGrade":{"type":"integer","minimum":0,"maximum":3,"nullable":true},"notes":{"type":"string","nullable":true}}},"BpeAssessment":{"type":"object","required":["id","perioChartId","patientId","assessmentDate","sextantScores","bleeding","stage","grade","stability","diagnosisStatement","notes"],"properties":{"id":{"type":"string","format":"uuid"},"perioChartId":{"type":"string","format":"uuid"},"patientId":{"type":"string","format":"uuid"},"assessmentDate":{"type":"string","format":"date"},"sextantScores":{"type":"array","minItems":6,"maxItems":6,"items":{"type":"integer","minimum":0,"maximum":4}},"bleeding":{"type":"array","minItems":6,"maxItems":6,"items":{"type":"boolean"}},"stage":{"type":"string","enum":["N/A","Gingivitis","1","2","3","4"],"nullable":true},"grade":{"type":"string","enum":["N/A","A","B","C"],"nullable":true},"stability":{"type":"string","enum":["N/A","Currently Stable","Currently in Remission","Currently Unstable"],"nullable":true},"diagnosisStatement":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true}}},"PerioChart":{"type":"object","required":["id","patientId","cotId","chartTitle","chartDate","chartType","notes","version","isCurrent","createdBy","createdByName","measurements","bpeAssessment"],"properties":{"id":{"type":"string","format":"uuid"},"patientId":{"type":"string","format":"uuid"},"cotId":{"type":"string","format":"uuid","nullable":true},"chartTitle":{"type":"string"},"chartDate":{"type":"string","format":"date"},"chartType":{"type":"string","enum":["full","partial","bpe"],"nullable":true},"notes":{"type":"string","nullable":true},"version":{"type":"integer","nullable":true},"isCurrent":{"type":"boolean","nullable":true},"createdBy":{"type":"string","format":"uuid"},"createdByName":{"type":"string","nullable":true},"measurements":{"type":"array","items":{"$ref":"#/components/schemas/PerioMeasurement"}},"bpeAssessment":{"$ref":"#/components/schemas/BpeAssessment","nullable":true}}},"CreatePerioChartBody":{"type":"object","required":["patientId","chartTitle","chartDate","chartType"],"properties":{"patientId":{"type":"string","format":"uuid"},"cotId":{"type":"string","format":"uuid"},"chartTitle":{"type":"string","minLength":1},"chartDate":{"type":"string","format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"chartType":{"type":"string","enum":["full","partial","bpe"]},"notes":{"type":"string","nullable":true},"measurements":{"type":"array","items":{"$ref":"#/components/schemas/CreatePerioMeasurementBody"}}}},"UpdatePerioChartBody":{"type":"object","properties":{"chartTitle":{"type":"string","minLength":1},"chartDate":{"type":"string","format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"notes":{"type":"string","nullable":true},"measurements":{"type":"array","items":{"$ref":"#/components/schemas/CreatePerioMeasurementBody"}}}},"CreatePerioMeasurementBody":{"type":"object","properties":{"chartingId":{"type":"string","format":"uuid"},"toothNumber":{"type":"string","example":"UR1"},"pocketDepth":{"type":"array","minItems":6,"maxItems":6,"items":{"type":"integer"}},"recession":{"type":"array","minItems":6,"maxItems":6,"items":{"type":"integer"}},"mobility":{"type":"array","minItems":6,"maxItems":6,"items":{"type":"integer"}},"bleeding":{"type":"array","minItems":6,"maxItems":6,"items":{"type":"boolean"}},"plaque":{"type":"array","minItems":6,"maxItems":6,"items":{"type":"boolean"}},"suppuration":{"type":"array","minItems":6,"maxItems":6,"items":{"type":"boolean"}},"furcationGrade":{"type":"integer","minimum":0,"maximum":3,"nullable":true},"notes":{"type":"string","nullable":true}},"description":"Either chartingId or toothNumber is required."},"CreateBpeBody":{"type":"object","required":["assessmentDate","sextantScores"],"properties":{"assessmentDate":{"type":"string","format":"date","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"sextantScores":{"type":"array","minItems":6,"maxItems":6,"items":{"type":"integer","minimum":0,"maximum":4}},"bleeding":{"type":"array","minItems":6,"maxItems":6,"items":{"type":"boolean"}},"stage":{"type":"string","enum":["N/A","Gingivitis","1","2","3","4"],"nullable":true},"grade":{"type":"string","enum":["N/A","A","B","C"],"nullable":true},"stability":{"type":"string","enum":["N/A","Currently Stable","Currently in Remission","Currently Unstable"],"nullable":true},"notes":{"type":"string","nullable":true}}},"AcceptAiRecommendationsBody":{"type":"object","properties":{"aiAnalysis":{"type":"object","additionalProperties":true,"description":"Optional externally prepared AI analysis payload."}}},"QuickPlanService":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"quickPlanId":{"type":"string","format":"uuid"},"serviceType":{"type":"string"},"procedureType":{"type":"string","nullable":true},"procedureMaterial":{"type":"string","nullable":true},"durationMinutes":{"type":"integer","nullable":true},"estimatedCost":{"type":"number"},"serviceOrder":{"type":"integer"},"requiresToothSelection":{"type":"boolean"}}},"QuickPlan":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"providerId":{"type":"string","format":"uuid"},"name":{"type":"string"},"icon":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"payorType":{"type":"string","enum":["NHS","Private"]},"cotType":{"type":"string","enum":["existing","new"]},"isActive":{"type":"boolean"},"services":{"type":"array","items":{"$ref":"#/components/schemas/QuickPlanService"}}}},"Task":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"task":{"type":"string"},"priority":{"type":"string","enum":["Low","Medium","High"]},"status":{"type":"string","enum":["Pending","In Progress","Done","Overdue"]},"dueDate":{"type":"string","format":"date"},"description":{"type":"string","nullable":true},"patientId":{"type":"string","format":"uuid"},"assignedTo":{"type":"string","format":"uuid"},"assignedBy":{"type":"string","format":"uuid"}}},"TaskSubtask":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"taskId":{"type":"string","format":"uuid"},"title":{"type":"string"},"notes":{"type":"string","nullable":true},"completed":{"type":"boolean"},"orderIndex":{"type":"integer"}}},"Currency":{"type":"object","properties":{"code":{"type":"string","example":"USD"},"name":{"type":"string","nullable":true,"example":"US Dollar"},"symbol":{"type":"string","nullable":true,"example":"$"}}},"OrganizationPricingSettings":{"type":"object","properties":{"id":{"type":"string"},"organizationId":{"type":"string","format":"uuid"},"currencyCode":{"type":"string","example":"USD"},"currency":{"$ref":"#/components/schemas/Currency"},"createdAt":{"type":"string","format":"date-time","nullable":true},"updatedAt":{"type":"string","format":"date-time","nullable":true}}},"ProcedurePricing":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"procedureType":{"type":"string","example":"Crown"},"procedureMaterial":{"type":"string","nullable":true,"example":"Gold Crown"},"price":{"type":"number","example":500},"currencyCode":{"type":"string","example":"USD"},"isActive":{"type":"boolean"},"createdBy":{"type":"string","format":"uuid","nullable":true},"createdAt":{"type":"string","format":"date-time","nullable":true},"updatedAt":{"type":"string","format":"date-time","nullable":true},"originalCurrency":{"type":"string","nullable":true},"originalPrice":{"type":"number","nullable":true}}},"OrganizationChartingProcedureType":{"type":"object","required":["id","organizationId","name","chartingLevel","sortOrder","isActive","createdAt","updatedAt"],"properties":{"id":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid","nullable":true},"name":{"type":"string"},"chartingLevel":{"type":"string","enum":["tooth_surface","tooth","patient"],"nullable":true},"sortOrder":{"type":"integer"},"isActive":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time","nullable":true},"updatedAt":{"type":"string","format":"date-time","nullable":true}}},"CreateOrganizationChartingProcedureTypeBody":{"type":"object","required":["name"],"properties":{"name":{"type":"string","minLength":1,"maxLength":255},"chartingLevel":{"type":"string","enum":["tooth_surface","tooth","patient"],"nullable":true},"sortOrder":{"type":"integer"}}},"CreateOrganizationChartingProcedureTypeBulkBody":{"type":"object","required":["items"],"properties":{"items":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/CreateOrganizationChartingProcedureTypeBody"}}}},"UpdateOrganizationChartingProcedureTypeBody":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255},"chartingLevel":{"type":"string","enum":["tooth_surface","tooth","patient"],"nullable":true},"sortOrder":{"type":"integer"},"isActive":{"type":"boolean"}}},"ToothHistoryEntry":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["charting","note","course_of_treatment","appointment"]},"date":{"type":"string","format":"date-time"},"provider":{"type":"string"},"cotId":{"type":"string","format":"uuid","nullable":true},"toothNumber":{"type":"string","nullable":true},"particulars":{"type":"string"},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"rawData":{"type":"object","additionalProperties":true}}},"ToothSpecificEntry":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["charting","note"]},"date":{"type":"string","format":"date-time"},"provider":{"type":"string"},"cotId":{"type":"string","format":"uuid","nullable":true},"procedureType":{"type":"string","nullable":true},"surface":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"rawData":{"type":"object","additionalProperties":true}}},"DoctorChatParticipant":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"fullName":{"type":"string","nullable":true},"avatarUrl":{"type":"string","nullable":true}}},"DoctorChatConversationListItem":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"participant":{"$ref":"#/components/schemas/DoctorChatParticipant"},"updatedAt":{"type":"string","format":"date-time","nullable":true},"lastMessage":{"type":"object","nullable":true},"unreadCount":{"type":"integer"}}},"DoctorChatMessage":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"conversationId":{"type":"string","format":"uuid"},"senderId":{"type":"string","format":"uuid"},"content":{"type":"string"},"createdAt":{"type":"string","format":"date-time","nullable":true},"readAt":{"type":"string","format":"date-time","nullable":true},"readBy":{"type":"string","format":"uuid","nullable":true},"sender":{"$ref":"#/components/schemas/DoctorChatParticipant"}}},"RbacRole":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"isActive":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time","nullable":true},"updatedAt":{"type":"string","format":"date-time","nullable":true}}},"RbacPermission":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"resource":{"type":"string"},"action":{"type":"string"}}},"EmailMessage":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"threadId":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"patientId":{"type":"string","format":"uuid","nullable":true},"direction":{"type":"string","enum":["inbound","outbound"]},"fromEmail":{"type":"string","format":"email"},"toEmail":{"type":"string","format":"email"},"subject":{"type":"string","nullable":true},"bodyText":{"type":"string","nullable":true},"bodyHtml":{"type":"string","nullable":true},"status":{"type":"string"},"receivedAt":{"type":"string","format":"date-time","nullable":true},"sentAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}}},"EmailThread":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"patientId":{"type":"string","format":"uuid","nullable":true},"subject":{"type":"string","nullable":true},"status":{"type":"string"},"lastMessageAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"InboxThreadItem":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"patientId":{"type":"string","format":"uuid","nullable":true},"subject":{"type":"string"},"status":{"type":"string"},"lastMessageAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"lastMessagePreview":{"type":"string"},"latestFromEmail":{"type":"string","nullable":true},"latestToEmail":{"type":"string","nullable":true},"unreadCount":{"type":"integer"},"hasUnread":{"type":"boolean"}}},"NewEmailBody":{"type":"object","required":["recipientEmail","subject","body"],"properties":{"patientId":{"type":"string","format":"uuid","nullable":true},"recipientEmail":{"type":"string","format":"email"},"subject":{"type":"string","minLength":1},"body":{"type":"string","minLength":1}}},"SendReplyBody":{"type":"object","required":["body"],"properties":{"body":{"type":"string","minLength":1},"subject":{"type":"string"}}},"SessionRecording":{"type":"object","required":["id","organizationId","siteId","patientId","appointmentId","createdBy","status","durationMs","consentObtained","consentMethod","startedAt","endedAt","error","retryCount","createdAt","updatedAt"],"properties":{"id":{"type":"string","format":"uuid"},"organizationId":{"type":"string","format":"uuid"},"siteId":{"type":"string","nullable":true},"patientId":{"type":"string","format":"uuid"},"appointmentId":{"type":"string","format":"uuid","nullable":true},"createdBy":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["awaiting_upload","uploading","transcribing","ready","failed"]},"durationMs":{"type":"integer","nullable":true},"consentObtained":{"type":"boolean"},"consentMethod":{"type":"string","nullable":true},"startedAt":{"type":"string","format":"date-time","nullable":true},"endedAt":{"type":"string","format":"date-time","nullable":true},"error":{"type":"string","nullable":true},"retryCount":{"type":"integer"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"SessionRecordingsPagination":{"type":"object","required":["page","limit","total","totalPages"],"properties":{"page":{"type":"integer","minimum":1},"limit":{"type":"integer","minimum":1},"total":{"type":"integer","minimum":0},"totalPages":{"type":"integer","minimum":0}}},"SessionUtterance":{"type":"object","required":["idx","speaker","role","startMs","endMs","text"],"properties":{"idx":{"type":"integer"},"speaker":{"type":"string"},"role":{"type":"string","enum":["clinician","patient","unknown"]},"startMs":{"type":"integer"},"endMs":{"type":"integer"},"text":{"type":"string"},"confidence":{"type":"number","nullable":true}}},"SessionTranscript":{"type":"object","required":["id","recordingId","provider","model","language","text","utterances","speakerRoleMap","avgConfidence","createdAt"],"properties":{"id":{"type":"string","format":"uuid"},"recordingId":{"type":"string","format":"uuid"},"provider":{"type":"string"},"model":{"type":"string","nullable":true},"language":{"type":"string","nullable":true},"text":{"type":"string"},"utterances":{"type":"array","items":{"$ref":"#/components/schemas/SessionUtterance"}},"speakerRoleMap":{"type":"object","nullable":true,"additionalProperties":{"type":"string","enum":["clinician","patient","unknown"]}},"avgConfidence":{"type":"number","nullable":true},"createdAt":{"type":"string","format":"date-time"}}},"CreateSessionRecordingBody":{"type":"object","required":["patientId","consentObtained","consentMethod"],"properties":{"patientId":{"type":"string","format":"uuid"},"appointmentId":{"type":"string","format":"uuid"},"consentObtained":{"type":"boolean","description":"Must be true — request is rejected otherwise."},"consentMethod":{"type":"string","enum":["verbal","written"]}}},"CompleteSessionRecordingBody":{"type":"object","required":["durationMs","endedAt"],"properties":{"durationMs":{"type":"integer","minimum":0},"endedAt":{"type":"string","format":"date-time"}}},"UpdateSpeakerRoleMapBody":{"type":"object","required":["speakerRoleMap"],"properties":{"speakerRoleMap":{"type":"object","additionalProperties":{"type":"string","enum":["clinician","patient","unknown"]}}}},"FinalizeNoteDraftBody":{"type":"object","required":["title","content","attestation"],"description":"Rejected when attestation is not true — the clinician must confirm they reviewed the AI-drafted note.","properties":{"title":{"type":"string"},"content":{"type":"string"},"values":{"type":"object"},"noteType":{"type":"string","default":"general"},"isPrivate":{"type":"boolean","default":false},"attestation":{"type":"boolean"}}}}}}