Skip to main content

OdontoX API Reference

Generated from source: server/src/routes/ + server/src/lib/permissions.ts
Last updated: 2026-05-09
Base URL: https://api.odontox.io/api/v1

Role Hierarchy

RoleScopeDescription
superadminPlatformAnthropic-level god mode. Bypasses all permission checks. Manages clinics, licenses, and impersonation.
adminClinicClinic owner/manager. Gets full plan-tier permissions. Template/per-user overrides do NOT apply (prevents accidental lockout).
doctorClinicClinical practitioner. Full clinical access + billing. IPD and Bridge are plan-gated.
receptionistClinicFront-desk staff. Appointment + patient + billing access. No write access to clinical notes or dental charts.
patientSelfPortal user. Read-only access to their own data. Can accept treatment plans, view invoices, send messages.

Permission Resolution Layers (non-admin roles)

Plan-tier defaults  →  Clinic role template  →  Per-user override  →  Role floor (cannot be revoked)
  • Pro plan: base permission set (no IPD, no Bridge for doctors; reduced AI for receptionists)
  • Pro+ / Enterprise: full permission set including inventory write for receptionist, full AI suite

Permission Key Reference

Each key maps to a named requirePermission(key) call in the route handlers. The role columns show which roles have this permission by default at the stated plan tier. Admins always get all plan-tier permissions. Legend: = granted by default · P = Pro only · PP = Pro+ / Enterprise only · - = not granted

Appointments (10 keys)

Permission KeyWhat it controlsDoctorReceptionistPatientPlan
appointments.viewSee appointment list and calendar✓ (own)Pro
appointments.view_detailOpen a specific appointment’s detail page✓ (own)Pro
appointments.createBook a new appointment-Pro
appointments.editChange time, doctor, notes on an existing appointment-Pro
appointments.deleteCancel and remove an appointment-Pro
appointments.change_statusMove through lifecycle: confirmed → arrived → in-chair → completed-Pro
appointments.send_summaryEmail/WhatsApp the appointment summary to the patient-Pro
appointments.view_all_doctorsSee appointments belonging to other doctors (not just own schedule)-Pro
appointments.block_timeMark a slot as blocked / holiday so it can’t be booked--Pro
appointments.exportDownload appointment list as CSV/PDF---Admin only
Floor: appointments.view + appointments.view_detail are irrevocable for both doctor and receptionist — these are the minimum required to practice or operate the front desk.

Patients (9 keys)

Permission KeyWhat it controlsDoctorReceptionistPatientPlan
patients.viewSee patient list and search-Pro
patients.view_detailOpen a patient’s full profile✓ (own)Pro
patients.createRegister a new patient-Pro
patients.editUpdate patient demographics and contact info-Pro
patients.deletePermanently delete a patient record--Pro
patients.invite_portalSend a patient portal invite email-Pro
patients.view_medical_historyRead medical history, allergies, and conditions-Pro
patients.exportDownload patient list as CSV---Admin only
patients.mergeMerge duplicate patient records---Admin only
Floor: patients.view + patients.view_detail are irrevocable for doctor and receptionist.

Clinical — Dental Chart (4 keys)

Permission KeyWhat it controlsDoctorReceptionistPatientPlan
clinical.dental_chart.viewView tooth chart with status colors-✓ (own)Pro
clinical.dental_chart.createAdd a new chart record for a patient--Pro
clinical.dental_chart.editUpdate tooth conditions, treatments, notes--Pro
clinical.dental_chart.initializeSet up a brand-new full-mouth chart for a patient--Pro
Receptionists have no chart write access — clinical integrity must remain with the treating clinician.

Clinical — Notes (4 keys)

Permission KeyWhat it controlsDoctorReceptionistPatientPlan
clinical.notes.viewRead SOAP/clinical notes for a patient-✓ (own)Pro
clinical.notes.createWrite a new clinical note (SOAP, AI-assisted, free-text)--Pro
clinical.notes.editEdit a previously written note--Pro
clinical.notes.deleteDelete a clinical note--Pro
Floor: clinical.notes.view + clinical.notes.create are irrevocable for doctors. Receptionists intentionally cannot read notes — protects clinical confidentiality from front-desk staff.

Clinical — Treatment Plans (10 keys)

Permission KeyWhat it controlsDoctorReceptionistPatientPlan
clinical.treatment_plans.viewRead treatment plans✓ (own)Pro
clinical.treatment_plans.createDraft a new treatment plan--Pro
clinical.treatment_plans.editModify procedures, pricing, timeline--Pro
clinical.treatment_plans.deleteRemove a plan entirely--Pro
clinical.treatment_plans.completeMark a plan as fully delivered--Pro
clinical.treatment_plans.approveDoctor approves plan before presenting to patient--Pro
clinical.treatment_plans.acceptPatient accepts a presented plan--Pro
clinical.treatment_plans.ai_presentationGenerate AI patient-friendly summary of the plan--Pro
clinical.treatment_plans.shareCreate a public share link for the patient to view--Pro
clinical.treatment_plans.revoke_shareRevoke a previously shared link--Pro
Receptionists can view plans (to assist with billing) but cannot create or modify them.
Permission KeyWhat it controlsDoctorReceptionistPatientPlan
clinical.vital_signs.viewRead recorded vitals (BP, pulse, weight)--Pro
clinical.vital_signs.recordEnter/update vitals for a visit--Pro
clinical.consent.viewView signed consent forms✓ (own)Pro
clinical.consent.uploadUpload a signed consent PDF-Pro

Clinical — Prescriptions (5 keys)

Permission KeyWhat it controlsDoctorReceptionistPatientPlan
clinical.prescriptions.viewRead prescriptions✓ (own)Pro
clinical.prescriptions.createIssue a new prescription--Pro
clinical.prescriptions.editAmend a prescription--Pro
clinical.prescriptions.deleteVoid a prescription--Pro
clinical.prescriptions.manage_templateEdit the clinic’s prescription letterhead template--Pro
Floor: clinical.prescriptions.view + clinical.prescriptions.create are irrevocable for doctors.

Clinical — Medications Library (3 keys)

Permission KeyWhat it controlsDoctorReceptionistPatientPlan
clinical.medications.viewBrowse the clinic’s medication catalog--Pro
clinical.medications.createAdd a medication to the catalog--Pro
clinical.medications.deleteRemove a medication from the catalog--Pro

Clinical — Procedures Catalog (4 keys)

Permission KeyWhat it controlsDoctorReceptionistPatientPlan
clinical.procedures.viewBrowse the procedure catalog (used in treatment plans)--Pro
clinical.procedures.createAdd a new procedure with pricing--Pro
clinical.procedures.editEdit procedure name, code, or price--Pro
clinical.procedures.deleteRemove a procedure from the catalog--Pro
Floor: clinical.procedures.view is irrevocable for doctors — required to create treatment plans.

Clinical — Patient Files (4 keys)

Permission KeyWhat it controlsDoctorReceptionistPatientPlan
clinical.patient_files.viewBrowse uploaded files (X-rays, documents, DICOM)✓ (own)Pro
clinical.patient_files.uploadUpload new files to a patient’s record-Pro
clinical.patient_files.editRename or re-categorize a file--Pro
clinical.patient_files.deletePermanently delete a patient file--Pro
Floor: clinical.patient_files.view is irrevocable for doctors.

Clinical — Recalls (5 keys)

Permission KeyWhat it controlsDoctorReceptionistPatientPlan
clinical.recalls.viewSee recall queue and status-Pro
clinical.recalls.createSchedule a recall for a patient-Pro
clinical.recalls.editChange recall date or message-Pro
clinical.recalls.deleteCancel a recall-Pro
clinical.recalls.batch_generateAuto-generate recalls for a cohort of patients-Pro

Clinical — IPD / In-Patient Department (4 keys)

Permission KeyWhat it controlsDoctorReceptionistPatientPlan
clinical.ipd.viewSee admission records--Pro+ only
clinical.ipd.admitAdmit a new patient to IPD--Pro+ only
clinical.ipd.editUpdate admission notes, ward, charges--Pro+ only
clinical.ipd.dischargeDischarge a patient and generate summary--Pro+ only
IPD is a Pro+ / Enterprise-only module. Doctors on Pro do not have these keys regardless of clinic template.

Billing — Invoices (8 keys)

Permission KeyWhat it controlsDoctorReceptionistPatientPlan
billing.invoices.viewSee invoice list✓ (own)Pro
billing.invoices.view_detailOpen a full invoice with line items✓ (own)Pro
billing.invoices.createDraft a new invoice-Pro
billing.invoices.editModify line items, discounts, due date-Pro
billing.invoices.sendEmail invoice to patient-Pro
billing.invoices.convertConvert a quotation to an invoice---Admin only
billing.invoices.shareGenerate a public payment link for the invoice-Pro
billing.invoices.revoke_shareRevoke a previously shared payment link--Pro
Floor: billing.invoices.view is irrevocable for receptionists — minimum required to handle payments at front desk.

Billing — Receipts & Payments (5 keys)

Permission KeyWhat it controlsDoctorReceptionistPatientPlan
billing.receipts.viewView receipt history✓ (own)Pro
billing.receipts.createIssue a payment receipt-Pro
billing.receipts.sendEmail receipt to patient-Pro
billing.receipts.shareShare receipt as public link--Pro
billing.payments.viewView payment records✓ (own)Pro
billing.payments.recordLog an offline/cash payment against an invoice-Pro

Billing — Installments (3 keys)

Permission KeyWhat it controlsDoctorReceptionistPatientPlan
billing.installments.viewSee installment plans✓ (own)Pro
billing.installments.createSet up a new payment plan for a patient--Pro
billing.installments.generate_invoiceTrigger invoice generation for a due installment term--Pro

Billing — Quotations (7 keys)

Permission KeyWhat it controlsDoctorReceptionistPatientPlan
billing.quotations.viewBrowse quotations✓ (own)Pro
billing.quotations.createDraft a quotation-Pro
billing.quotations.editEdit line items and pricing--Pro
billing.quotations.deleteDelete a quotation--Pro
billing.quotations.sendEmail quotation to patient-Pro
billing.quotations.reissueRe-issue an expired quotation--Pro
billing.quotations.shareShare as a public link--Pro

Billing — Expenses (4 keys)

Permission KeyWhat it controlsDoctorReceptionistPatientPlan
billing.expenses.viewView expense records---Admin only
billing.expenses.manageCreate and edit expense entries---Admin only
billing.expenses.deleteDelete an expense---Admin only
billing.expenses.view_eodView end-of-day financial summary---Admin only

Billing — Payroll (3 keys)

Permission KeyWhat it controlsDoctorReceptionistPatientPlan
billing.payroll.viewView payroll periods and runs---Admin only
billing.payroll.manageCreate employees and pay periods---Admin only
billing.payroll.runExecute a payroll run---Admin only

Billing — Insurance Claims (4 keys)

Permission KeyWhat it controlsDoctorReceptionistPatientPlan
billing.insurance.viewView insurance claims--Pro+ only
billing.insurance.createSubmit a new claim--Pro+ only
billing.insurance.editUpdate claim details and status--Pro+ only
billing.insurance.manage_attachmentsUpload/delete supporting documents to a claim--Pro+ only
Insurance claims are Pro+ / Enterprise only. Doctors on Pro do not have these keys.

Inventory (6 keys)

Permission KeyWhat it controlsDoctorReceptionistPatientPlan
inventory.viewBrowse inventory items and stock levels✓ (view only)✓ (Pro+)-Pro
inventory.createAdd a new item to inventory-✓ (Pro+ only)-Pro+
inventory.editEdit item details and reorder point-✓ (Pro+ only)-Pro+
inventory.adjust_stockRecord stock received, consumed, or adjusted--Pro
inventory.view_alertsSee low-stock and expiry alerts-Pro
inventory.manage_suppliersAdd and edit supplier records-✓ (Pro+ only)-Pro+
Doctors get view + alerts only — they need to see supply levels but shouldn’t manage stock. Receptionists get full inventory write access on Pro+, view/adjust on Pro.

Lab (10 keys)

Permission KeyWhat it controlsDoctorReceptionistPatientPlan
lab.cases.viewBrowse lab cases-Pro
lab.cases.createOpen a new lab case-Pro
lab.cases.update_statusMove case through workflow (sent → received → ready)-Pro
lab.services.viewBrowse lab service catalog-Pro
lab.services.manageAdd/edit lab services and pricing--Pro
lab.services.deleteDelete a lab service--Pro
lab.laboratories.viewBrowse external lab partners-Pro
lab.laboratories.createAdd a new lab partner--Pro
lab.laboratories.editUpdate lab contact and details--Pro
lab.laboratories.deleteRemove a lab partner--Pro
Receptionists can manage the case lifecycle but cannot configure labs or services — that’s clinical territory.

Bridge / X-Ray Integration (3 keys)

Permission KeyWhat it controlsDoctorReceptionistPatientPlan
bridge.viewSee Bridge X-ray inbox and patient file matches-Pro+ only
bridge.captureCapture/upload an X-ray from the Bridge device--Pro+ only
bridge.manageConfigure the Bridge device settings---Admin / Pro+ only
Bridge is a hardware X-ray integration device. Access is Pro+ only. Receptionists can only view (to assist with file matching), not capture.

Communications (9 keys)

Permission KeyWhat it controlsDoctorReceptionistPatientPlan
comms.messages.viewRead message conversations✓ (own)Pro
comms.messages.send_patientSend a message to a patientPro
comms.messages.send_staffSend a message to another staff member-Pro
comms.messages.deleteDelete a message thread--Pro
comms.messages.check_windowCheck if 24-hour WhatsApp messaging window is open-Pro
comms.messages.mark_readMark messages as readPro
comms.templates.viewBrowse message templates-Pro
comms.templates.manageCreate/edit message templates---Admin only
comms.bulk.sendSend a broadcast message to a patient segment--Pro

Reports & Analytics (3 keys)

Permission KeyWhat it controlsDoctorReceptionistPatientPlan
reports.financialAccess financial reports (revenue, collections, aging)--Pro+ (doctor), Admin always
reports.statsAccess operational stats (appointments, patient volume)-Pro
reports.revenueAccess revenue breakdown reports--Pro+ (doctor)
On Pro plan, doctors get reports.stats only. reports.financial and reports.revenue require Pro+.

AI Insights (15 keys)

Permission KeyWhat it controlsDoctorReceptionistPatientPlan
ai.patient_briefGenerate AI patient brief before an appointment--Pro+
ai.clinical_assistAI-assisted SOAP note generation from voice/text--Pro+
ai.shorten_expandExpand shorthand → full prose, or shorten verbose notes--Pro
ai.recall_messageGenerate personalized recall reminder message for a patient--Pro+
ai.dicom_analysis.viewView existing AI DICOM X-ray analysis results--Pro+
ai.dicom_analysis.runTrigger a new AI analysis on a DICOM X-ray--Pro+
ai.daily_briefGenerate the morning operational brief for the clinic-Pro
ai.appointment_nudgesGenerate appointment confirmation/reminder messages-Pro
ai.monthly_summaryGenerate monthly performance summary--Pro+
ai.treatment_plan_presentationGenerate patient-friendly treatment plan explanation--Pro
ai.revenue_forecastAI revenue forecast based on pipeline--Pro+
ai.churn_riskIdentify at-risk patients likely to churn--Pro+
ai.payment_reminderGenerate a payment reminder message for overdue invoices-Pro
ai.eod_summaryGenerate end-of-day summary--Pro
ai.grammar_rewriteFix grammar and style in clinical notes-Pro

Settings (16 keys)

Permission KeyWhat it controlsDoctorReceptionistPatientPlan
settings.staff.viewView staff list and their roles--Pro
settings.staff.createInvite or directly create a staff account---Admin only
settings.staff.editEdit staff name, role, or profile---Admin only
settings.staff.removeRemove a staff member from the clinic---Admin only
settings.staff.manage_permissionsOverride individual staff permissions---Admin only
settings.staff.resend_invitationResend a pending staff invite email---Admin only
settings.staff.refresh_accessRefresh patient portal access tokens---Admin only
settings.rooms.viewView operatory/room list---Admin only
settings.rooms.manageCreate, edit, delete operatory rooms---Admin only
settings.branding.viewView clinic logo and branding settings---Admin only
settings.branding.editUpload logo, favicon, set color theme---Admin only
settings.email_templates.viewView automated email templates---Admin only
settings.email_templates.editCustomize email template content---Admin only
settings.email_templates.testSend a test email for a template---Admin only
settings.signatures.viewView uploaded doctor signature images✓ (Pro+)-Pro
settings.signatures.manageUpload or activate a signature✓ (Pro+)-Pro+
settings.signatures.deleteDelete a signature--Pro
settings.referrals.viewView patient referral source list---Admin only
settings.referrals.manageAdd/edit referral sources---Admin only
settings.referrals.deleteDelete a referral source---Admin only
settings.appointment_types.manageConfigure appointment type names and colors---Admin only
settings.working_hours.manageSet clinic working hours and doctor availability---Admin only
settings.modules.manageEnable/disable optional clinic modules---Admin only

Notifications (2 keys)

Permission KeyWhat it controlsDoctorReceptionistPatientPlan
notifications.view_allView all clinic notifications (not just own)---Admin only
notifications.manageMark notifications read, delete notificationsPro

Audit & Compliance (3 keys)

Permission KeyWhat it controlsDoctorReceptionistPatientPlan
audit.logs.viewView system audit log (who did what, when)---Admin only
audit.logs.exportExport audit log as CSV---Admin only
audit.activity.viewView entity-level activity timeline (appointment, patient, etc.)--Pro

Endpoint Reference

All protected endpoints require a valid session cookie/token. All clinic-scoped endpoints enforce the active clinic context.
Notation: [perm] = requirePermission(perm) · [any: a, b] = requireAnyPermission([a, b]) · [role] = hard-coded role check · [auth] = authenticated only, no specific perm · - = public

Authentication (/api/v1/auth/)

MethodPathAuthDescription
POST/signup-Register new clinic — creates a pending approval request (manual superadmin review required)
POST/signin-Email + password sign-in, returns session
POST/mobile-signin-Mobile app sign-in with PIN/biometric pre-check
POST/mfa/verify-Verify MFA code during login flow
POST/mfa/setup/send-otp-Send OTP to begin MFA setup
POST/mfa/setup/init-totp-Initialize TOTP authenticator app setup
POST/mfa/setup/verify-Confirm TOTP code to complete setup
POST/forgot-password-Send password reset email
POST/verify-otp-Verify OTP for password reset flow
POST/confirm-password-reset-Complete password reset with OTP
POST/reset-password-Reset password using reset token
POST/onboarding-Begin clinic onboarding after approval
GET/onboarding/validate/:token-Validate onboarding token from email link
POST/onboarding/send-otp-Send OTP during onboarding
POST/onboarding/complete-Finalize onboarding and activate clinic
GET/check-status/:requestId-Poll approval status for a pending signup
POST/check-status/:requestId/resend-activation-Resend the activation email
GET/invitation/:token-Preview a staff invitation before accepting
POST/invitation/:token/accept-Accept a staff invitation and set password
POST/verify-setup-token-Verify account setup link token
POST/set-password-Set initial password for invited staff
POST/generate-ott-Generate a one-time sign-in token
POST/exchange-Exchange a one-time token for a session
POST/impersonation/exit[auth]Exit superadmin impersonation session
POST/refresh-Refresh access token using refresh token (rotation)
POST/GET/logout[auth]Sign out and revoke session

2FA (/api/v1/auth/2fa/)

MethodPathAuthDescription
POST/setup/init[auth]Start 2FA setup flow
POST/setup/verify[auth]Confirm 2FA is working, save to account
POST/verify-Verify 2FA code during login
POST/recovery-Use a recovery code instead of 2FA code
POST/email/send-Send 2FA code via email
GET/status[auth]Get 2FA enabled/type status
DELETE/disable[auth]Disable 2FA (requires verification)
POST/regenerate-codes[auth]Generate new backup/recovery codes
POST/backup-codes/request-email[auth]Email the backup codes to the user
POST/backup-codes/view[auth]View backup codes in-browser (requires re-auth)
POST/reset/request-Request 2FA reset (for locked-out users)
POST/reset/verify-Complete 2FA reset with identity verification

Passkeys / WebAuthn (/api/v1/auth/passkeys/)

MethodPathAuthDescription
POST/register/options[auth]Get WebAuthn registration challenge
POST/register[auth]Register new passkey (FaceID, fingerprint, hardware key)
POST/authenticate/options-Get WebAuthn authentication challenge
POST/authenticate-Sign in with passkey
GET/[auth]List registered passkeys
DELETE/:id[auth]Remove a passkey
PATCH/:id[auth]Rename a passkey

Blog (/api/v1/blog/)

MethodPathAuthDescription
GET/-List published blog posts
GET/:slug-Get blog post by slug

Help Center (/api/v1/help/)

MethodPathAuthDescription
GET/categories-List help documentation categories
GET/articles-List help articles (filterable by category)
GET/articles/:slug-Get individual help article
GET/releases-List product release notes

Public Endpoints

MethodPathAuthDescription
POST/contact-Submit contact/demo request form
POST/guide-lead-Download guide lead capture (marketing)
POST/public-referrals/-Patient submits referral from a shareable referral link
POST/appointments/respond-Patient confirms or cancels appointment from email link
GET/branding/:clinicId/info-Get clinic name, logo URL for white-label embed
GET/branding/:clinicId/:type-Serve clinic logo or favicon
POST/waitlist/-Join app waitlist
GET/upgrade-invite/:token-View an upgrade invite sent by sales
POST/upgrade-invite/:token/request-Accept / request upgrade
POST/support/feature-request-Submit anonymous feature request

Public Documents (/api/v1/public-documents/)

MethodPathAuthDescription
GET/:token-View a shared document (invoice, prescription, treatment plan)
POST/:token/accept-Accept a shared document (e.g., patient accepting treatment plan)
PUT/:token/lab-status-External lab updates case status via shared link
POST/:token/lab-attachments-External lab uploads files to a case

WhatsApp Webhook (/api/v1/whatsapp/)

MethodPathAuthDescription
GET/POST/webhook-Meta/WhatsApp platform verification and message ingestion
GET/POST/:clinicId/webhook-Per-clinic WhatsApp webhook endpoint

OTLP Telemetry (/api/v1/otlp/)

MethodPathAuthDescription
POST/logs-OTLP log ingestion endpoint (from client/worker)

Stripe Webhook

MethodPathAuthDescription
POST/stripe/webhook-Stripe payment event webhook (signature-verified)

Activity Timeline (/api/v1/protected/activity/)

MethodPathAuthDescription
GET/:entityType/:entityId[auth]Timeline of all changes to an entity (appointment, patient, invoice, etc.)

AI Insights (/api/v1/protected/ai/)

Requires ai_insights module to be enabled for the clinic.
MethodPathPermissionDescription
POST/clinical-notesai.clinical_assistGenerate SOAP note from transcript or voice input
POST/patient-briefai.patient_briefGenerate pre-appointment patient brief
GET/revenue-forecastai.revenue_forecastAI revenue forecast from pipeline + history
GET/treatment-followupsai.clinical_assistGenerate follow-up messages for completed treatments
GET/churn-riskai.churn_riskList patients at risk of not returning
GET/daily-briefai.daily_briefMorning brief: today’s schedule, outstanding tasks
POST/payment-reminderai.payment_reminderDraft overdue payment reminder message
POST/payment-reminder/sendai.payment_reminderSend the drafted reminder to the patient
POST/rewriteai.grammar_rewriteImprove clinical note style and clarity
POST/grammarai.grammar_rewriteFix grammar in selected text
POST/shortenai.shorten_expandCondense verbose clinical notes
POST/expandai.shorten_expandExpand shorthand into full clinical prose
GET/appointment-nudgesai.appointment_nudgesGenerate appointment reminders/confirmations
GET/recall-message/:patientIdai.recall_messagePersonalized recall message for a specific patient
GET/monthly-summaryai.monthly_summaryMonthly performance summary for clinic
GET/treatment-plan-presentation/:planIdai.treatment_plan_presentationPatient-friendly explanation of a treatment plan
GET/dicom-analysis/:patientFileIdai.dicom_analysis.viewRetrieve existing DICOM analysis result
POST/dicom-analysisai.dicom_analysis.runTrigger AI analysis on a DICOM X-ray file
GET/dicom-quota[auth]Check DICOM AI usage vs plan quota
POST/dicom-terms-accept[auth]Accept DICOM AI usage terms (one-time)

Analytics (/api/v1/protected/analytics/)

MethodPathAuthDescription
GET/[role: superadmin]Platform-wide analytics across all clinics
GET/financial-summary[role: admin, superadmin]Financial summary for current clinic

Appointments (/api/v1/protected/appointments/)

MethodPathPermissionDescription
GET/appointments.viewList appointments (filterable by date, doctor, status)
POST/appointments.createBook a new appointment
GET/available-slots[auth]Query available time slots (used by booking form)
GET/doctor-schedules[auth]Get all doctors’ weekly schedules
GET/:idappointments.view_detailGet full appointment detail
PUT/:idappointments.editUpdate appointment (time, doctor, notes, type)
DELETE/:idappointments.deleteDelete appointment
PATCH/:id/statusappointments.change_statusTransition appointment status
POST/:id/send-summaryappointments.send_summarySend appointment summary to patient
GET/:id/share-link[auth]Get shareable appointment confirmation link
PUT/doctor-schedules/:doctorId[auth]Update doctor weekly availability

Audit Logs (/api/v1/protected/audit-logs/)

MethodPathPermissionDescription
GET/audit.logs.viewView system audit log (paginated, filterable by user/action/date)

Billing — Subscription Billing (/api/v1/protected/billing/)

MethodPathAuthDescription
POST/license-requests[auth]Request a license seat increase
GET/license-requests[auth]View pending license requests
PATCH/license-requests/:id[auth]Update a license request
GET/invoicesbilling.invoices.viewList OdontoX subscription invoices (not clinic invoices)
GET/invoices/next-number[auth]Preview the next invoice number
POST/invoicesbilling.invoices.createCreate a subscription invoice
POST/invoices/:id/sendbilling.invoices.sendEmail subscription invoice
POST/invoices/:id/portal[auth]Create Stripe customer portal link
POST/invoices/:id/mark-paidbilling.invoices.editMark invoice as paid
GET/invoices/:id/pdfbilling.invoices.viewDownload invoice PDF
POST/upgrade-invite-token[auth]Generate a sales upgrade invite link
POST/upgrade-requests[auth]Submit an upgrade request to sales
GET/payment-methods[auth]List saved payment methods (Stripe)
PATCH/payment-methods/:id/default[auth]Set a payment method as default
DELETE/payment-methods/:id[auth]Remove a payment method
GET/overview[auth]Get subscription plan, usage, next bill date
POST/referral-payouts[auth]Request referral program commission payout
GET/referral-payouts[auth]List referral payout requests
GET/clinics[role: superadmin]Get billing info for all clinics

Blog Admin (/api/v1/protected/blog/admin/)

MethodPathAuthDescription
GET/all[role: superadmin]List all posts including drafts
GET/:id[role: superadmin]Get post (including draft)
POST/[role: superadmin]Create blog post
PUT/:id[role: superadmin]Update blog post
DELETE/:id[role: superadmin]Delete blog post

Bridge / X-Ray (/api/v1/protected/bridge/)

MethodPathPermissionDescription
GET/patients/searchbridge.viewSearch patients to attach X-ray from Bridge inbox

Clinic API Keys (/api/v1/protected/clinic/api-keys/)

MethodPathAuthDescription
POST/[role: admin]Create a new API key for clinic integrations
GET/[role: admin]List active API keys
DELETE/:keyId[role: admin]Revoke an API key

Clinic Modules (/api/v1/protected/clinic/modules/)

MethodPathAuthDescription
GET/active[auth]Get the list of enabled modules for the current clinic

Permission Templates (/api/v1/protected/clinic/permission-templates/)

MethodPathAuthDescription
GET/[role: admin]Get the clinic’s custom role permission templates
PUT/:role[role: admin]Override default permissions for a role at clinic level
DELETE/:role[role: admin]Reset a role’s permissions back to plan defaults

Clinical Notes (/api/v1/protected/clinical-notes/)

MethodPathPermissionDescription
GET/patient/:patientIdclinical.notes.viewGet all clinical notes for a patient
GET/:idclinical.notes.viewGet a specific note
POST/clinical.notes.createWrite a new clinical note
PUT/:idclinical.notes.editEdit an existing note
DELETE/:idclinical.notes.deleteDelete a note

Clinics (/api/v1/protected/clinics/)

MethodPathAuthDescription
GET/context[auth]Get current clinic context (name, plan, active modules)
POST/context/switch[auth]Switch active clinic (multi-clinic users)
GET/[role: superadmin]List all clinics
GET/:id[role: admin, superadmin]Get clinic details
PUT/:id[role: admin]Update clinic settings
PUT/:id/subscription[role: superadmin]Update clinic subscription plan
POST/:id/brandingsettings.branding.editUpload clinic logo or favicon
DELETE/:id/branding/:typesettings.branding.editRemove a branding asset
DELETE/:id[role: superadmin]Delete a clinic (hard delete)
GET/deletions/history[role: superadmin]View deleted clinic history
GET/subscription-plans[auth]List available subscription plans and their features
GET/:id/users[role: admin, superadmin]Get all users in a clinic

Clinical Client Logs (/api/v1/protected/logs/client/)

MethodPathAuthDescription
GET/[role: superadmin]View client-side error logs
POST/[auth]Submit a client error log from the browser

Cron Jobs (/api/v1/protected/superadmin/cron-jobs/)

MethodPathAuthDescription
POST/[role: superadmin]Create a scheduled cron job
GET/[role: superadmin]List cron jobs
PUT/:id[role: superadmin]Update cron schedule or payload
DELETE/:id[role: superadmin]Delete cron job
POST/trigger-eod[role: superadmin]Manually fire end-of-day processing

Dental Charts (/api/v1/protected/dental-charts/)

MethodPathPermissionDescription
GET/patient/:patientIdclinical.dental_chart.viewGet the dental chart for a patient
GET/:idclinical.dental_chart.viewGet a specific chart record
POST/clinical.dental_chart.createCreate a new chart
POST/:chartId/initializeclinical.dental_chart.initializeInitialize full-mouth chart for a new patient
PUT/tooth/:toothIdclinical.dental_chart.editUpdate a single tooth’s status/treatment
POST/toothclinical.dental_chart.createAdd a new tooth record to chart
PUT/:chartId/teethclinical.dental_chart.editBatch update multiple teeth at once

Document Issuance (/api/v1/protected/document-issuance/)

MethodPathAuthDescription
POST/[auth]Issue a document (creates share token + records metadata)

Document Views (/api/v1/protected/document-views/)

MethodPathAuthDescription
POST/[auth]Record that a document was viewed (analytics)

Email Templates (/api/v1/protected/superadmin/emails/templates/)

MethodPathAuthDescription
GET/[role: superadmin]List all email templates (system defaults + overrides)
POST/[role: superadmin]Create a custom email template
GET/:key[role: superadmin]Get template by key
PUT/:key[role: superadmin]Update template content
POST/:key/test[role: superadmin]Send a test email with this template
POST/seed[role: superadmin]Seed default system templates

Expenses (/api/v1/protected/expenses/)

MethodPathPermissionDescription
GET/billing.expenses.viewList clinic expenses (operational costs)
POST/billing.expenses.manageCreate an expense entry
PUT/:idbilling.expenses.manageUpdate an expense
DELETE/:idbilling.expenses.deleteDelete an expense
GET/eod-reportbilling.expenses.view_eodEnd-of-day financial summary
POST/eod-report/ai-summarybilling.expenses.view_eodGenerate AI narrative of EOD report

Files (/api/v1/protected/files/)

MethodPathAuthDescription
POST/upload[auth]Upload a generic file to R2 storage
GET/storage-usage[role: admin]Get total storage used by the clinic
GET/patients-summary[role: admin]File count/size breakdown by patient
GET/:id/download[auth]Download a file (generates signed R2 URL)
POST/messages/:messageId/upload[auth]Upload attachment to a message
GET/messages/:messageId/attachments/:key/download[auth]Download message attachment
GET/bridge-inboxbridge.viewList unassigned X-rays in the Bridge device inbox
GET/:id[auth]Get file metadata
POST/:id/convert[auth]Convert file format (e.g., TIFF → PNG, DICOM → PNG)
POST/:id/attach-patient[auth]Link an unassigned Bridge file to a patient
DELETE/:id[auth]Delete a file from storage

Help Center Admin (/api/v1/protected/help/admin/)

MethodPathAuthDescription
POST/categories[role: superadmin]Create a help category
PUT/categories/:id[role: superadmin]Update category
POST/articles[role: superadmin]Create help article
PUT/articles/:id[role: superadmin]Update article
POST/releases[role: superadmin]Publish release notes
PUT/releases/:id[role: superadmin]Update release notes

Installments (/api/v1/protected/installments/)

MethodPathPermissionDescription
POST/billing.installments.createCreate a payment installment plan
GET/billing.installments.viewList all installment plans
GET/:idbilling.installments.viewGet plan detail
GET/by-treatment-plan/:treatmentPlanIdbilling.installments.viewGet plans linked to a treatment plan
POST/:termId/generate-invoicebilling.installments.generate_invoiceGenerate invoice for a due term
POST/cron/generate-due-invoices[role: superadmin]Cron: auto-generate invoices for all due terms

Insurance Claims (/api/v1/protected/insurance-claims/)

MethodPathPermissionDescription
GET/billing.insurance.viewList all insurance claims
GET/patient/:patientIdbilling.insurance.viewGet claims for a patient
GET/:idbilling.insurance.viewGet claim detail
PUT/:idbilling.insurance.editUpdate claim status or details
DELETE/:idbilling.insurance.editDelete a claim
GET/:id/attachmentsbilling.insurance.viewList claim attachments
POST/:id/attachmentsbilling.insurance.manage_attachmentsUpload supporting document to claim
DELETE/:id/attachments/:fileIdbilling.insurance.manage_attachmentsRemove attachment from claim
POST/billing.insurance.createSubmit a new insurance claim

Inventory (/api/v1/protected/inventory/)

MethodPathPermissionDescription
GET/inventory.viewList inventory items
POST/inventory.createAdd a new inventory item
GET/:idinventory.viewGet item detail
PUT/:idinventory.editEdit item info, reorder point, unit
POST/:id/receiveinventory.adjust_stockRecord stock received (purchase order)
POST/:id/consumeinventory.adjust_stockRecord stock consumed (procedure use)
POST/:id/adjustinventory.adjust_stockManual stock adjustment (correction/write-off)
GET/:id/transactionsinventory.viewTransaction history for an item
GET/:id/movementsinventory.viewStock movement log
GET/suppliersinventory.viewList suppliers
POST/suppliersinventory.manage_suppliersAdd a supplier
GET/alertsinventory.view_alertsGet low-stock and expiry alerts
POST/alerts/:id/acknowledgeinventory.view_alertsDismiss/acknowledge an alert
GET/summaryinventory.viewInventory summary (total value, alert count)

IPD / In-Patient Department (/api/v1/protected/ipd/)

MethodPathPermissionDescription
GET/admissionsclinical.ipd.viewList current and past admissions
POST/admissionsclinical.ipd.admitAdmit a patient to IPD
GET/admissions/:idclinical.ipd.viewGet admission detail
PUT/admissions/:idclinical.ipd.editUpdate admission (ward, notes, charges)
POST/admissions/:id/dischargeclinical.ipd.dischargeDischarge patient and generate discharge summary
GET/admissions/:id/appointmentsclinical.ipd.viewGet appointments linked to an admission
GET/admissions/:id/notesclinical.ipd.viewGet clinical notes for an admission

Invoices (/api/v1/protected/invoices/)

MethodPathPermissionDescription
GET/billing.invoices.viewList clinic invoices
GET/next-numberbilling.invoices.viewPreview next auto-generated invoice number
POST/billing.invoices.createCreate a new invoice
GET/:idbilling.invoices.view_detailGet invoice with full line items
PUT/:idbilling.invoices.editEdit invoice
DELETE/:idbilling.invoices.editDelete invoice
POST/:id/sendbilling.invoices.sendEmail invoice to patient
POST/:id/mark-paidbilling.invoices.editRecord as paid
GET/:id/pdfbilling.invoices.viewDownload invoice PDF
POST/:id/sharebilling.invoices.shareGenerate public payment link
DELETE/:id/sharebilling.invoices.revoke_shareRevoke public share link

Lab Cases (/api/v1/protected/lab-cases/)

MethodPathPermissionDescription
GET/lab.cases.viewList lab cases
GET/patient/:patientIdlab.cases.viewGet cases for a patient
GET/:idlab.cases.viewGet case detail
POST/lab.cases.createOpen a new lab case
PUT/:idlab.cases.update_statusUpdate case status or details
GET/:id/activitylab.cases.viewActivity log for case
GET/:id/attachments/:encodedKeylab.cases.viewDownload a case attachment

Lab Services (/api/v1/protected/lab-services/)

MethodPathPermissionDescription
GET/lab.services.viewList lab services catalog
GET/:idlab.services.viewGet service detail
POST/lab.services.manageCreate a lab service
PUT/:idlab.services.manageUpdate service
DELETE/:idlab.services.deleteDelete service

Laboratories (/api/v1/protected/laboratories/)

MethodPathPermissionDescription
GET/lab.laboratories.viewList external lab partners
GET/:idlab.laboratories.viewGet lab partner detail
POST/lab.laboratories.createAdd a lab partner
PUT/:idlab.laboratories.editEdit lab details
DELETE/:idlab.laboratories.deleteRemove a lab partner

Licenses (/api/v1/protected/licenses/)

MethodPathAuthDescription
GET/:clinicId[role: admin, superadmin]Get license plan, seat counts
GET/:clinicId/usage[role: admin, superadmin]Current seat usage vs limit
GET/:clinicId/check/:role[role: admin]Check if a new user of given role would exceed seat limit
POST/:clinicId/upgrade[role: superadmin]Apply a license upgrade

Medications (/api/v1/protected/medications/)

MethodPathPermissionDescription
GET/clinical.medications.viewList clinic medication catalog
POST/clinical.medications.createAdd a medication
POST/bulkclinical.medications.createBulk import medications
PUT/:idclinical.medications.createUpdate medication
DELETE/:idclinical.medications.deleteRemove medication from catalog

Messages (/api/v1/protected/messages/)

MethodPathPermissionDescription
GET/comms.messages.viewList all messages
GET/conversationscomms.messages.viewList conversation threads
GET/conversations/:idcomms.messages.viewGet conversation detail
POST/conversations/:id/sendcomms.messages.send_patientReply in a conversation
POST/conversations/:id/readcomms.messages.mark_readMark conversation as read
GET/receptionists[auth]Get list of receptionists (for staff messaging)
GET/contacts[auth]Get messageable contacts
GET/:idcomms.messages.viewGet a specific message
POST/comms.messages.send_patientSend a new message
PUT/:id[auth]Update message status
GET/patient/:patientIdcomms.messages.viewGet all messages with a patient
GET/staff/:staffIdcomms.messages.viewGet all messages with a staff member
DELETE/:idcomms.messages.deleteDelete a message
GET/can-initiate/:patientIdcomms.messages.check_windowCheck if 24-hour WhatsApp window is open
POST/whatsapp/sendcomms.messages.send_patientSend via WhatsApp channel

Mobile (/api/v1/protected/mobile/)

Permissions Engine:
MethodPathAuthDescription
GET/permissions[auth]Get mobile-specific permission config
GET/permissions/clinic/:clinicId/:role[role: admin, superadmin]Get permission config for a role
PATCH/permissions/clinic/:clinicId/:role/:module[role: admin]Toggle a module permission for mobile
Consolidated Screen Endpoints (Native iOS/Android):
MethodPathPermissionTTLDescription
GET/screen/dashboardappointments.view5 minDashboard: today’s visits, stats, week KPIs, notifications
GET/screen/appointments?view=monthappointments.view15 minAppointments: list, available slots, doctor schedules, rules
GET/screen/patients?page=1patients.view1 hourPatients: list, details, prescriptions, treatment plans
GET/screen/financebilling.invoices.view30 minFinance: invoices, quotes, receipts, summary (role: admin/doctor only, patient sees own)
GET/screen/chatcomms.messages.view2 minChat: staff threads, patient threads, unread counts (real-time-ish)
GET/screen/lab-worklab.cases.view15 minLab work: cases, summary (role: admin/doctor/reception only)
GET/screen/inventoryinventory.view15 minInventory: items, low-stock alerts (role: admin/doctor/reception only)
Response Format (All Screen Endpoints):
{
  "success": true,
  "data": { /* screen-specific payload */ },
  "meta": {
    "cached": false,
    "fetchedAt": "2026-05-09T10:45:00Z",
    "expiresAt": "2026-05-09T10:50:00Z"
  }
}
Query Parameters (Screen Endpoints):
  • source=mobile — marks request as from mobile client (for analytics)
  • view? (appointments): 'day' | 'week' | 'month' (default: 'month')
  • page? (patients, any paginated): page number (default: 1)
  • limit? (override defaults per screen)

Notifications (/api/v1/protected/notifications/)

MethodPathPermissionDescription
GET/notifications.view_allList all clinic notifications (admin view)
GET/unread-count[auth]Get unread notification count for current user
PUT/:id[auth]Mark a notification as read
PUT/mark-all-read[auth]Mark all notifications as read
DELETE/:idnotifications.manageDelete a notification
GET/live-feed[auth]SSE stream of real-time notifications

Patient Files (/api/v1/protected/patient-files/)

MethodPathPermissionDescription
GET/clinical.patient_files.viewList all patient files
GET/patient/:patientIdclinical.patient_files.viewGet files for a patient
GET/:idclinical.patient_files.viewGet file metadata
POST/clinical.patient_files.uploadUpload a file to patient record
PUT/:idclinical.patient_files.editEdit file name or category
DELETE/:idclinical.patient_files.deleteDelete a patient file

Patient Recalls (/api/v1/protected/patient-recalls/)

MethodPathPermissionDescription
GET/clinical.recalls.viewList recall queue
GET/patient/:patientIdclinical.recalls.viewGet recalls for a patient
GET/:idclinical.recalls.viewGet recall detail
POST/clinical.recalls.createSchedule a recall
PUT/:idclinical.recalls.editUpdate recall date or message
DELETE/:idclinical.recalls.deleteCancel recall
POST/batch-generateclinical.recalls.batch_generateBatch generate recalls for a patient cohort

Patients (/api/v1/protected/patients/)

MethodPathPermissionDescription
GET/patients.viewList all patients (paginated)
GET/searchpatients.viewFull-text search patients
GET/:idpatients.view_detailGet patient profile
POST/patients.createRegister a new patient
PUT/:idpatients.editUpdate patient demographics
DELETE/:idpatients.deleteDelete patient record
PUT/:id/medicalpatients.view_medical_historyUpdate patient medical history
GET/profile[auth]Patient: get own profile
PUT/profilepatients.editPatient: update own profile
PUT/profile/medical[auth]Patient: update own medical history
GET/check-account/:email[auth]Check if an email already has a patient portal account
POST/invitepatients.invite_portalSend patient portal invite

Payment / Stripe (/api/v1/protected/payment/)

MethodPathAuthDescription
GET/status[auth]Get current Stripe subscription status
POST/checkout[role: admin]Create Stripe checkout session for plan upgrade
POST/portal[role: admin]Create Stripe customer portal link

Payroll (/api/v1/protected/payroll/)

MethodPathPermissionDescription
GET/employeesbilling.payroll.viewList payroll employees
POST/employeesbilling.payroll.manageAdd employee to payroll
PUT/employees/:idbilling.payroll.manageUpdate employee details
GET/periodsbilling.payroll.viewList pay periods
POST/periodsbilling.payroll.manageCreate a pay period
GET/runsbilling.payroll.viewList payroll runs
GET/runs/:idbilling.payroll.viewGet payroll run detail
POST/runsbilling.payroll.runExecute a payroll run

Prescription Template (/api/v1/protected/clinics/prescription-template/)

MethodPathPermissionDescription
POST/clinical.prescriptions.manage_templateCreate prescription template
PUT/clinical.prescriptions.manage_templateUpdate prescription template
DELETE/clinical.prescriptions.manage_templateDelete prescription template

Prescriptions (/api/v1/protected/prescriptions/)

MethodPathPermissionDescription
GET/myclinical.prescriptions.viewDoctor: get own prescriptions issued
GET/patient/:patientIdclinical.prescriptions.viewGet prescriptions for a patient
GET/:idclinical.prescriptions.viewGet prescription detail
POST/clinical.prescriptions.createIssue a new prescription
PUT/:idclinical.prescriptions.editAmend prescription
DELETE/:idclinical.prescriptions.deleteVoid prescription

Procedures (/api/v1/protected/procedures/)

MethodPathPermissionDescription
GET/categoriesclinical.procedures.viewList procedure categories
POST/categoriesclinical.procedures.createCreate a category
GET/clinical.procedures.viewList procedures in catalog
GET/:idclinical.procedures.viewGet procedure detail
POST/clinical.procedures.createCreate procedure
PUT/:idclinical.procedures.editEdit procedure
DELETE/:idclinical.procedures.deleteDelete procedure

Public Documents (Protected) (/api/v1/protected/public-documents/)

MethodPathAuthDescription
POST/[auth]Generate a public share link for a document
GET/status[auth]Get share status for current documents
POST/:id/revoke[auth]Revoke a share link

Quotations (/api/v1/protected/quotations/)

MethodPathPermissionDescription
GET/billing.quotations.viewList quotations
GET/next-numberbilling.quotations.viewPreview next quotation number
POST/billing.quotations.createCreate a quotation
GET/:idbilling.quotations.viewGet quotation detail
PUT/:idbilling.quotations.editEdit quotation
DELETE/:idbilling.quotations.deleteDelete quotation
POST/:id/sendbilling.quotations.sendEmail quotation to patient
POST/:id/reissuebilling.quotations.reissueRe-issue expired quotation
POST/:id/sharebilling.quotations.shareGenerate public share link
POST/:id/convert-to-invoicebilling.invoices.createConvert quotation to invoice

Receipts (/api/v1/protected/receipts/)

MethodPathPermissionDescription
GET/billing.receipts.viewList receipts
POST/billing.receipts.createIssue a receipt
GET/:idbilling.receipts.viewGet receipt detail
POST/:id/sendbilling.receipts.sendEmail receipt
POST/:id/sharebilling.receipts.shareShare as public link
GET/:id/pdfbilling.receipts.viewDownload PDF

Referrals (/api/v1/protected/referrals/)

MethodPathPermissionDescription
GET/settings.referrals.viewList referral sources
GET/:idsettings.referrals.viewGet referral source detail
POST/settings.referrals.manageCreate referral source
PUT/:idsettings.referrals.manageUpdate referral source
DELETE/:idsettings.referrals.deleteDelete referral source

Reports (/api/v1/protected/reports/)

MethodPathPermissionDescription
GET/financial-statementreports.financialFull financial P&L statement
GET/financial-summaryreports.financialFinancial summary (revenue, collections, outstanding)
GET/statsreports.statsOperational stats (appointments, patients, revenue KPIs)

Rooms / Operatories (/api/v1/protected/rooms/)

MethodPathPermissionDescription
GET/settings.rooms.viewList clinic operatory rooms
POST/settings.rooms.manageCreate a room
PUT/:idsettings.rooms.manageUpdate room name/status
DELETE/:idsettings.rooms.manageDelete a room

Signatures (/api/v1/protected/signatures/)

MethodPathPermissionDescription
GET/settings.signatures.viewList uploaded signatures
GET/activesettings.signatures.viewGet the currently active signature
POST/settings.signatures.manageUpload a signature image
PUT/:id/activatesettings.signatures.manageSet a signature as active
DELETE/:idsettings.signatures.deleteDelete a signature
GET/:id/downloadsettings.signatures.viewDownload signature image

SSE / Real-time Events (/api/v1/protected/sse/)

MethodPathAuthDescription
GET/clinic-events[auth]Server-sent event stream for live clinic notifications

Staff (/api/v1/protected/staff/)

MethodPathPermissionDescription
GET/settings.staff.viewList all staff members
GET/invitationssettings.staff.viewList pending invitations
POST/invitations/:id/resendsettings.staff.resend_invitationResend invite email
DELETE/invitations/:idsettings.staff.createCancel a pending invitation
POST/invitesettings.staff.createSend a staff invitation email
POST/createsettings.staff.createCreate staff account directly (no invite flow)
PUT/:idsettings.staff.editEdit staff profile
DELETE/:idsettings.staff.removeRemove staff from clinic
GET/:id/permissionssettings.staff.viewView staff member’s effective permissions
PUT/:id/permissionssettings.staff.manage_permissionsOverride staff member’s permissions
POST/refresh-patient-accesssettings.staff.refresh_accessRegenerate patient portal access links

Statistics / Dashboard (/api/v1/protected/stats/)

MethodPathAuthDescription
GET/superadmin[role: superadmin]Platform-level stats (all clinics)
GET/admin[role: admin]Admin dashboard stats (clinic KPIs)
GET/doctor[role: doctor]Doctor dashboard (today’s schedule, patient summary)
GET/receptionist[role: receptionist]Reception dashboard (today’s appointments, billing tasks)
GET/patient/summary[role: patient]Patient portal summary
GET/patient/appointments[role: patient]Patient’s appointment history
GET/patient/billing[role: patient]Patient’s billing history
GET/patient/records[role: patient]Patient’s clinical records summary
GET/patient[role: patient]Full patient stats object
GET/revenue[auth]Revenue breakdown (requires reports.revenue)
GET/superadmin/dicom-usage[role: superadmin]DICOM AI usage across all clinics

Subscription Plans (/api/v1/protected/subscription-plans/)

MethodPathAuthDescription
GET/[auth]List available plans with features
PATCH/:id[role: superadmin]Update plan details
POST/create-pro-trial[role: superadmin]Create a Pro trial for a clinic
POST/seed-defaults[role: superadmin]Seed default plan configurations

SuperAdmin Modules (/api/v1/protected/superadmin/modules/)

MethodPathAuthDescription
GET/available[role: superadmin]List all available optional modules
GET/clinics/:clinicId[role: superadmin]Get enabled modules for a clinic
POST/clinics/:clinicId/toggle[role: superadmin]Enable or disable a module for a clinic
POST/clinics/:clinicId/sync-to-plan[role: superadmin]Reset clinic modules to match plan defaults

Support Tickets (/api/v1/protected/support-tickets/)

MethodPathAuthDescription
GET/[auth]List support tickets (own tickets for users, all for superadmin)
GET/:id[auth]Get ticket detail
POST/[auth]Open a new support ticket
PUT/:id[auth]Update ticket status
POST/:id/replies[auth]Add a reply to a ticket

System Health (/api/v1/protected/system-health/)

MethodPathAuthDescription
GET/[role: superadmin]Overall system health (DB, storage, worker)
GET/endpoints[role: superadmin]Per-endpoint health check
GET/test-analytics[role: superadmin]Test analytics pipeline

Treatment Plans (/api/v1/protected/treatment-plans/)

MethodPathPermissionDescription
GET/myclinical.treatment_plans.viewDoctor: get own created plans
GET/clinical.treatment_plans.viewList all treatment plans
GET/patient/:patientIdclinical.treatment_plans.viewGet plans for a patient
GET/:idclinical.treatment_plans.viewGet plan detail
POST/clinical.treatment_plans.createDraft a treatment plan
PUT/:idclinical.treatment_plans.editEdit plan procedures, pricing, phases
POST/:id/approveclinical.treatment_plans.approveDoctor approves plan (before patient presentation)
POST/:id/acceptclinical.treatment_plans.acceptPatient accepts presented plan

User Devices (/api/v1/protected/user-devices/)

MethodPathAuthDescription
POST/[auth]Register device for push notifications

Users (/api/v1/protected/users/)

MethodPathAuthDescription
GET/[role: superadmin]List all platform users
GET/pending[role: superadmin]Get pending signup requests
GET/pending/:requestId[role: superadmin]Get specific pending request
GET/me/clinics[auth]Get current user’s clinic memberships
GET/:id/clinics[role: superadmin]Get clinic memberships for any user
POST/:id/clinics[role: superadmin]Add user to a clinic
DELETE/:id/clinics/:clinicId[role: superadmin]Remove user from a clinic
GET/clinics[role: superadmin]All user–clinic assignments
POST/:id/approve[role: superadmin]Approve a pending signup
POST/:id/reject[role: superadmin]Reject a pending signup
PUT/role[role: superadmin]Change a user’s platform role
PATCH/:id[role: superadmin]Update user account details

WhatsApp Config (/api/v1/protected/whatsapp/)

MethodPathAuthDescription
GET/config[role: admin]Get clinic’s WhatsApp integration config
PUT/config[role: admin]Update WhatsApp config (token, phone number ID)
DELETE/config[role: admin]Disconnect WhatsApp integration
POST/test[role: admin]Send a test WhatsApp message

SuperAdmin Admin Routes (/api/v1/protected/admin/)

MethodPathAuthDescription
POST/test-email-speed[role: superadmin]Benchmark email delivery speed
POST/preview-email/feedback-review[role: superadmin]Preview feedback review email
POST/preview-email/stock-alert[role: superadmin]Preview stock alert email
POST/trigger-trial-emails[role: superadmin]Manually trigger trial onboarding emails
GET/referrals[role: superadmin]List all clinic referral submissions
GET/trial-insights[role: superadmin]Trial conversion insights
GET/upgrade-requests[role: superadmin]List upgrade requests from clinics
POST/upgrade-requests/:id/decision[role: superadmin]Approve or reject an upgrade request
POST/maintenance/announce[role: superadmin]Broadcast a maintenance window announcement
GET/referral-payouts[role: superadmin]List referral payout requests
POST/referral-payouts/:id/decision[role: superadmin]Approve or reject payout
POST/referral-payouts/:id/send-form[role: superadmin]Email payout form to clinic
GET/referral-payouts/:id/pdf[role: superadmin]Download payout PDF
POST/backfill-patient-search-text[role: superadmin]Backfill patient full-text search index
POST/create-superadmin[role: superadmin]Create a new superadmin user
GET/users[role: superadmin]List all platform users (detailed view)
GET/users/multi-clinic[role: superadmin]Users with multi-clinic access
POST/users/:id/resend-invite[role: superadmin]Resend staff invite
POST/users/:id/reset-password[role: superadmin]Force password reset for user
PATCH/users/:id/status[role: superadmin]Activate or suspend a user account
PATCH/users/:id/clinics/:clinicId/permissions[role: superadmin]Override user permissions at a specific clinic
POST/users/:id/disable-2fa[role: superadmin]Force-disable 2FA for a locked-out user
POST/users/:id/impersonate[role: superadmin]Impersonate a user for debugging
DELETE/users/:id[role: superadmin]Delete a user account
GET/invitations[role: superadmin]List all pending invitations
POST/invitations[role: superadmin]Create an invitation directly
POST/invitations/:id/resend[role: superadmin]Resend invitation
POST/run-migrations[role: superadmin]Run pending DB migrations
GET/billing/logs[role: superadmin]View billing event logs
POST/billing/custom-subscription[role: superadmin]Create a custom subscription for a clinic
POST/cleanup/invoices[role: superadmin]Clean up orphaned invoices
GET/cleanup/invoices/report[role: superadmin]Preview cleanup impact
POST/imports/validate[role: superadmin]Validate a patient data import file
POST/imports/run[role: superadmin]Execute a validated patient import
GET/alerts/count[role: superadmin]Get total unacknowledged alert count
GET/alerts[role: superadmin]List all system alerts
POST/alerts/:id/acknowledge[role: superadmin]Dismiss a system alert
GET/worker-logs[role: superadmin]View Cloudflare Worker execution logs
GET/admin/leads[role: superadmin]Cross-tenant Website Leads inspector
DELETE/admin/leads/:id[role: superadmin]Hard-delete a lead submission (compliance / GDPR)

Website Leads (/leads) — clinic-scoped

Module-gated by lead_inbox + per-permission gates listed inline.
MethodPathPermissionDescription
GET/leadsleads.viewList inbox submissions (paginated, optional status filter)
GET/leads/:idleads.viewSubmission detail with decrypted PII
PATCH/leads/:idleads.manageUpdate status (new / contacted / converted / archived / spam)
POST/leads/:id/convertleads.convertCreate a patient from a lead (1-click; needs gender)
GET/leads/form-configsleads.viewList the clinic’s lead forms (token shown only to leads.configure)
POST/leads/form-configsleads.configureCreate a new lead form (mints a token)
PATCH/leads/form-configs/:idleads.configureUpdate label / origins / auto-reply / active
POST/leads/form-configs/:id/rotateleads.configureIssue a fresh token; old token immediately invalid
DELETE/leads/form-configs/:idleads.configureDisable a form (soft — submissions stop, history preserved)

Public Website Leads (/public/leads) — no auth, token-authenticated

Used by the clinic’s own React/JS website to post contact-form submissions. CORS responds based on the form’s configured allowedOrigins. Rate-limited per token and per IP. Honeypot field website must be empty.
MethodPathAuthDescription
OPTIONS/public/leadsnoneCORS preflight
POST/public/leadsX-OdontoX-Token headerCapture a contact-form submission. Body fields: firstName (required), lastName, email, phone, dateOfBirth, gender, subject, message, preferredDate, preferredTimeOfDay, customFields (object), sourceUrl, referrer, utm (object). Either email or phone is required. Returns { ok, leadId }.

Plan × Role Permission Matrix Summary

ModuleFeaturePro — DoctorPro — ReceptionistPro+ — DoctorPro+ — Receptionist
AppointmentsFull CRUD
PatientsFull CRUDcreate/edit (no delete)create/edit (no delete)
Clinical NotesFull CRUD--
Dental ChartFull CRUD--
Treatment PlansFull CRUD + approveview onlyview only
PrescriptionsFull CRUDview onlyview only
MedicationsFull CRUD--
ProceduresFull CRUD--
Patient FilesFull CRUDview + uploadview + upload
RecallsFull CRUDFull CRUDFull CRUD
IPD----
Invoicescreate/send/sharecreate/send/sharecreate/send/share
ReceiptsFullFullFull
Installmentscreate + generateview onlyview only
QuotationsFullcreate + sendcreate + send
Expenses-----
Payroll-----
Insurance----
Inventoryview + alertsview + adjust + alertsview + alertsFull CRUDFull CRUD
LabFullcases + services viewFullcases + services view
Bridge-viewview
MessagesFullsend patient + staffFullsend patient + staff
Reportsstats onlystats onlyfinancial + revenue-
AI — Clinicalclinical_assist, patient_brief, DICOM--
AI — Schedulingnudges, payment remindernudges, reminder, daily brief
AI — Businessrevenue_forecast, churn_risk, monthly_summary--
Signaturesview-viewmanage
Auditactivity.view-activity.view-

Legacy Permission Key Mapping

These old flat keys are still accepted in stored permission overrides and are transparently expanded:
Legacy KeyExpands To
view_appointmentsappointments.view, appointments.view_detail
edit_appointmentsappointments.create, .edit, .delete, .change_status, .send_summary
view_patientspatients.view, patients.view_detail
edit_patientspatients.create, .edit, .delete, .invite_portal
view_billingbilling.invoices.view, .view_detail, receipts.view, payments.view, quotations.view, installments.view
process_paymentsbilling.payments.record, receipts.create, receipts.send, invoices.create, invoices.edit, invoices.send
view_reportsreports.financial, reports.stats, reports.revenue
view_clinical_recordsAll clinical.*.view keys
edit_clinical_recordsAll clinical.*.create/edit/approve keys
manage_inventoryAll inventory.* keys
send_messagescomms.messages.view, .send_patient, .send_staff, .mark_read
manage_lab_caseslab.cases.*, lab.services.view, lab.laboratories.view