API Reference

🔌 API Reference

Complete documentation of all REST API endpoints available on the FitTrack AI backend server (http://localhost:1337).

---

🔐 Authentication Header

All protected endpoints require the HTTP Authorization header:

Authorization: Bearer <JWT_TOKEN>

---

👤 1. Authentication & Profile Routes

Register Local Account

• Endpoint: POST /api/auth/local/register
• Rate Limit: 5 requests / 15 minutes
• Body:

{
  "username": "jashan",
  "email": "jashan@example.com",
  "password": "Password123!"
}

• Response (200 OK): { "jwt": "...", "user": { "id": "...", "username": "jashan", "email": "..." } }

Login Local Account

• Endpoint: POST /api/auth/local
• Rate Limit: 5 requests / 15 minutes
• Body: { "identifier": "jashan@example.com", "password": "Password123!" }
• Response (200 OK): { "jwt": "...", "user": { ... } }

Google OAuth Callback & Session Exchange

• Initiate: GET /api/connect/google (Redirects to Google consent)
• Callback: GET /api/connect/google/callback (Redirects to frontend with #access_token=)
• Exchange Token: POST /api/auth/google/callback
  • Body: { "access_token": "ya29..." }
  • Response (200 OK): { "jwt": "...", "user": { "id": "...", "username": "...", "googleLinked": true } }

Email Verification

• Confirm Token: POST /api/auth/verify-email
  • Body: { "token": "64_char_hex_token" }
  • Response (200 OK): { "message": "Email verified successfully. You may now sign in." }
• Resend Token: POST /api/auth/resend-verification
  • Rate Limit: 3 requests / 15 minutes
  • Body: { "email": "user@example.com" }

Password Management (Add / Update)

• Endpoint: POST /api/users/me/password
• Access: Private (Bearer JWT)
• Rate Limit: 5 requests / 15 minutes
• Body (Set first password on OAuth): { "newPassword": "SecurePassword123!" }
• Body (Update existing password): { "currentPassword": "OldPassword123!", "newPassword": "SecurePassword123!" }
• Step-Up Requirement: Stale sessions (>15 min) receive 401 reauth_required.

Password Reset Flow (Brevo HTTPS)

• Request Link: POST /api/password-reset/request
  • Rate Limit: 3 requests / 1 hour
  • Cooldown: 60-second active token debouncing (prevents duplicate dispatches)
  • Body: { "email": "user@example.com" }
• Validate Token: GET /api/password-reset/validate?code=TOKEN
  • Response (200 OK): { "valid": true, "message": "Token is valid." }
• Reset Password: POST /api/password-reset/reset
  • Body: { "code": "TOKEN", "newPassword": "SecurePassword123!" }
  • Password History: Enforces rolling 5-password history protection.

Email Webhook Receiver

• Endpoint: POST /api/webhooks/email?key=YOUR_BREVO_WEBHOOK_KEY
• Access: Timing-safe HMAC / Key Header
• Rate Limit: 120 requests / 1 minute
• Body: Event array from Brevo (delivered, hard_bounce, soft_bounce, spam)

Fetch Authenticated User

• Endpoint: GET /api/users/me
• Access: Private (Bearer JWT)
• Response (200 OK): Current user profile with height, weight, daily goals, and onboarding answers.

Update Profile & Username

• Endpoint: PUT /api/users/:id or PUT /api/users/me
• Access: Private (Bearer JWT)
• Body:

{
  "username": "jashan_fitness",
  "age": 28,
  "height": 180,
  "weight": 78,
  "goal": "maintain",
  "dailycaloriesintake": 2200,
  "dailycaloriesburned": 600
}

• Validation: Username is validated for 3–30 characters and uniqueness. Returns 409 Conflict if taken.

---

🥗 2. Food & Nutrition Logging (/api/foodlogs)

Method	Endpoint	Description	Access
GET	/api/foodlogs?date=YYYY-MM-DD	Retrieve all meals logged for specific date	Private
POST	/api/foodlogs	Create a new food log entry	Private
DELETE	/api/foodlogs/:id	Remove a food log record	Private

Create Food Log Body

{
  "name": "Grilled Chicken Breast with Rice",
  "calories": 450,
  "protein": 42,
  "carbs": 48,
  "fat": 6,
  "mealType": "Lunch",
  "date": "2026-09-14"
}

---

🏃 3. Activity & Exercise Logging (/api/activitylogs)

Method	Endpoint	Description	Access
GET	/api/activitylogs?date=YYYY-MM-DD	Retrieve all workouts for date	Private
POST	/api/activitylogs	Log workout with duration and calories burned	Private
DELETE	/api/activitylogs/:id	Remove an activity entry	Private

---

💧 4. Water Intake Logging (/api/waterlogs)

Method	Endpoint	Description	Access
GET	/api/waterlogs?date=YYYY-MM-DD	Fetch total water volume consumed for date	Private
POST	/api/waterlogs	Log water intake ({ "amount": 250, "date": "2026-09-14" })	Private
DELETE	/api/waterlogs/:id	Delete water entry	Private

---

🤖 5. Generative AI Endpoints

Chat with FitBot Coach

• Endpoint: POST /api/ai-assistant/chat
• Access: Private (Bearer JWT)
• Rate Limit:
  • aiLimiter: 30 requests / 1 minute (per IP)
  • aiUserLimiter: 20 requests / 1 minute (per user account post-JWT)
• Payload Constraints & Truncation:
  • messages: Array of max 50 items (older items gracefully truncated if exceeded).
  • message.content: Max 8,000 characters per message.
  • totalChars: Max 40,000 characters per conversation payload.
  • userContext: Max 4,000 characters.
• Resilience Features:
  • 1–2 exponential retries on network hiccups, timeouts, and 429/5xx status codes.
  • Automatic fallback model failover (OPENROUTER_FALLBACK_MODEL).
  • Structured JSON validation and repair retry for Activity Planner.
  • 5-minute in-memory query cache for identical prompt hashes.
  • Graceful 503 Service Unavailable on upstream provider outages.
• Body:

{
  "messages": [
    { "role": "user", "content": "Suggest a high-protein post-workout snack under 200 calories" }
  ],
  "userContext": "Target: 2200 kcal, Weight: 78kg"
}

• Response (200 OK):

{
  "success": true,
  "reply": "Greek yogurt (150g) with a handful of fresh berries gives you 17g of protein and only 130 kcal!",
  "usage": {
    "prompt_tokens": 820,
    "completion_tokens": 42,
    "total_tokens": 862
  },
  "model": "openai/gpt-4o-mini",
  "cached": false
}

AI Food Snap (Vision Analysis)

• Endpoint: POST /api/image-analysis
• Access: Private (Bearer JWT)
• Rate Limit: 20 requests / 1 minute
• Content-Type: multipart/form-data
• Form Field: image (Binary file upload)
• Response (200 OK):

{
  "foodName": "Avocado Toast with Poached Egg",
  "calories": 320,
  "macros": {
    "protein": 14,
    "carbs": 24,
    "fat": 18
  }
}

Natural Language Nutrition Estimator

• Endpoint: POST /api/food-estimate
• Access: Private (Bearer JWT)
• Rate Limit: 20 requests / 1 minute
• Body: { "description": "1 bowl oatmeal with almond milk and banana" }
• Response (200 OK): { "calories": 290, "protein": 7, "carbs": 52, "fat": 5 }

Calorie Burn Estimator

• Endpoint: POST /api/calorie-estimate
• Access: Private (Bearer JWT)
• Rate Limit: 20 requests / 1 minute
• Body: { "activity": "Swimming freestyle", "duration": 45 }
• Response (200 OK): { "caloriesBurned": 380 }

---

🎥 6. Media & Workout Video Search

Workout Video Query (RapidAPI Proxy)

• Endpoint: GET /api/youtube/search?q=full+body+hiit
• Access: Private (Bearer JWT)
• Rate Limit: 30 requests / 1 minute
• Response (200 OK):

{
  "contents": [
    {
      "video": {
        "videoId": "abc123xyz",
        "title": "20 Min Full Body HIIT Workout",
        "thumbnails": [{ "url": "https://..." }]
      }
    }
  ]
}

---

🩺 7. System Health & Observability

Uptime & Database Health Check

• Endpoint: GET /api/health
• Access: Public
• Response (200 OK or 503 Service Unavailable):

{
  "status": "ok",
  "uptime": 1420,
  "timestamp": "2026-09-27T12:00:00.000Z",
  "database": "connected"
}

• X-Request-Id Correlation Header: Returned on all responses (X-Request-Id: 8b09a266-b698-4ec6-b48a-46ba1bef9bda) for trace correlation across structured logs.