SparkyFitness Dashboard API

openapi: 3.2.0
info:
  title: SparkyFitness Dashboard 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: Dashboard
paths:
  /daily-summary:
    get:
      summary: Get consolidated daily summary
      tags:
      - Dashboard
      description: Returns goals, food entries, exercise sessions, and water intake for a single date in one response.
      security:
      - apiKeyAuth: []
      parameters:
      - in: query
        name: date
        required: true
        schema:
          type: string
          format: date
          example: '2026-03-26'
        description: Date in YYYY-MM-DD format
      - in: query
        name: userId
        schema:
          type: string
          format: uuid
        description: Optional user ID for family access
      responses:
        '200':
          description: Daily summary containing goals, food entries, exercise sessions, and water intake
        '400':
          description: Missing or invalid date parameter
        '403':
          description: User does not have permission to access this resource
        '500':
          description: Internal server error
      operationId: getDailySummary
      x-operation-id-source: derived
  /daily-summary/range:
    get:
      summary: Get per-day calorie balance for a date range
      tags:
      - Dashboard
      description: 'Returns one calorie-balance row per day, computed by the same code path as GET /daily-summary. Reports uses this instead of deriving the balance in the browser, which is what caused issue #2094.'
      security:
      - apiKeyAuth: []
      parameters:
      - in: query
        name: startDate
        required: true
        schema:
          type: string
          format: date
          example: '2026-08-06'
      - in: query
        name: endDate
        required: true
        schema:
          type: string
          format: date
          example: '2026-08-20'
      - in: query
        name: userId
        schema:
          type: string
          format: uuid
        description: Optional user ID for family access
      responses:
        '200':
          description: One calorie-balance row per calendar day in the range
        '400':
          description: Missing/invalid dates, inverted range, or range longer than 366 days
        '403':
          description: User does not have permission to access this resource
        '500':
          description: Internal server error
      operationId: getDailySummaryRange
      x-operation-id-source: derived
  /dashboard/stats:
    get:
      summary: Get dashboard statistics for external widgets
      tags:
      - Dashboard
      description: Returns daily energy goal stats. Can be authenticated via Browser Session or API Key (x-api-key).
      parameters:
      - in: query
        name: date
        schema:
          type: string
          format: date
        description: The date to fetch stats for (YYYY-MM-DD). Defaults to today in user's timezone.
      responses:
        '200':
          description: Statistics retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  eaten:
                    type: integer
                    description: Food and supplement kcal logged for the day.
                  burned:
                    type: integer
                    description: 'Resolved exercise calories plus BMR when the user enables "Include BMR in Net Calories". Exercise is max(device Active Calories, logged workouts + background steps), never their sum.

                      '
                  remaining:
                    type: integer
                    description: Budget left, per the user's calorie goal adjustment mode.
                  goal:
                    type: integer
                  net:
                    type: integer
                    description: eaten - burned.
                  progress:
                    type: integer
                    minimum: 0
                    description: 'Percent of the goal consumed. Not capped at 100 — a day over budget reports above 100, matching the Diary.

                      '
                  steps:
                    type: integer
                    description: Total step count from the day's check-in, or 0.
                  stepCalories:
                    type: integer
                    description: 'kcal from steps no logged workout already accounted for. 0 when the caller lacks checkin permission.

                      '
                  bmr:
                    type: integer
                  unit:
                    type: string
                    example: kcal
        '401':
          description: Authentication required.
        '403':
          description: 'Family access denied — the caller lacks `diary` permission on the requested user.

            '
      operationId: getDashboardStats
      x-operation-id-source: derived
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)