Skip to content
ClinicFlow Docs

API Overview

API Reference

Section titled “API Reference”

Base URL

Section titled “Base URL”
Environment URL
Production https://api.clinicflow.lat/api
Local dev http://localhost:3001/api

Role Levels

Section titled “Role Levels”
Role Description
Any authenticated Valid JWT required
Admin only app_role: admin in JWT (role is always authenticated)
Superadmin X-Admin-Key header (separate from JWT)
Public No authentication

Authentication

Section titled “Authentication”

All protected endpoints require:

Authorization: Bearer <ES256 JWT>

The JWT is obtained via POST /api/auth/login. Tokens expire after 8 hours.

Error Format

Section titled “Error Format”

All errors return JSON:

{
  "error": "Human-readable message in Spanish or English",
  "code": "MACHINE_READABLE_CODE"
}

Common error codes:

Code Meaning
USER_INACTIVE User account is deactivated
SUBSCRIPTION_EXPIRED Clinic subscription has expired
PLAN_UPGRADE_REQUIRED Feature requires a higher plan
DOCTOR_LIMIT_REACHED Plan doctor limit exceeded
USER_LIMIT_REACHED Plan user limit exceeded

HTTP status codes follow REST conventions:

  • 200 — Success
  • 201 — Created
  • 400 — Bad request (validation error)
  • 401 — Unauthenticated (missing/invalid/expired token)
  • 402 — Subscription expired
  • 403 — Forbidden (valid token, insufficient permissions/plan)
  • 404 — Not found
  • 409 — Conflict (duplicate, already exists)
  • 429 — Rate limited
  • 500 — Internal server error
  • 503 — Service temporarily unavailable (fail-closed DB check)

Rate Limits

Section titled “Rate Limits”
Endpoint group Limit
Auth endpoints 10 requests / 15 min / IP (failed attempts only)
Demo requests 5 requests / hour / IP
ICS calendar feed 30 requests / 15 min / IP
All other API 100 requests / 15 min / IP

Rate limit errors return 429 Too Many Requests.

Endpoint Index

Section titled “Endpoint Index”
Method Path Required Plan Auth Level Description
POST /api/auth/login All Public Authenticate user & issue ES256 JWT + refresh cookie
POST /api/auth/register-clinic All Public Register new clinic with valid invite code
GET /api/auth/me All Authenticated Retrieve session context and user metadata
GET /api/appointments All Authenticated List clinic appointments with status/date filters
POST /api/appointments All Authenticated Create appointment (validates doctor slot availability)
PATCH /api/appointments/:id/status All Authenticated Update status (confirmed, completed, cancelled, no_show)
GET /api/doctors All Authenticated List clinic doctors and schedules
GET /api/patients All Authenticated Search patient records
POST /api/patients All Authenticated Create patient record (with DUI encryption)
GET /api/dental/charts/:patientId/current Pro+ Authenticated Retrieve current FDI tooth findings for patient
POST /api/dental/charts/:patientId/entries Pro+ Authenticated Record new tooth finding and auto-materialize chart
POST /api/dental/treatment-plans/:patientId/generate-plan Pro+ Authenticated Auto-generate multi-step treatment plan from untreated findings
POST /api/dte/checkout Pro+ Authenticated Issue signed El Salvador Electronic Tax Document (DTE Factura/CCF)
GET /api/assistant/briefing Pro+ Authenticated Retrieve daily AI Copilot executive briefing
POST /api/assistant/chat Pro+ Authenticated Interactive streaming AI Assistant chat session
GET /api/conversations All Authenticated List live WhatsApp patient chats for receptionist takeover
POST /api/conversations/:phone/reply All Authenticated Send manual WhatsApp reply to patient
GET /api/waitlist All Authenticated List patient cancellation waitlist entries
GET /api/analytics/dashboard Pro+ Authenticated Retrieve clinic revenue, occupancy, and no-show metrics
POST /webhooks/whatsapp All HMAC Webhook Receive inbound Meta WhatsApp message events
POST /webhooks/lemonsqueezy All HMAC Webhook Receive subscription order payment events
GET /api/superadmin/clinics Superadmin X-Admin-Key Platform administration & clinic lifecycle

Sections

Section titled “Sections”
  • Authentication — Login, registration, password recovery, session refresh
  • Appointments — Appointment CRUD, slot availability, draft booking
  • Doctors — Profiles, working hours, availability, commission rules
  • Patients — Patient records, tax profiles, DUI encryption, CSV export
  • Clinics — Settings, WhatsApp credential binding, QR check-in
  • Users — Staff accounts, role elevation, profile photo upload
  • Analytics — Revenue metrics, peak booking hours, commission ledgers
  • FAQ — Chatbot knowledge base entries
  • Dental Engine — Odontogram findings, periodontics, treatment plans, recall campaigns
  • DTE Invoicing — El Salvador electronic tax document issuance
  • Webhooks Reference — Meta WhatsApp Cloud API and LemonSqueezy HMAC webhooks
  • Superadmin — System management, invite codes, feature toggles