SparkyFitness Goals & Personalization API

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)