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 | Plan | Auth | Description | |—|—|—|—|—|—| | POST | /api/auth/login | All | None | Login | | POST | /api/auth/register | All | None | Register new clinic + admin | | GET | /api/auth/me | All | User | Current user profile | | PATCH | /api/users/me | All | User | Update own profile | | GET | /api/appointments | All | User | List appointments | | POST | /api/appointments | All | User | Create appointment | | PATCH | /api/appointments/:id | All | User | Update appointment | | GET | /api/doctors | All | User | List doctors | | POST | /api/doctors | All | Admin | Create doctor | | PATCH | /api/doctors/:id | All | Admin | Update doctor | | GET | /api/patients | All | User | List patients | | POST | /api/patients | All | User | Create patient | | GET | /api/analytics | Pro+ | User | Dashboard analytics | | GET | /api/dental/treatment-plans | Pro+ | User | List treatment plans | | POST | /api/dental/treatment-plans | Pro+ | User | Create treatment plan | | GET | /api/superadmin/clinics | Superadmin | Admin-Key | List all clinics |

Sections

Section titled “Sections”
  • Authentication — Login, register, password reset
  • Appointments — CRUD, availability, notifications, attendance
  • Doctors — CRUD, schedules, ICS feeds
  • Patients — CRUD, import/export, blocking
  • Clinics — Settings, WhatsApp config, QR attendance
  • Users — Staff management, self-edit, quick switch
  • Analytics — Dashboard metrics
  • FAQ — FAQ management for the WhatsApp chatbot
  • Dental — Treatment plans, payment plans, recall campaigns (Pro+)
  • Superadmin — Demo requests, invite codes, clinic management