openapi: 3.2.0
info:
  title: SparkyFitness Sleep Science 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: SleepScience
paths:
  /sleep-science/sleep-debt:
    get:
      summary: Get current sleep debt with 14-day breakdown
      tags:
      - SleepScience
      security:
      - bearerAuth: []
      parameters:
      - in: query
        name: targetUserId
        schema:
          type: string
        description: Optional user ID for family access
      responses:
        '200':
          description: Sleep debt data
  /sleep-science/calculate-baseline:
    post:
      summary: Calculate and persist MCTQ baseline sleep need
      tags:
      - SleepScience
      security:
      - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                windowDays:
                  type: number
                  default: 90
      responses:
        '200':
          description: MCTQ calculation result
  /sleep-science/mctq-stats:
    get:
      summary: Get MCTQ statistics and calculation history
      tags:
      - SleepScience
      security:
      - bearerAuth: []
      parameters:
      - in: query
        name: targetUserId
        schema:
          type: string
      responses:
        '200':
          description: MCTQ stats
  /sleep-science/daily-need:
    get:
      summary: Get dynamic daily sleep need (WHOOP-style decomposition)
      tags:
      - SleepScience
      security:
      - bearerAuth: []
      parameters:
      - in: query
        name: date
        schema:
          type: string
          format: date
        description: Target date (defaults to today)
      - in: query
        name: targetUserId
        schema:
          type: string
      responses:
        '200':
          description: Daily sleep need breakdown
  /sleep-science/energy-curve:
    get:
      summary: Get 24-hour energy curve (Two-Process Model)
      tags:
      - SleepScience
      security:
      - bearerAuth: []
      parameters:
      - in: query
        name: targetUserId
        schema:
          type: string
      responses:
        '200':
          description: 96-point energy curve with zones
  /sleep-science/chronotype:
    get:
      summary: Get chronotype analysis
      tags:
      - SleepScience
      security:
      - bearerAuth: []
      parameters:
      - in: query
        name: targetUserId
        schema:
          type: string
      responses:
        '200':
          description: Chronotype classification and circadian markers
  /sleep-science/data-sufficiency:
    get:
      summary: Check if enough sleep data exists for MCTQ calculation
      tags:
      - SleepScience
      security:
      - bearerAuth: []
      parameters:
      - in: query
        name: targetUserId
        schema:
          type: string
      responses:
        '200':
          description: Data sufficiency assessment
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)