{
  "endpoint": "/api/calculate-deficit",
  "method": "GET",
  "description": "Calculates the target daily calorie intake and deficit target for weight loss.",
  "parameters": {
    "gender": { "type": "string", "enum": ["male", "female"], "required": true },
    "age": { "type": "integer", "minimum": 15, "required": true },
    "weightKg": { "type": "number", "required": true },
    "heightCm": { "type": "number", "required": true },
    "activityLevel": { "type": "string", "enum": ["sedentary", "light", "moderate", "active", "extreme"], "required": true },
    "weeklyLossGoalKg": { "type": "number", "enum": [0.25, 0.5, 0.75, 1.0], "required": true },
    "targetWeightKg": { "type": "number", "required": true }
  },
  "mathematical_model": {
    "bmr": "Mifflin-St Jeor Equation",
    "tdee": "BMR * activity_multiplier",
    "deficit_kcal": "weeklyLossGoalKg * 7700 / 7",
    "safety_floor": { "male": 1500, "female": 1200 }
  },
  "sample_response": {
    "maintenanceCalories": 2380,
    "targetCalories": 1830,
    "deficit": 550,
    "daysToGoal": 98,
    "weeksToGoal": 14.0,
    "isFloorClipped": false
  }
}