Authentication
Session management utilizes JWT with a 1-hour expiration and 2-week refresh window.
POST Login Gateway
/auth/login
Initializes a secure session. Returns a JWT and user summary.
Request{ "identifier": "patient@glucocare.com", "password": "securePassword123" }
POST Token Refresh
/auth/refresh
Rotates an active or recently expired JWT.
POST Registration
/auth/register
Request{ "displayName": "John Doe", "email": "john@example.com", "phone": "08011223344", "password": "password123", "role": "patient" }
POST Forgot Password
/auth/forgot-password
Request{ "email": "user@example.com" }
POST Verify OTP
/auth/verify-otp
Request{ "email": "user@example.com", "otp": "123456" }
Returns a signed
resetToken URL valid for 15 minutes. Pass this as the
full URL to the next step.POST Reset Password
/auth/reset-password/{id}
Use the signed URL returned in
resetToken from verify-otp. The
{id} is in that URL. Send password in the body.
Request{ "password": "newSecurePassword123" }
GET Verify Email
/auth/verify-email/{id}
Public. Activates a newly registered account via the link sent to email.
POST Logout
/auth/logout
Invalidates the current JWT and adds it to the blacklist.
Clinical Profiles
Management of role-specific clinical and personal identity data.
GET Retrieve Identity
/auth/me
Returns the currently authenticated user's summary.
PATCH Update App Preferences
/me/preferences
Quickly update application-level settings like theme and biometric status.
Request{ "theme": "dark", "biometric": true, "notification": true, "notificationToken": "fcm-token-string" }
GET Full Clinical Profile
/users/{userId}
Retrieves detailed role-specific clinical profile data.
PUT Synchronize Profile
/users/{userId}
Updates core identity and role-specific clinical baselines.
Patient Clinical Baselines (Updatable Fields — all nullable)
| Field (camelCase) | DB Column | Type | Notes |
|---|---|---|---|
| displayName | users.name | string | Full legal name |
| phone | users.phone | string | E.164 format, normalised server-side |
| dateOfBirth | date_of_birth | date | YYYY-MM-DD |
| gender | gender | string | male, female, other |
| bloodGroup | blood_group | string | A+, B-, O+, etc. |
| address | address | string | Street address |
| city | city | string | City |
| state | state | string | State / Province |
| country | country | string | Country name |
| diabetesType | diabetes_type | string | Type 1, Type 2, Gestational, Pre-diabetes |
| diagnosisDate | diagnosis_date | date | Date of first clinical diagnosis |
| insulinDependent | insulin_dependent | boolean | Active insulin therapy flag |
| insulinType | insulin_type | string | e.g. Rapid-acting, Basal, Humalog |
| baselineWeightKg | baseline_weight_kg | float | Weight in kilograms |
| baselineHeightCm | baseline_height_cm | float | Height in centimeters |
| baselineGlucoseMgDl | baseline_glucose_mg_dl | float | Initial fasting glucose reading |
| baselineHba1cPercent | baseline_hba1c_percent | float | Initial lab HbA1c (%) |
| baselineBpSystolic | baseline_bp_systolic | int | Systolic blood pressure (mmHg) |
| baselineBpDiastolic | baseline_bp_diastolic | int | Diastolic blood pressure (mmHg) |
| baselineCholesterolTotal | baseline_cholesterol_total | float | Total cholesterol (mg/dL) |
| baselineCholesterolLdl | baseline_cholesterol_ldl | float | LDL cholesterol (mg/dL) |
| baselineCholesterolHdl | baseline_cholesterol_hdl | float | HDL cholesterol (mg/dL) |
| baselineTriglycerides | baseline_triglycerides | float | Triglycerides (mg/dL) |
| baselineEgfr | baseline_egfr | float | Kidney function (eGFR mL/min/1.73m²) |
| comorbidities | comorbidities | string | Known associated conditions |
| allergies | allergies | string | Drug / food allergies |
| familyHistory | family_history | string | Inherited metabolic history |
| currentMedicationsSummary | current_medications_summary | string | Free-text medication overview |
| glucoseTargets | glucose_targets | json | { "fasting": 90, "postMeal": 140 } |
| carbTargetG | carb_target_g | int | Daily carbohydrate limit (grams) |
| glucoseUnit | glucose_unit | string | mgDl or mmolL |
| theme | theme | string | light or dark |
| notificationsEnabled | notifications_enabled | boolean | Global notification toggle |
| biometricAuth | biometric_auth | boolean | Enable fingerprint / Face ID login |
| language | language | string | ISO 639-1 language code e.g. en |
Comprehensive Patient Update{ "displayName": "John Doe", "phone": "+2348011223344", "dateOfBirth": "1990-01-15", "gender": "male", "bloodGroup": "O+", "address": "12 Ozumba Mbadiwe Ave", "city": "Lagos", "state": "Lagos", "country": "Nigeria", "diabetesType": "Type 2", "diagnosisDate": "2020-03-10", "insulinDependent": true, "insulinType": "Rapid-acting", "baselineWeightKg": 82.5, "baselineHeightCm": 175.0, "baselineGlucoseMgDl": 120, "baselineHba1cPercent": 6.8, "baselineBpSystolic": 125, "baselineBpDiastolic": 80, "baselineCholesterolTotal": 190, "baselineCholesterolLdl": 110, "baselineCholesterolHdl": 55, "baselineTriglycerides": 150, "baselineEgfr": 88.5, "comorbidities": "Hypertension", "allergies": "Penicillin", "familyHistory": "Father had Type 2 Diabetes", "currentMedicationsSummary": "Metformin 500mg twice daily", "glucoseTargets": { "fasting": 90, "postMeal": 140 }, "carbTargetG": 180, "glucoseUnit": "mgDl", "theme": "dark", "notificationsEnabled": true, "biometricAuth": false, "language": "en" }
DELETE Account Termination
/users/{userId}
Irreversibly deletes the user account and all associated clinical records (profile, glucose readings, medication schedules, meals, etc.).
POST Delete Selective Data
/users/{userId}/delete-data
Wipes specific categories of clinical records (e.g. glucose readings, medication logs, activities, meals) without deleting the account. Pass 'all' or individual category names in the array.
Request{ "categories": [ "glucose", "medication", "meals", "activities", "alerts" ] }
GET Export User Data
/users/{userId}/export
Retrieves a comprehensive JSON export of all metabolic and activity records.
POST Elevate to Admin
/admin/make-admin
Promotes a doctor to admin. Restricted to existing admins.
Request{ "userId": 15 }
Next of Kin
Manage emergency contacts and linked caregivers.
GET List Contacts
/users/{userId}/nok
POST Add Next of Kin
/users/{userId}/nok
Request{ "displayName": "Sarah Doe", "relationship": "Spouse", "phone": "09011223344", "email": "sarah@example.com", "address": "12 Ozumba Mbadiwe Ave, Lagos", "isEmergencyContact": true }
PATCH Update Next of Kin
/users/{userId}/nok/{nokId}
Updates details for a specific next of kin contact.
Request{ "displayName": "Sarah Smith", "relationship": "Wife", "phone": "09011223344", "address": "12 Ozumba Mbadiwe Ave, Lagos", "isEmergencyContact": true }
DELETE Remove Next of Kin
/nok/{nokId}
Glucose Tracking
Core metabolic monitoring endpoints.
POST Log Reading
/glucose/readings
Required:
valueMgDl, context, recordedAt.
Request{ "valueMgDl": 125, "context": "after_meal", "recordedAt": "2026-04-23T08:30:00Z", "notes": "Feeling slightly dizzy" }
GET Fetch Readings
/glucose/readings?from=YYYY-MM-DD&to=YYYY-MM-DD&context=fasting&limit=100
GET Metabolic Stats
/glucose/stats?from=YYYY-MM-DD&to=YYYY-MM-DD
Returns avg glucose, estimated HbA1c, and time-in-range for the period.
DELETE Void Reading
/glucose/readings/{id}
Nutrition & Meals
Track caloric intake and glycemic impact.
GET Available Catalog
/nutrition/available
Returns all validated meals available for logging.
POST Log Consumption
/nutrition/meals
Request{ "mealId": 5, "mealType": "breakfast", "portionSize": 1, "loggedAt": "2026-04-23T07:15:00Z" }
GET My Meal Logs
/nutrition/meals?from=YYYY-MM-DD&to=YYYY-MM-DD&mealType=breakfast
DELETE Delete Meal Log
/nutrition/meals/{mealId}
PATCH Update Meal Log
/nutrition/meals/{mealId}
Request{ "portionSize": 2, "mealType": "dinner", "loggedAt": "2026-04-23T19:00:00Z" }
GET Nutrition Stats
/nutrition/stats?from=YYYY-MM-DD&to=YYYY-MM-DD
Returns totals and daily averages: carbs, protein, fat, calories.
POST Skip Meal
/nutrition/skip
Request{ "mealType": "lunch", "reason": "Not hungry" }
GET Weekly Meal Plan
/nutrition/meal-suggestions?day=MONDAY&meal_type=Breakfast
GET Today's Suggestions
/nutrition/meal-suggestions/today
POST Add Meal Plan Entry
/nutrition/meal-suggestions
Request (multipart/form-data){ "day": "MONDAY", "meal_type": "Breakfast", "content": "Oats with almond milk and berries", "category": "low-gi", "image": "(Binary Upload — optional)" }
PATCH Update Plan Entry
/nutrition/meal-suggestions/{id}
Request{ "content": "Updated meal description", "category": "low-gi" }
DELETE Remove Plan Entry
/nutrition/meal-suggestions/{id}
POST Add Meal to Catalog
/nutrition/catalog
Admin/Doctor only. Adds a new meal definition to the shared catalog.
Request{ "name": "Jollof Rice", "gi_value": 64, "gi_category": "medium" }
PUT Update Catalog Meal
/nutrition/catalog/{id}
Admin/Doctor only. Updates a meal in the shared catalog.
DELETE Remove Catalog Meal
/nutrition/catalog/{id}
Medication Adherence
Prescription management and dose tracking.
POST Add Prescription
/medications
Request{ "name": "Metformin", "doseMg": 500, "doseUnit": "mg", "type": "pill", "mealTiming": "with_food", "scheduleTimes": [ { "hour": 8, "minute": 0 } ], "stockCount": 30, "refillDueDate": "2026-05-23", "notes": "Take with plenty of water" }
Required:
name, type, scheduleTimes,
mealTiming.
GET List Prescriptions
/medications?activeOnly=true
GET Single Prescription
/medications/{id}
Retrieves details for a specific medication.
PATCH Update Prescription
/medications/{id}
Update details of an existing prescription.
Request{ "doseMg": 1000, "stockCount": 50, "notes": "Increased dose per doctor instruction" }
DELETE Remove Prescription
/medications/{id}
POST Log Adherence
/medications/logs
Request{ "medicationId": 1, "scheduledTime": { "hour": 8, "minute": 0 }, "skipped": false, "skipReason": null }
If
skipped: true, provide skipReason. Auto-decrements
stockCount on taken dose.
GET Medication Logs
/medications/{medicationId}/logs
Fetch adherence logs for a specific medication.
GET Adherence History
/medications/logs?from=YYYY-MM-DD&to=YYYY-MM-DD
DELETE Void Adherence Log
/medications/logs/{id}
PATCH Update Adherence Log
/medications/logs/{id}
Request{ "skipped": true, "skipReason": "Forgot to carry medication", "takenAt": null }
Activity & Fitness
Track energy expenditure and fitness metrics.
POST Log Activity
/activity/logs
Request{ "name": "Brisk Walk", "durationMinutes": 30, "caloriesBurned": 150, "steps": 3500, "loggedAt": "2026-04-23T10:00:00Z" }
GET Activity Logs
/activity/logs?from=YYYY-MM-DD&to=YYYY-MM-DD&name=Walk
GET Activity Stats
/activity/stats?from=YYYY-MM-DD&to=YYYY-MM-DD
Returns totals and daily breakdown: steps, calories, minutes. Adds targets if
single-day.
DELETE Remove Activity Log
/activity/logs/{id}
PATCH Update Activity Log
/activity/logs/{id}
Request{ "name": "Intense Running", "durationMinutes": 45, "caloriesBurned": 400, "steps": 6000 }
Clinical Alerts
Automated clinical warnings triggered by metabolic anomalies.
GET Active Alerts
/alerts
POST Create Alert
/alerts
Manually trigger a clinical alert. Severity should be one of: low, medium, high,
critical.
Request{ "title": "Abnormal Feeling", "message": "Patient reports extreme fatigue and blurred vision.", "severity": "high" }
GET Alert Statistics
/alerts/stats
POST Mark Alert as Read
/alerts/{id}/read
DELETE Dismiss Alert
/alerts/{id}
Push & Notification Services
Multi-channel notification dispatch via Firebase and in-app inbox.
GET Notification Inbox
/notifications/inbox?from=YYYY-MM-DD&to=YYYY-MM-DD
POST Mark Notification Read
/notifications/{id}/read
POST Send Custom Push
/notifications/custom-push
Request{ "user_id": "uuid-here", "title": "Dose Reminder", "message": "Time to take your Metformin." }
POST Send Web Alert
/notifications/web-alert
Request{ "user_id": "uuid-here", "title": "Protocol Update", "message": "Your nutrition plan has been revised.", "type": "info" }
Secure Messaging
Direct clinical communication threads.
GET Conversations Inbox
/chats
POST Initiate Conversation
/chats/initiate
Request{ "targetUid": "uuid-of-target-user" }
GET My Thread (Patient)
/chats/my-thread
Patient only. Auto-creates thread with an available consultant.
GET Patient Thread (Doctor)
/chats/user/{userId}
Doctor only. Opens thread with a specific patient.
GET Thread Messages
/chats/{conversationId}/messages
POST Send Message
/chats/{conversationId}/messages
Request{ "content": "How are you feeling today?" }
PATCH Mark Thread as Read
/chats/{conversationId}/read
PUT Edit Message
/chats/messages/{messageId}
Allows the sender to modify message content. Bubble will display an "Edited" tag.
Request{ "content": "Updated clinical advice text..." }
DELETE Delete Message
/chats/messages/{messageId}
Soft-deletes a message. It will no longer appear in thread retrievals.
Knowledge Base
Clinical articles, health tips, and metabolic education.
GET Article Catalog
/education/articles
POST Publish Article
/education/articles
Doctor/Admin only. Supports Markdown content.
Request{ "title": "Metabolic Balance 101", "category": "lifestyle", "content": "# Markdown supported...", "image": "(Binary Upload)" }
GET Daily Health Tips
/education/daily-tips
POST Create Daily Tip
/education/daily-tips
Request{ "title": "Hydration Hack", "message": "Drinking water before meals helps stabilize glucose peaks.", "category": "nutrition" }
GET Frequently Asked Questions
/education/faqs
POST Add FAQ
/education/faqs
Request{ "question": "Can I eat fruit?", "answer": "Yes, but focus on low-GI berries in moderation.", "category": "diet" }
GET Single Article
/education/articles/{id}
PUT Update Article
/education/articles/{id}
DELETE Delete Article
/education/articles/{id}
PUT Update FAQ
/education/faqs/{id}
DELETE Delete FAQ
/education/faqs/{id}
GET Random Health Tip
/education/daily-tips/random
PUT Update Daily Tip
/education/daily-tips/{id}
DELETE Delete Daily Tip
/education/daily-tips/{id}
Consultant Portal
All routes restricted to doctor or admin role.
GET My Professional Profile
/consultant/profile
PUT Update Professional Profile
/consultant/profile
Request{ "displayName": "Dr. Smith", "organization": "City Hospital", "hospitalAffiliation": "NHS Trust", "specialization": "Endocrinology", "experienceYears": 12, "licenseNumber": "MD-99887", "consultationFee": "5000", "availabilityStatus": "available" }
GET Patient Registry
/consultant/patients?search=John&from=YYYY-MM-DD&limit=20
GET Doctor / Staff List
/consultant/doctors?search=Smith&limit=20
POST Register Medical Staff
/consultant/doctors
Admin only. Creates a new doctor or admin account.
Request{ "name": "Dr. Alice Vane", "email": "alice@glucocare.com", "phone": "+2348011223344", "password": "securePassword123", "role": "doctor", "specialization": "Endocrinology" }
PUT Update Medical Staff
/consultant/doctors/{id}
Admin only. Updates basic profile and role for a staff member.
Request{ "name": "Dr. Alice Johnson", "role": "admin" }
DELETE Remove Medical Staff
/consultant/doctors/{id}
Admin only. Revokes access and removes staff record. Cannot delete self.
GET Patient Profile
/consultant/patients/{userId}
GET Patient Glucose Readings
/consultant/patients/{userId}/glucose?from=YYYY-MM-DD&to=YYYY-MM-DD
GET Patient Glucose Stats
/consultant/patients/{userId}/glucose/stats
GET Patient Nutrition Logs
/consultant/patients/{userId}/nutrition?from=YYYY-MM-DD&to=YYYY-MM-DD
GET Patient Nutrition Stats
/consultant/patients/{userId}/nutrition/stats
GET Patient Medications
/consultant/patients/{userId}/medications
GET Patient Activity Logs
/consultant/patients/{userId}/activity?from=YYYY-MM-DD&to=YYYY-MM-DD
GET Patient Activity Stats
/consultant/patients/{userId}/activity/stats
GET Patient Alerts
/consultant/patients/{userId}/alerts
GET Patient Full Report
/consultant/patients/{userId}/report
GET Global Glucose Mesh
/consultant/mesh/glucose?from=YYYY-MM-DD&to=YYYY-MM-DD&limit=50
GET Global Nutrition Mesh
/consultant/mesh/nutrition?from=YYYY-MM-DD&to=YYYY-MM-DD&limit=50
GET Global Activity Mesh
/consultant/mesh/activity?from=YYYY-MM-DD&to=YYYY-MM-DD&limit=50
GET Global Medications Mesh
/consultant/mesh/medications?from=YYYY-MM-DD&to=YYYY-MM-DD&limit=50
GET Global Alerts Mesh
/consultant/mesh/alerts?from=YYYY-MM-DD&to=YYYY-MM-DD&limit=50
GET Global Notifications Mesh
/consultant/mesh/notifications?from=YYYY-MM-DD&to=YYYY-MM-DD&limit=50
© 2026 GlucoCare Systems. Proprietary Clinical Interfacing v1.4.2