User Management & Plans API

User profiles, AI-generated plans, daily view, and progress tracking.

Manage user profiles, generate AI-powered fitness plans, view combined daily schedules, and track progress. All endpoints require X-API-Key and Authorization: Bearer <token>.

User Profile

Get Profile GET /users/me

Get the current user's profile including coach information.

{
  "success": true,
  "data": {
    "user": {
      "id": 1,
      "email": "user@example.com",
      "name": "Jane Doe",
      "role": "user",
      "profile": {
        "age": 28,
        "gender": "female",
        "height": 170,
        "weight": 65,
        "fitnessLevel": "intermediate",
        "fitnessGoal": "weight_loss"
      },
      "settings": {
        "notifications": true
      },
      "coach": {
        "id": 5,
        "name": "Coach Mike"
      }
    }
  }
}

Update Profile PUT /users/me

Update the current user's profile and settings. Only include the fields you want to change.

{
  "profile": {
    "weight": 63,
    "fitnessLevel": "advanced"
  },
  "settings": {
    "notifications": false
  }
}

Delete Account DELETE /users/me

Permanently delete the current user's account and all associated data.

Irreversible

This action cannot be undone. All user data, plans, progress, and sessions are permanently deleted.

Daily Plan

Get Daily Plan GET /users/me/daily-plan

Get the combined daily plan -- workouts, meals, and classes unified into a single view.

Parameter	Type	Description
`date`	string	Date in `YYYY-MM-DD` format (defaults to today)

{
  "success": true,
  "data": {
    "date": "2026-02-28",
    "workout": {
      "name": "Upper Body Strength",
      "exercises": [ ]
    },
    "meals": [
      { "mealType": "breakfast", "name": "Greek Yogurt Bowl" },
      { "mealType": "lunch", "name": "Grilled Chicken Salad" },
      { "mealType": "dinner", "name": "Salmon with Vegetables" }
    ],
    "classes": [
      { "name": "Evening Yoga", "time": "18:00", "duration": 60 }
    ]
  }
}

Building a daily agenda

The daily plan endpoint is designed for building a "today" screen. It combines data from the user's active workout plan, nutrition plan, and class plan into a single response so you don't need to make three separate calls.

Workout Plans

AI-generated workout plans are saved to the user's account and broken down into daily workouts with exercises, sets, reps, and instructions.

Generate Plan POST /users/me/workout-plan

Generate an AI-powered workout plan and save it to the account.

{
  "preferences": {
    "workoutDays": ["mon", "wed", "fri", "sat"],
    "intensity": "medium",
    "duration": "6 weeks"
  },
  "overrides": {
    "fitnessLevel": "intermediate",
    "goals": ["weight_loss", "strength"],
    "equipment": ["dumbbells"],
    "focusAreas": ["full_body"],
    "workoutTypes": ["strength_training"],
    "sessionDuration": 45
  }
}

{
  "success": true,
  "data": {
    "planId": 1,
    "title": "Intermediate Fat Loss & Strength Program - 6 weeks",
    "description": "This fat loss program utilizes higher repetition ranges...",
    "daysPerWeek": 4,
    "workoutDays": ["mon", "wed", "fri", "sat"]
  }
}

Preferences control scheduling:

Field	Type	Description
`workoutDays`	string[]	Specific days (`mon`..`sun`). Determines plan structure and `daysPerWeek`.
`daysPerWeek`	number	Fallback if `workoutDays` not provided.
`intensity`	string	`low`, `medium`, or `high`.
`duration`	string	Plan duration, e.g. `"6 weeks"`.

Overrides control what the AI optimises for. Values take precedence over the stored profile:

Field	Type	Description
`fitnessLevel`	string	`beginner`, `intermediate`, `advanced`, or `elite`.
`goals`	string[]	e.g. `["weight_loss", "strength"]`. Drives exercise selection and plan title.
`equipment`	string[]	Available equipment.
`focusAreas`	string[]	Body-part focus, e.g. `["upper_body", "core"]`.
`workoutTypes`	string[]	e.g. `["strength_training", "hiit"]`.
`sessionDuration`	number	Minutes per session.
`injuries`	string[]	Constraints for exercise selection.

Profile-based generation

If no overrides are provided, the plan is generated entirely from the user's stored profile (fitness level, goals, equipment, injuries, and preferred workout days from onboarding). Override values take precedence, so the generated plan title, description, and structure will match what you submit.

Get Active Plan GET /users/me/workout-plan

Get the current user's active workout plan with full details.

{
  "success": true,
  "data": {
    "plan": {
      "id": 1,
      "title": "Intermediate Strength Program",
      "duration": "6 weeks",
      "daysPerWeek": 4,
      "workoutDays": ["mon", "wed", "fri", "sat"],
      "createdAt": "2026-02-20T10:00:00Z",
      "weeks": [
        {
          "week": 1,
          "days": [
            { "day": "mon", "dayLabel": "Monday", "name": "Upper Body", "exerciseCount": 6 },
            { "day": "wed", "dayLabel": "Wednesday", "name": "Lower Body", "exerciseCount": 5 },
            { "day": "fri", "dayLabel": "Friday", "name": "Upper Body Pull", "exerciseCount": 6 },
            { "day": "sat", "dayLabel": "Saturday", "name": "Full Body", "exerciseCount": 5 }
          ]
        }
      ]
    }
  }
}

Get Workout Day GET /users/me/workout-plan/day/:dayId

Get a specific workout day by ID with all exercises, sets, reps, and instructions.

{
  "success": true,
  "data": {
    "day": {
      "dayId": 1,
      "name": "Upper Body Strength",
      "exercises": [
        {
          "name": "Dumbbell Bench Press",
          "sets": 3,
          "reps": "10-12",
          "restTime": "60-90 seconds",
          "instructions": "Lie flat on bench, press dumbbells upward..."
        }
      ]
    }
  }
}

Cancel Plan DELETE /users/me/workout-plan

Cancel the current user's active workout plan.

{
  "success": true,
  "data": {
    "message": "Workout plan cancelled"
  }
}

Nutrition Plans

Generate Plan POST /users/me/nutrition-plan

Generate an AI-powered nutrition plan.

{
  "preferences": {
    "mealTypes": ["breakfast", "lunch", "dinner"],
    "targetCalories": 1800
  }
}

Get Active Plan GET /users/me/nutrition-plan

Get the full nutrition plan with meals and macros.

{
  "success": true,
  "data": {
    "plan": {
      "id": 2,
      "title": "Balanced Nutrition Plan",
      "targetCalories": 1800,
      "duration": "7 days",
      "weeks": [
        {
          "weekId": 1,
          "days": [
            {
              "day": 1,
              "meals": [
                { "mealType": "breakfast", "name": "Greek Yogurt Bowl", "calories": 320 },
                { "mealType": "lunch", "name": "Grilled Chicken Salad", "calories": 480 },
                { "mealType": "dinner", "name": "Salmon with Vegetables", "calories": 550 }
              ]
            }
          ]
        }
      ]
    }
  }
}

Get Week Detail GET /users/me/nutrition-plan/week/:weekId

Get a specific nutrition week including meals and a generated shopping list.

{
  "success": true,
  "data": {
    "week": {
      "weekId": 1,
      "days": [ ],
      "shoppingList": [
        { "item": "Chicken breast", "quantity": "1kg", "category": "Protein" },
        { "item": "Greek yogurt", "quantity": "500g", "category": "Dairy" },
        { "item": "Mixed greens", "quantity": "2 bags", "category": "Vegetables" }
      ]
    }
  }
}

Cancel Plan DELETE /users/me/nutrition-plan

Cancel the active nutrition plan.

{
  "success": true,
  "data": {
    "message": "Nutrition plan cancelled"
  }
}

Class Plans

Generate Plan POST /users/me/class-plan

Generate an AI class schedule matching the user to optimal classes.

{
  "preferences": {
    "workoutDays": ["mon", "wed", "fri"],
    "duration": "4 weeks",
    "intensity": "medium",
    "focusAreas": ["cardio", "strength"]
  },
  "overrides": {
    "fitnessLevel": "intermediate",
    "goals": ["weight_loss", "flexibility"],
    "classTypes": ["H.I.I.T.", "YOGA"],
    "sessionDuration": 60
  }
}

Preferences control scheduling:

Field	Type	Description
`workoutDays`	string[]	Specific days (`mon`..`sun`). Determines plan structure and `classesPerWeek`.
`daysPerWeek` / `classesPerWeek`	number	Fallback if `workoutDays` not provided.
`duration`	string	Plan duration, e.g. `"4 weeks"`.
`intensity`	string	`low`, `medium`, or `high`.
`focusAreas`	string[]	Areas to focus on, e.g. `["cardio", "strength"]`.

Overrides control what the AI optimises for. Values take precedence over the stored profile:

Field	Type	Description
`fitnessLevel`	string	`beginner`, `intermediate`, `advanced`, or `elite`.
`goals`	string[]	e.g. `["weight_loss", "flexibility"]`. Drives class selection and plan title.
`classTypes`	string[]	Preferred class categories, e.g. `["YOGA", "H.I.I.T."]`.
`equipment`	string[]	Available equipment.
`sessionDuration`	number	Max class duration in minutes.

Get Active Plan GET /users/me/class-plan

Get the user's active AI-generated class schedule.

{
  "success": true,
  "data": {
    "plan": {
      "id": 3,
      "daysPerWeek": 3,
      "workoutDays": ["mon", "wed", "fri"],
      "duration": "4 weeks",
      "schedule": [
        {
          "day": "mon",
          "dayLabel": "Monday",
          "class": { "id": 12, "name": "Morning Yoga Flow", "time": "07:00", "duration": 60 }
        },
        {
          "day": "wed",
          "dayLabel": "Wednesday",
          "class": { "id": 8, "name": "HIIT Blast", "time": "18:00", "duration": 30 }
        },
        {
          "day": "fri",
          "dayLabel": "Friday",
          "class": { "id": 5, "name": "Strength Basics", "time": "17:00", "duration": 45 }
        }
      ]
    }
  }
}

Cancel Plan DELETE /users/me/class-plan

Cancel the active class plan.

{
  "success": true,
  "data": {
    "message": "Class plan cancelled"
  }
}

Progress Tracking

Log fitness activities and track progress over time.

Get Progress GET /progress

Retrieve progress data for the current user.

Parameter	Type	Description
`startDate`	string	Start date (`YYYY-MM-DD`)
`endDate`	string	End date (`YYYY-MM-DD`)
`category`	string	Filter by category

Log Workout POST /progress/workout

Log a completed workout with exercises and performance data.

{
  "workoutId": 1,
  "completedAt": "2026-02-28T07:30:00Z",
  "duration": 45,
  "exercises": [
    {
      "exerciseId": 101,
      "sets": [
        { "weight": 60, "reps": 10 },
        { "weight": 65, "reps": 8 }
      ]
    }
  ],
  "caloriesBurned": 350,
  "perceivedExertion": 7
}

Log Nutrition POST /progress/nutrition

Log food intake for a meal.

{
  "mealType": "breakfast",
  "logDate": "2026-02-28",
  "foods": [
    {
      "name": "Greek Yogurt",
      "calories": 130,
      "protein": 15,
      "carbs": 9,
      "fat": 4
    }
  ]
}

Log Body Metrics POST /progress/body-metrics

Log body measurements and composition data.

{
  "date": "2026-02-28",
  "weight": 63,
  "bodyFat": 18.5
}

Log Water POST /progress/water

Log water intake.

{
  "amount": 500,
  "unit": "ml",
  "loggedAt": "2026-02-28T10:30:00Z",
  "source": "water_bottle"
}

Complete User Journey

Here is how to build a full user lifecycle:

Call POST /users/me/workout-plan and POST /users/me/nutrition-plan to generate personalised plans from the user's profile.

Show the user what is on their plate today with GET /users/me/daily-plan. Combine workouts, meals, and scheduled classes in a single view.

As the user completes workouts, log them with POST /progress/workout. Track meals with POST /progress/nutrition and water with POST /progress/water.

Fetch progress data with GET /progress and build dashboard visualisations showing trends over time.

FAQ

Can a user have multiple active plans?

A user can have one active plan of each type: one workout plan, one nutrition plan, and one class plan. Generating a new plan replaces the existing one.

What happens if the user's profile is incomplete?

The AI will generate plans with whatever data is available, but more complete profiles produce better results. At minimum, the user should have fitnessLevel and fitnessGoal set.

How is the daily plan built?

The daily plan endpoint combines data from the user's active workout plan (which day it is in the programme), nutrition plan (meals for that day), and class plan (scheduled classes). It is a read-only view -- changes are made to individual plans.