openapi: 3.2.0 info: title: SparkyFitness Goals & Personalization API version: 1.0.0 description: API documentation for the SparkyFitness application, providing a comprehensive guide to all available endpoints. Have caution using the API directly, as improper use may lead to data loss or corruption. Also note that the API is subject to change without notice due to heavy development, so always refer to the latest documentation for up-to-date information. It might have flaw and due to vite/nginx internal proxy actual end point accessed via front end URL might be different than hitting them directly on the server. contact: name: SparkyFitness Support servers: - url: https://{host}/api description: Self-hosted SparkyFitness instance (the operator supplies the host). The upstream spec declares the relative base "/api". variables: host: default: sparkyfitness.example.com description: Hostname of your own SparkyFitness deployment. SparkyFitness is self-hosted; there is no vendor-operated API host. security: - apiKeyAuth: [] tags: - name: Goals & Personalization description: Personal goal setting, goal presets, and application preferences. paths: /adaptive-tdee: get: summary: Get adaptive TDEE calculation tags: - Goals & Personalization security: - apiKeyAuth: [] responses: '200': description: Adaptive TDEE details. /goal-presets: post: summary: Create a new goal preset tags: - Goals & Personalization security: - apiKeyAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/GoalPreset' responses: '201': description: Goal preset created successfully. get: summary: Get all goal presets for the user tags: - Goals & Personalization security: - apiKeyAuth: [] responses: '200': description: List of goal presets. content: application/json: schema: type: array items: $ref: '#/components/schemas/GoalPreset' /goal-presets/{id}: get: summary: Get a specific goal preset by ID tags: - Goals & Personalization security: - apiKeyAuth: [] parameters: - in: path name: id required: true schema: type: string format: uuid responses: '200': description: The goal preset. content: application/json: schema: $ref: '#/components/schemas/GoalPreset' put: summary: Update a goal preset tags: - Goals & Personalization security: - apiKeyAuth: [] parameters: - in: path name: id required: true schema: type: string format: uuid requestBody: content: application/json: schema: $ref: '#/components/schemas/GoalPreset' responses: '200': description: Goal preset updated successfully. delete: summary: Delete a goal preset tags: - Goals & Personalization security: - apiKeyAuth: [] parameters: - in: path name: id required: true schema: type: string format: uuid responses: '204': description: Deleted successfully. /goals/by-date/{date}: get: summary: Get goals for a specific date tags: - Goals & Personalization security: - apiKeyAuth: [] parameters: - in: path name: date required: true schema: type: string format: date responses: '200': description: User goals for the specified date. content: application/json: schema: $ref: '#/components/schemas/UserGoal' /goals/for-date: get: summary: Get goals for a date (query param) tags: - Goals & Personalization security: - apiKeyAuth: [] parameters: - in: query name: date required: true schema: type: string format: date responses: '200': description: User goals for the specified date. content: application/json: schema: $ref: '#/components/schemas/UserGoal' /goals/manage-timeline: post: summary: Manage goal timeline (upsert goals over a range) tags: - Goals & Personalization security: - apiKeyAuth: [] requestBody: required: true content: application/json: schema: type: object properties: p_start_date: type: string format: date p_end_date: type: - string - 'null' format: date calories: type: number required: - p_start_date responses: '200': description: Timeline managed successfully. /onboarding: post: summary: Submit user onboarding data tags: - Goals & Personalization security: - apiKeyAuth: [] requestBody: required: true content: application/json: schema: type: object properties: sex: type: string primaryGoal: type: string currentWeight: type: number height: type: number birthDate: type: string format: date activityLevel: type: string targetWeight: type: number required: - sex - primaryGoal - currentWeight - height - birthDate - activityLevel - targetWeight responses: '201': description: Onboarding completed successfully. /onboarding/status: get: summary: Check if the current user has completed onboarding tags: - Goals & Personalization security: - apiKeyAuth: [] responses: '200': description: Onboarding status. content: application/json: schema: $ref: '#/components/schemas/OnboardingStatus' /onboarding/skip: post: summary: Mark onboarding as skipped for the user tags: - Goals & Personalization security: - apiKeyAuth: [] responses: '200': description: Onboarding skipped successfully. /onboarding/reset: post: summary: Reset onboarding status for the user tags: - Goals & Personalization security: - apiKeyAuth: [] responses: '200': description: Onboarding status reset successfully. /user-preferences: put: summary: Update user preferences tags: - Goals & Personalization security: - apiKeyAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UserPreferences' responses: '200': description: Preferences updated successfully. delete: summary: Delete user preferences tags: - Goals & Personalization security: - apiKeyAuth: [] responses: '200': description: Preferences deleted successfully. get: summary: Get user preferences tags: - Goals & Personalization security: - apiKeyAuth: [] responses: '200': description: User preferences. content: application/json: schema: $ref: '#/components/schemas/UserPreferences' post: summary: Upsert user preferences tags: - Goals & Personalization security: - apiKeyAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UserPreferences' responses: '200': description: Preferences upserted successfully. /v2/goal-presets: post: summary: Create a new goal preset tags: - Goals & Personalization security: - apiKeyAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/GoalPreset' responses: '201': description: Goal preset created successfully. '400': description: Validation error. get: summary: Get all goal presets for the authenticated user tags: - Goals & Personalization security: - apiKeyAuth: [] responses: '200': description: List of goal presets. /v2/goal-presets/{id}: get: summary: Get a goal preset by ID tags: - Goals & Personalization security: - apiKeyAuth: [] parameters: - in: path name: id required: true schema: type: string format: uuid responses: '200': description: Goal preset. '400': description: Validation error. '404': description: Goal preset not found. put: summary: Update a goal preset tags: - Goals & Personalization security: - apiKeyAuth: [] parameters: - in: path name: id required: true schema: type: string format: uuid requestBody: content: application/json: schema: $ref: '#/components/schemas/GoalPreset' responses: '200': description: Goal preset updated successfully. '400': description: Validation error. '404': description: Goal preset not found. delete: summary: Delete a goal preset tags: - Goals & Personalization security: - apiKeyAuth: [] parameters: - in: path name: id required: true schema: type: string format: uuid responses: '200': description: Goal preset deleted successfully. '400': description: Validation error. '404': description: Goal preset not found. /weekly-goal-plans: post: summary: Create a new weekly goal plan tags: - Goals & Personalization description: Creates a new weekly goal plan for the authenticated user. security: - apiKeyAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WeeklyGoalPlan' responses: '201': description: The weekly goal plan was created successfully. content: application/json: schema: $ref: '#/components/schemas/WeeklyGoalPlan' '401': description: Unauthorized. '500': description: Internal server error. get: summary: Get all weekly goal plans tags: - Goals & Personalization description: Retrieves all weekly goal plans for the authenticated user. security: - apiKeyAuth: [] responses: '200': description: A list of weekly goal plans. content: application/json: schema: type: array items: $ref: '#/components/schemas/WeeklyGoalPlan' '401': description: Unauthorized. '500': description: Internal server error. /weekly-goal-plans/active: get: summary: Get the active weekly goal plan for a specific date tags: - Goals & Personalization description: Retrieves the active weekly goal plan for the authenticated user on a specific date. security: - apiKeyAuth: [] parameters: - in: query name: date required: true schema: type: string format: date description: The date to check for an active plan (YYYY-MM-DD). responses: '200': description: The active weekly goal plan. content: application/json: schema: $ref: '#/components/schemas/WeeklyGoalPlan' '400': description: Date query parameter is required. '401': description: Unauthorized. '500': description: Internal server error. /weekly-goal-plans/{id}: put: summary: Update an existing weekly goal plan tags: - Goals & Personalization description: Updates an existing weekly goal plan. security: - apiKeyAuth: [] parameters: - in: path name: id required: true schema: type: string format: uuid description: The ID of the weekly goal plan to update. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WeeklyGoalPlan' responses: '200': description: The weekly goal plan was updated successfully. content: application/json: schema: $ref: '#/components/schemas/WeeklyGoalPlan' '401': description: Unauthorized. '404': description: Weekly goal plan not found or not authorized. '500': description: Internal server error. delete: summary: Delete a weekly goal plan tags: - Goals & Personalization description: Deletes a specific weekly goal plan. security: - apiKeyAuth: [] parameters: - in: path name: id required: true schema: type: string format: uuid description: The ID of the weekly goal plan to delete. responses: '204': description: Weekly goal plan deleted successfully. '401': description: Unauthorized. '404': description: Weekly goal plan not found or not authorized. '500': description: Internal server error. components: schemas: OnboardingStatus: type: object properties: onboarding_complete: type: boolean onboarding_skipped: type: boolean WeeklyGoalPlan: type: object properties: id: type: string format: uuid user_id: type: string format: uuid plan_name: type: string start_date: type: string format: date end_date: type: - string - 'null' format: date is_active: type: boolean monday_preset_id: type: - string - 'null' format: uuid tuesday_preset_id: type: - string - 'null' format: uuid wednesday_preset_id: type: - string - 'null' format: uuid thursday_preset_id: type: - string - 'null' format: uuid friday_preset_id: type: - string - 'null' format: uuid saturday_preset_id: type: - string - 'null' format: uuid sunday_preset_id: type: - string - 'null' format: uuid created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - user_id - plan_name - start_date - is_active UserGoal: type: object properties: goal_date: type: - string - 'null' format: date calories: type: number protein: type: number carbs: type: number fat: type: number water_goal_ml: type: number protein_percentage: type: number carbs_percentage: type: number fat_percentage: type: number target_exercise_calories_burned: type: - number - 'null' target_exercise_duration_minutes: type: - integer - 'null' GoalPreset: type: object properties: id: type: string format: uuid user_id: type: string format: uuid preset_name: type: string calories: type: number protein: type: number carbs: type: number fat: type: number water_goal: type: number protein_percentage: type: number carbs_percentage: type: number fat_percentage: type: number required: - preset_name - calories UserPreferences: type: object properties: user_id: type: string format: uuid language: type: string theme: type: string timezone: type: string unit_system: type: string enum: - metric - imperial meal_calorie_distribution: type: object calorie_safety_floor_mode: type: string enum: - standard - custom - disabled description: Controls adaptive calorie-target clamping. Standard uses the recommended RMR/clinical floor, custom uses calorie_safety_floor_value, and disabled only reports health warnings. calorie_safety_floor_value: type: integer minimum: 800 maximum: 5000 description: Custom calorie safety floor in kcal/day. Used when calorie_safety_floor_mode is custom. securitySchemes: apiKeyAuth: type: apiKey in: header name: x-api-key description: API key authentication via x-api-key header. x-provenance: generated: '2026-08-27' method: derived source: https://github.com/CodeWithCJ/SparkyFitness — assembled from the project's own swagger-jsdoc configuration (SparkyFitnessServer/config/swagger.ts) and the 419 @swagger JSDoc blocks in SparkyFitnessServer/routes/**, using the same scan paths and the same cookieAuth->apiKeyAuth post-processing the server applies. This is the identical document a running instance serves at GET /api/api-docs/json (Swagger UI at /api/api-docs/swagger, ReDoc at /api/api-docs/redoc). note: 'Not fetched from a live host: SparkyFitness is self-hosted and the project operates no public instance, so the contract can only be read from the source that generates it. Upstream sets no operationIds; paths+methods are the stable identifiers.' upstream_version: server package.json 1.6.4 (release v1.6.4, 2026-08-27)