SparkyFitness Medications & GLP-1 API

openapi: 3.2.0
info:
  title: SparkyFitness Medications & GLP-1 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: Medications & GLP-1
  description: Medication cabinet, schedules, GLP-1 injections, pen/vial inventory, titration, and modeled PK/site-rotation.
paths:
  /v2/medications:
    get:
      summary: List the user's medications
      tags:
      - Medications & GLP-1
      security:
      - apiKeyAuth: []
      parameters:
      - in: query
        name: glp1Only
        schema:
          type: boolean
      - in: query
        name: activeOnly
        schema:
          type: boolean
      responses:
        '200':
          description: A list of medications.
      operationId: getV2Medications
      x-operation-id-source: derived
    post:
      summary: Create a medication
      tags:
      - Medications & GLP-1
      security:
      - apiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              properties:
                name:
                  type: string
                is_glp1:
                  type: boolean
                is_supplement:
                  type: boolean
                nutrients:
                  type: object
                  description: Fixed-key and custom nutrient amounts per dose
                type_id:
                  type: string
                strength_value:
                  type: number
                strength_unit:
                  type: string
      responses:
        '201':
          description: Created.
        '400':
          description: Invalid request.
      operationId: postV2Medications
      x-operation-id-source: derived
  /v2/medications/{id}:
    get:
      summary: Get a medication (with schedules)
      tags:
      - Medications & GLP-1
      security:
      - apiKeyAuth: []
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: The medication.
        '404':
          description: Not found.
      operationId: getV2MedicationsById
      x-operation-id-source: derived
    put:
      summary: Update a medication (partial)
      tags:
      - Medications & GLP-1
      security:
      - apiKeyAuth: []
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Updated.
        '404':
          description: Not found.
      operationId: putV2MedicationsById
      x-operation-id-source: derived
    delete:
      summary: Delete a medication (cascades)
      tags:
      - Medications & GLP-1
      security:
      - apiKeyAuth: []
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: Deleted.
        '404':
          description: Not found.
      operationId: deleteV2MedicationsById
      x-operation-id-source: derived
  /v2/medications/{medicationId}/schedules:
    post:
      summary: Add a schedule rule to a medication
      tags:
      - Medications & GLP-1
      security:
      - apiKeyAuth: []
      parameters:
      - in: path
        name: medicationId
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '201':
          description: Created.
        '400':
          description: Invalid request.
        '403':
          description: Supplement doses require food diary access for this profile.
      operationId: postV2MedicationsByMedicationIdSchedules
      x-operation-id-source: derived
  /v2/medications/schedules/{id}:
    put:
      summary: Update a schedule rule (partial)
      tags:
      - Medications & GLP-1
      security:
      - apiKeyAuth: []
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Updated.
        '400':
          description: Invalid request.
        '404':
          description: Not found.
      operationId: putV2MedicationsSchedulesById
      x-operation-id-source: derived
    delete:
      summary: Delete a schedule rule
      tags:
      - Medications & GLP-1
      security:
      - apiKeyAuth: []
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: Deleted.
        '404':
          description: Not found.
      operationId: deleteV2MedicationsSchedulesById
      x-operation-id-source: derived
  /v2/medications/{medicationId}/pens:
    get:
      summary: List pens/vials for a medication
      tags:
      - Medications & GLP-1
      security:
      - apiKeyAuth: []
      parameters:
      - in: path
        name: medicationId
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Pen/vial inventory.
      operationId: getV2MedicationsByMedicationIdPens
      x-operation-id-source: derived
    post:
      summary: Add a pen/vial (concentration, volume, BUD, doses)
      tags:
      - Medications & GLP-1
      security:
      - apiKeyAuth: []
      parameters:
      - in: path
        name: medicationId
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '201':
          description: Created.
        '400':
          description: Invalid request.
      operationId: postV2MedicationsByMedicationIdPens
      x-operation-id-source: derived
  /v2/medications/pens/{id}:
    put:
      summary: Update a pen/vial
      tags:
      - Medications & GLP-1
      security:
      - apiKeyAuth: []
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Updated.
        '404':
          description: Not found.
      operationId: putV2MedicationsPensById
      x-operation-id-source: derived
    delete:
      summary: Delete a pen/vial
      tags:
      - Medications & GLP-1
      security:
      - apiKeyAuth: []
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: Deleted.
        '404':
          description: Not found.
      operationId: deleteV2MedicationsPensById
      x-operation-id-source: derived
  /v2/medications/{medicationId}/injections:
    get:
      summary: List injections for a medication
      tags:
      - Medications & GLP-1
      security:
      - apiKeyAuth: []
      parameters:
      - in: path
        name: medicationId
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Injection history.
      operationId: getV2MedicationsByMedicationIdInjections
      x-operation-id-source: derived
  /v2/medications/injections:
    post:
      summary: Log an injection (optionally deduct from a pen/vial; auto-picks the pen when…
      tags:
      - Medications & GLP-1
      security:
      - apiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - medication_id
              properties:
                medication_id:
                  type: string
                  format: uuid
                pen_id:
                  type: string
                  format: uuid
                site:
                  type: string
                dose_mg:
                  type: number
                deduct_pen:
                  type: boolean
      responses:
        '201':
          description: Created (returns injection + updated pen).
        '400':
          description: Invalid request.
      operationId: postV2MedicationsInjections
      x-operation-id-source: derived
  /v2/medications/injections/{id}:
    put:
      summary: Update an injection (timing, site, dose, notes — not pen deduction)
      tags:
      - Medications & GLP-1
      security:
      - apiKeyAuth: []
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Updated.
        '404':
          description: Not found.
      operationId: putV2MedicationsInjectionsById
      x-operation-id-source: derived
    delete:
      summary: Delete an injection (credits the dose back to its pen when one was deducted)
      tags:
      - Medications & GLP-1
      security:
      - apiKeyAuth: []
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: Deleted.
        '404':
          description: Not found.
      operationId: deleteV2MedicationsInjectionsById
      x-operation-id-source: derived
  /v2/medications/{medicationId}/titration:
    get:
      summary: List titration/taper steps
      tags:
      - Medications & GLP-1
      security:
      - apiKeyAuth: []
      parameters:
      - in: path
        name: medicationId
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Titration plan steps.
      operationId: getV2MedicationsByMedicationIdTitration
      x-operation-id-source: derived
    post:
      summary: Add a titration/taper step
      tags:
      - Medications & GLP-1
      security:
      - apiKeyAuth: []
      parameters:
      - in: path
        name: medicationId
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '201':
          description: Created.
        '400':
          description: Invalid request.
      operationId: postV2MedicationsByMedicationIdTitration
      x-operation-id-source: derived
  /v2/medications/titration/{id}:
    put:
      summary: Update a titration step
      tags:
      - Medications & GLP-1
      security:
      - apiKeyAuth: []
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Updated.
        '404':
          description: Not found.
      operationId: putV2MedicationsTitrationById
      x-operation-id-source: derived
    delete:
      summary: Delete a titration step
      tags:
      - Medications & GLP-1
      security:
      - apiKeyAuth: []
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: Deleted.
        '404':
          description: Not found.
      operationId: deleteV2MedicationsTitrationById
      x-operation-id-source: derived
  /v2/medications/{medicationId}/glp1/serum-curve:
    get:
      summary: Modeled GLP-1 serum-level curve (PK model, not measured)
      tags:
      - Medications & GLP-1
      security:
      - apiKeyAuth: []
      parameters:
      - in: path
        name: medicationId
        required: true
        schema:
          type: string
          format: uuid
      - in: query
        name: fromDay
        schema:
          type: number
      - in: query
        name: toDay
        schema:
          type: number
      - in: query
        name: stepDays
        schema:
          type: number
      responses:
        '200':
          description: Sampled curve + current modeled level + disclaimer.
        '404':
          description: Medication not found.
      operationId: getV2MedicationsByMedicationIdGlp1SerumCurve
      x-operation-id-source: derived
  /v2/medications/{medicationId}/glp1/site-suggestion:
    get:
      summary: Suggest the next injection site (rotation + lipo rest window)
      tags:
      - Medications & GLP-1
      security:
      - apiKeyAuth: []
      parameters:
      - in: path
        name: medicationId
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Suggested site + resting sites + zone map.
      operationId: getV2MedicationsByMedicationIdGlp1SiteSuggestion
      x-operation-id-source: derived
  /v2/medications/entries:
    get:
      summary: List logged adherence doses, merged with GLP-1 injection logs
      description: Injection rows are folded into the same feed and flagged with entry_type='injection'; their id is an injection id, so update/delete them via the /injections endpoints.
      tags:
      - Medications & GLP-1
      security:
      - apiKeyAuth: []
      parameters:
      - in: query
        name: fromDate
        schema:
          type: string
          format: date
      - in: query
        name: toDate
        schema:
          type: string
          format: date
      - in: query
        name: medicationId
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Logged doses (adherence entries + injections).
      operationId: getV2MedicationsEntries
      x-operation-id-source: derived
    post:
      summary: Log an adherence dose (taken/skipped/snoozed/prn_taken)
      tags:
      - Medications & GLP-1
      security:
      - apiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - medication_id
              properties:
                medication_id:
                  type: string
                  format: uuid
                schedule_id:
                  type: string
                  format: uuid
                status:
                  type: string
                  enum:
                  - taken
                  - skipped
                  - snoozed
                  - prn_taken
                taken_at:
                  type: string
                  format: date-time
                entry_date:
                  type: string
                  format: date
                notes:
                  type: string
      responses:
        '201':
          description: Created.
        '400':
          description: Invalid request.
        '403':
          description: Supplement doses require food diary access for this profile.
      operationId: postV2MedicationsEntries
      x-operation-id-source: derived
  /v2/medications/entries/{id}:
    put:
      summary: Update a logged dose (e.g. correct the taken-at time or notes)
      tags:
      - Medications & GLP-1
      security:
      - apiKeyAuth: []
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: string
                  enum:
                  - taken
                  - skipped
                  - snoozed
                  - prn_taken
                taken_at:
                  type: string
                  format: date-time
                scheduled_for:
                  type: string
                  format: date-time
                entry_date:
                  type: string
                  format: date
                notes:
                  type: string
      responses:
        '200':
          description: Updated.
        '404':
          description: Not found.
        '403':
          description: Supplement doses require food diary access for this profile.
      operationId: putV2MedicationsEntriesById
      x-operation-id-source: derived
    delete:
      summary: Delete a logged dose
      tags:
      - Medications & GLP-1
      security:
      - apiKeyAuth: []
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: Deleted.
        '404':
          description: Not found.
        '403':
          description: Supplement doses require food diary access for this profile.
      operationId: deleteV2MedicationsEntriesById
      x-operation-id-source: derived
  /v2/medications/display-preferences:
    get:
      summary: List the user's medication display preferences
      tags:
      - Medications & GLP-1
      security:
      - apiKeyAuth: []
      responses:
        '200':
          description: Display preferences per view group and platform.
      operationId: getV2MedicationsDisplayPreferences
      x-operation-id-source: derived
  /v2/medications/display-preferences/{viewGroup}/{platform}:
    put:
      summary: Upsert the visible items for a view group and platform
      tags:
      - Medications & GLP-1
      security:
      - apiKeyAuth: []
      parameters:
      - in: path
        name: viewGroup
        required: true
        schema:
          type: string
      - in: path
        name: platform
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - visible_items
              properties:
                visible_items:
                  type: array
                  items:
                    type: string
      responses:
        '200':
          description: Upserted preference.
        '400':
          description: Invalid request.
      operationId: putV2MedicationsDisplayPreferencesByViewGroupByPlatform
      x-operation-id-source: derived
    delete:
      summary: Delete a display preference for a view group and platform
      tags:
      - Medications & GLP-1
      security:
      - apiKeyAuth: []
      parameters:
      - in: path
        name: viewGroup
        required: true
        schema:
          type: string
      - in: path
        name: platform
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Deleted.
        '404':
          description: Not found.
      operationId: deleteV2MedicationsDisplayPreferencesByViewGroupByPlatform
      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)