SparkyFitness AI & Insights API

openapi: 3.2.0
info:
  title: SparkyFitness AI & Insights 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: AI & Insights
  description: AI-powered chat assistance, reports, trends, and analytical insights.
paths:
  /chat:
    post:
      summary: Process a chat message or save AI service settings
      tags:
      - AI & Insights
      security:
      - apiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                messages:
                  type: array
                  items:
                    type: object
                    properties:
                      role:
                        type: string
                        enum:
                        - user
                        - assistant
                        - system
                      content:
                        type: string
                service_config_id:
                  type: string
                  format: uuid
                action:
                  type: string
                  enum:
                  - save_ai_service_settings
                service_data:
                  type: object
      responses:
        '200':
          description: Successful response from the AI service or confirmation of settings save.
        '400':
          description: Bad request.
        '404':
          description: Not found.
        '500':
          description: Server error.
  /chat/clear-old-history:
    post:
      summary: Clear old chat history for the authenticated user
      tags:
      - AI & Insights
      security:
      - apiKeyAuth: []
      responses:
        '200':
          description: Confirmation of successful clearing.
        '500':
          description: Server error.
  /chat/ai-service-settings:
    get:
      summary: Retrieve AI service settings for the authenticated user
      tags:
      - AI & Insights
      security:
      - apiKeyAuth: []
      responses:
        '200':
          description: List of AI service settings.
        '403':
          description: Forbidden.
        '500':
          description: Server error.
  /chat/ai-service-settings/active:
    get:
      summary: Retrieve the active AI service setting for the authenticated user
      tags:
      - AI & Insights
      security:
      - apiKeyAuth: []
      responses:
        '200':
          description: Active AI service setting.
        '403':
          description: Forbidden.
        '404':
          description: Not found.
        '500':
          description: Server error.
  /chat/ai-service-settings/test:
    post:
      summary: Test an AI service connection with a minimal live completion
      description: 'Runs a minimal completion against the supplied provider config without persisting anything. Returns HTTP 200 for both pass (`ok: true`) and provider failure (`ok: false`, with a `category`), so the client can show a friendly, category-specific message instead of a generic API error. On edit, a blank `api_key` falls back to the stored encrypted key.

        '
      tags:
      - AI & Insights
      security:
      - apiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - service_type
              properties:
                id:
                  type: string
                  format: uuid
                service_type:
                  type: string
                api_key:
                  type: string
                custom_url:
                  type: string
                model_name:
                  type: string
      responses:
        '200':
          description: Test result (pass or provider failure).
        '400':
          description: Bad request (malformed body or missing required model).
        '403':
          description: Forbidden (per-user AI config disabled, or non-admin testing a global service).
        '500':
          description: Server error.
  /chat/ai-service-settings/{id}:
    delete:
      summary: Delete an AI service setting
      tags:
      - AI & Insights
      security:
      - apiKeyAuth: []
      parameters:
      - in: path
        name: id
        schema:
          type: string
          format: uuid
        required: true
      responses:
        '200':
          description: Confirmation of successful deletion.
        '400':
          description: Bad request.
        '403':
          description: Forbidden.
        '404':
          description: Not found.
        '500':
          description: Server error.
  /chat/sparky-chat-history:
    get:
      summary: Retrieve Sparky chat history for the authenticated user
      tags:
      - AI & Insights
      security:
      - apiKeyAuth: []
      responses:
        '200':
          description: Chat history.
        '403':
          description: Forbidden.
        '500':
          description: Server error.
  /chat/sparky-chat-history/entry/{id}:
    get:
      summary: Retrieve a single Sparky chat history entry
      tags:
      - AI & Insights
      security:
      - apiKeyAuth: []
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Chat history entry.
        '400':
          description: Bad request.
        '403':
          description: Forbidden.
        '404':
          description: Not found.
        '500':
          description: Server error.
  /chat/sparky-chat-history/{id}:
    put:
      summary: Update a Sparky chat history entry
      tags:
      - AI & Insights
      security:
      - apiKeyAuth: []
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Updated chat history entry.
        '400':
          description: Bad request.
        '403':
          description: Forbidden.
        '404':
          description: Not found.
        '500':
          description: Server error.
    delete:
      summary: Delete a Sparky chat history entry
      tags:
      - AI & Insights
      security:
      - apiKeyAuth: []
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Confirmation of successful deletion.
        '400':
          description: Bad request.
        '403':
          description: Forbidden.
        '404':
          description: Not found.
        '500':
          description: Server error.
  /chat/clear-all-history:
    post:
      summary: Clear all Sparky chat history for the authenticated user
      tags:
      - AI & Insights
      security:
      - apiKeyAuth: []
      responses:
        '200':
          description: Confirmation of successful clearing.
        '403':
          description: Forbidden.
        '500':
          description: Server error.
  /chat/save-history:
    post:
      summary: Save a Sparky chat history entry
      tags:
      - AI & Insights
      security:
      - apiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                content:
                  type: string
                messageType:
                  type: string
                metadata:
                  type: object
      responses:
        '201':
          description: Confirmation of successful saving.
        '400':
          description: Bad request.
        '403':
          description: Forbidden.
        '500':
          description: Server error.
  /chat/food-options:
    post:
      summary: Generate food options for a given food name and unit
      tags:
      - AI & Insights
      security:
      - apiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                foodName:
                  type: string
                unit:
                  type: string
                service_config_id:
                  type: string
                  format: uuid
      responses:
        '200':
          description: Raw AI JSON text containing the generated food options, returned as a string in `content`.
        '400':
          description: Missing service_config_id.
        '404':
          description: No AI service configured, or its API key / custom URL is missing.
        '422':
          description: AI response unusable (refused, truncated, empty, invalid JSON, or unsupported provider).
        '500':
          description: Server error.
        '502':
          description: Upstream AI service error.
        '504':
          description: AI service timed out.
  /reports:
    get:
      summary: Get comprehensive reports data
      tags:
      - AI & Insights
      security:
      - apiKeyAuth: []
      parameters:
      - in: query
        name: userId
        required: true
        schema:
          type: string
          format: uuid
      - in: query
        name: startDate
        required: true
        schema:
          type: string
          format: date
      - in: query
        name: endDate
        required: true
        schema:
          type: string
          format: date
      responses:
        '200':
          description: Reports data.
  /reports/mini-nutrition-trends:
    get:
      summary: Get mini nutrition trends
      tags:
      - AI & Insights
      security:
      - apiKeyAuth: []
      parameters:
      - in: query
        name: userId
        required: true
        schema:
          type: string
          format: uuid
      - in: query
        name: startDate
        required: true
        schema:
          type: string
          format: date
      - in: query
        name: endDate
        required: true
        schema:
          type: string
          format: date
      responses:
        '200':
          description: Mini nutrition trends.
  /reports/nutrition-trends-with-goals:
    get:
      summary: Get nutrition trends with goals
      tags:
      - AI & Insights
      security:
      - apiKeyAuth: []
      parameters:
      - in: query
        name: userId
        required: true
        schema:
          type: string
          format: uuid
      - in: query
        name: startDate
        required: true
        schema:
          type: string
          format: date
      - in: query
        name: endDate
        required: true
        schema:
          type: string
          format: date
      responses:
        '200':
          description: Nutrition trends with goals.
  /reports/exercise-dashboard:
    get:
      summary: Get exercise dashboard data
      tags:
      - AI & Insights
      security:
      - apiKeyAuth: []
      parameters:
      - in: query
        name: userId
        required: true
        schema:
          type: string
          format: uuid
      - in: query
        name: startDate
        required: true
        schema:
          type: string
          format: date
      - in: query
        name: endDate
        required: true
        schema:
          type: string
          format: date
      - in: query
        name: equipment
        schema:
          type: string
      - in: query
        name: muscle
        schema:
          type: string
      - in: query
        name: exercise
        schema:
          type: string
      responses:
        '200':
          description: Exercise dashboard data.
components:
  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)