openapi: 3.2.0
info:
  title: SparkyFitness Dashboard Layouts 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: Dashboard Layouts
paths:
  /dashboard-layouts/{pageKey}:
    get:
      summary: Get the saved widget layout for a dashboard page
      tags:
      - Dashboard Layouts
      security:
      - apiKeyAuth: []
      parameters:
      - in: path
        name: pageKey
        required: true
        schema:
          type: string
        description: The dashboard page identifier (e.g. "diary").
      responses:
        '200':
          description: The saved layout, or null when none is stored (use defaults).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DashboardLayout'
        '400':
          description: Unknown page key.
        '401':
          description: Unauthorized.
    put:
      summary: Create or update the widget layout for a dashboard page
      tags:
      - Dashboard Layouts
      security:
      - apiKeyAuth: []
      parameters:
      - in: path
        name: pageKey
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - layout
              - hidden
              properties:
                layout:
                  type: object
                hidden:
                  type: array
                  items:
                    type: string
      responses:
        '200':
          description: The saved layout.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DashboardLayout'
        '400':
          description: Invalid payload or unknown page key.
        '401':
          description: Unauthorized.
    delete:
      summary: Reset a dashboard page layout to defaults (deletes the stored row)
      tags:
      - Dashboard Layouts
      security:
      - apiKeyAuth: []
      parameters:
      - in: path
        name: pageKey
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Layout reset; the client should fall back to defaults.
        '400':
          description: Unknown page key.
        '401':
          description: Unauthorized.
components:
  schemas:
    DashboardLayout:
      type: object
      properties:
        layout:
          type: object
          description: Responsive grid layout keyed by breakpoint (lg/md/sm/xs).
        hidden:
          type: array
          items:
            type: string
          description: Widget keys the user has hidden.
        updated_at:
          type: string
          format: date-time
  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)