SparkyFitness

SparkyFitness Goals & Personalization API

Personal goal setting, goal presets, and application preferences.

Documentation GitHub OpenAPI

Operations 27

GET /adaptive-tdee Get adaptive TDEE calculation #

POST /goal-presets Create a new goal preset #

GET /goal-presets Get all goal presets for the user #

GET /goal-presets/{id} Get a specific goal preset by ID #

PUT /goal-presets/{id} Update a goal preset #

DELETE /goal-presets/{id} Delete a goal preset #

GET /goals/by-date/{date} Get goals for a specific date #

GET /goals/for-date Get goals for a date (query param) #

POST /goals/manage-timeline Manage goal timeline (upsert goals over a range) #

POST /onboarding Submit user onboarding data #

GET /onboarding/status Check if the current user has completed onboarding #

POST /onboarding/skip Mark onboarding as skipped for the user #

POST /onboarding/reset Reset onboarding status for the user #

PUT /user-preferences Update user preferences #

DELETE /user-preferences Delete user preferences #

GET /user-preferences Get user preferences #

POST /user-preferences Upsert user preferences #

POST /v2/goal-presets Create a new goal preset #

GET /v2/goal-presets Get all goal presets for the authenticated user #

GET /v2/goal-presets/{id} Get a goal preset by ID #

PUT /v2/goal-presets/{id} Update a goal preset #

DELETE /v2/goal-presets/{id} Delete a goal preset #

POST /weekly-goal-plans Create a new weekly goal plan #

GET /weekly-goal-plans Get all weekly goal plans #

GET /weekly-goal-plans/active Get the active weekly goal plan for a specific date #

PUT /weekly-goal-plans/{id} Update an existing weekly goal plan #

DELETE /weekly-goal-plans/{id} Delete a weekly goal plan #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this

find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/sparkyfitness-goals-personalization-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

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.
  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.
      operationId: getAdaptiveTdee
      x-operation-id-source: derived
  /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.
      operationId: postGoalPresets
      x-operation-id-source: derived
    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'
      operationId: getGoalPresets
      x-operation-id-source: derived
  /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'
      operationId: getGoalPresetsById
      x-operation-id-source: derived
    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.
      operationId: putGoalPresetsById
      x-operation-id-source: derived
    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.
      operationId: deleteGoalPresetsById
      x-operation-id-source: derived
  /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'
      operationId: getGoalsByDateByDate
      x-operation-id-source: derived
  /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'
      operationId: getGoalsForDate
      x-operation-id-source: derived
  /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.
      operationId: postGoalsManageTimeline
      x-operation-id-source: derived
  /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.
      operationId: postOnboarding
      x-operation-id-source: derived
  /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'
      operationId: getOnboardingStatus
      x-operation-id-source: derived
  /onboarding/skip:
    post:
      summary: Mark onboarding as skipped for the user
      tags:
      - Goals & Personalization
      security:
      - apiKeyAuth: []
      responses:
        '200':
          description: Onboarding skipped successfully.
      operationId: postOnboardingSkip
      x-operation-id-source: derived
  /onboarding/reset:
    post:
      summary: Reset onboarding status for the user
      tags:
      - Goals & Personalization
      security:
      - apiKeyAuth: []
      responses:
        '200':
          description: Onboarding status reset successfully.
      operationId: postOnboardingReset
      x-operation-id-source: derived
  /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.
      operationId: putUserPreferences
      x-operation-id-source: derived
    delete:
      summary: Delete user preferences
      tags:
      - Goals & Personalization
      security:
      - apiKeyAuth: []
      responses:
        '200':
          description: Preferences deleted successfully.
      operationId: deleteUserPreferences
      x-operation-id-source: derived
    get:
      summary: Get user preferences
      tags:
      - Goals & Personalization
      security:
      - apiKeyAuth: []
      responses:
        '200':
          description: User preferences.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserPreferences'
      operationId: getUserPreferences
      x-operation-id-source: derived
    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.
      operationId: postUserPreferences
      x-operation-id-source: derived
  /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.
      operationId: postV2GoalPresets
      x-operation-id-source: derived
    get:
      summary: Get all goal presets for the authenticated user
      tags:
      - Goals & Personalization
      security:
      - apiKeyAuth: []
      responses:
        '200':
          description: List of goal presets.
      operationId: getV2GoalPresets
      x-operation-id-source: derived
  /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.
      operationId: getV2GoalPresetsById
      x-operation-id-source: derived
    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.
      operationId: putV2GoalPresetsById
      x-operation-id-source: derived
    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.
      operationId: deleteV2GoalPresetsById
      x-operation-id-source: derived
  /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.
      operationId: postWeeklyGoalPlans
      x-operation-id-source: derived
    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.
      operationId: getWeeklyGoalPlans
      x-operation-id-source: derived
  /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.
      operationId: getWeeklyGoalPlansActive
      x-operation-id-source: derived
  /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.
      operationId: putWeeklyGoalPlansById
      x-operation-id-source: derived
    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.
      operationId: deleteWeeklyGoalPlansById
      x-operation-id-source: derived
components:
  schemas:
    OnboardingStatus:
      type: object
      properties:
        onboarding_complete:
          type: boolean
        onboarding_skipped:
          type: boolean
    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
    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'
    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)