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. 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: 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.
    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.
  /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.
    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.
    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.
  /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.
  /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.
    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.
  /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.
    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.
  /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.
    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.
  /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.
  /v2/medications/injections:
    post:
      summary: Log an injection (optionally deduct from a pen/vial; auto-picks the pen when deduct_pen is set without pen_id)
      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.
  /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.
    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.
  /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.
    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.
  /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.
    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.
  /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.
  /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.
  /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).
    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.
  /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.
    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.
  /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.
  /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.
    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.
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)