SparkyFitness System & Admin API

openapi: 3.2.0
info:
  title: SparkyFitness System & Admin 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: System & Admin
  description: System configuration, administrative tasks, backups, reviews, and versioning.
paths:
  /admin/users:
    get:
      summary: Get all users with pagination and search
      tags:
      - System & Admin
      security:
      - apiKeyAuth: []
      parameters:
      - in: query
        name: limit
        schema:
          type: integer
          default: 10
        description: The maximum number of users to return.
      - in: query
        name: offset
        schema:
          type: integer
          default: 0
        description: The number of users to skip before starting to return results.
      - in: query
        name: searchTerm
        schema:
          type: string
        description: Search term for user names or emails.
      responses:
        '200':
          description: A list of users.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
        '401':
          description: Unauthorized.
        '403':
          description: Forbidden.
        '500':
          description: Server error.
      operationId: getAdminUsers
      x-operation-id-source: derived
  /admin/users/{userId}:
    delete:
      summary: Delete a user
      tags:
      - System & Admin
      security:
      - apiKeyAuth: []
      parameters:
      - in: path
        name: userId
        schema:
          type: string
          format: uuid
        required: true
        description: The ID of the user to delete.
      responses:
        '200':
          description: User deleted successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '401':
          description: Unauthorized.
        '403':
          description: Forbidden (e.g., cannot delete primary admin).
        '404':
          description: User not found.
        '500':
          description: Server error.
      operationId: deleteAdminUsersByUserId
      x-operation-id-source: derived
  /admin/users/{userId}/status:
    put:
      summary: Update user status (active/inactive)
      tags:
      - System & Admin
      security:
      - apiKeyAuth: []
      parameters:
      - in: path
        name: userId
        schema:
          type: string
          format: uuid
        required: true
        description: The ID of the user to update.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                isActive:
                  type: boolean
              required:
              - isActive
      responses:
        '200':
          description: User status updated successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '400':
          description: Invalid request body.
        '401':
          description: Unauthorized.
        '403':
          description: Forbidden (e.g., cannot change primary admin status).
        '404':
          description: User not found.
        '500':
          description: Server error.
      operationId: putAdminUsersByUserIdStatus
      x-operation-id-source: derived
  /admin/users/{userId}/role:
    put:
      summary: Update user role (user/admin)
      tags:
      - System & Admin
      security:
      - apiKeyAuth: []
      parameters:
      - in: path
        name: userId
        schema:
          type: string
          format: uuid
        required: true
        description: The ID of the user to update.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                role:
                  type: string
                  enum:
                  - user
                  - admin
              required:
              - role
      responses:
        '200':
          description: User role updated successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '400':
          description: Invalid request body.
        '401':
          description: Unauthorized.
        '403':
          description: Forbidden (e.g., cannot change primary admin role).
        '404':
          description: User not found.
        '500':
          description: Server error.
      operationId: putAdminUsersByUserIdRole
      x-operation-id-source: derived
  /admin/users/{userId}/full-name:
    put:
      summary: Update user's full name
      tags:
      - System & Admin
      security:
      - apiKeyAuth: []
      parameters:
      - in: path
        name: userId
        schema:
          type: string
          format: uuid
        required: true
        description: The ID of the user to update.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                fullName:
                  type: string
              required:
              - fullName
      responses:
        '200':
          description: User full name updated successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '400':
          description: Invalid request body.
        '401':
          description: Unauthorized.
        '403':
          description: Forbidden.
        '404':
          description: User not found.
        '500':
          description: Server error.
      operationId: putAdminUsersByUserIdFullName
      x-operation-id-source: derived
  /admin/users/{userId}/reset-password:
    post:
      summary: Initiate a password reset for a user
      tags:
      - System & Admin
      security:
      - apiKeyAuth: []
      parameters:
      - in: path
        name: userId
        schema:
          type: string
          format: uuid
        required: true
        description: The ID of the user to reset the password for.
      responses:
        '200':
          description: Password reset email sent successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '401':
          description: Unauthorized.
        '403':
          description: Forbidden.
        '404':
          description: User not found.
        '500':
          description: Server error.
      operationId: postAdminUsersByUserIdResetPassword
      x-operation-id-source: derived
  /admin/users/{userId}/mfa/reset:
    post:
      summary: Reset MFA for a user
      tags:
      - System & Admin
      security:
      - apiKeyAuth: []
      parameters:
      - in: path
        name: userId
        schema:
          type: string
          format: uuid
        required: true
        description: The ID of the user to reset MFA for.
      responses:
        '200':
          description: MFA reset successfully.
        '404':
          description: User not found.
      operationId: postAdminUsersByUserIdMfaReset
      x-operation-id-source: derived
  /admin/ai-service-settings/global:
    get:
      summary: Get all global AI service settings
      tags:
      - System & Admin
      security:
      - apiKeyAuth: []
      responses:
        '200':
          description: List of global AI service settings
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
      operationId: getAdminAiServiceSettingsGlobal
      x-operation-id-source: derived
    post:
      summary: Create a new global AI service setting
      tags:
      - System & Admin
      security:
      - apiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                service_name:
                  type: string
                service_type:
                  type: string
                api_key:
                  type: string
                custom_url:
                  type: string
                system_prompt:
                  type: string
                is_active:
                  type: boolean
                model_name:
                  type: string
                chat_tool_profile:
                  type: string
                  enum:
                  - full
                  - core
      responses:
        '201':
          description: Global AI service setting created
        '400':
          description: Invalid request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
      operationId: postAdminAiServiceSettingsGlobal
      x-operation-id-source: derived
  /admin/ai-service-settings/global/{id}:
    put:
      summary: Update a global AI service setting
      tags:
      - System & Admin
      security:
      - apiKeyAuth: []
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                service_name:
                  type: string
                service_type:
                  type: string
                api_key:
                  type: string
                custom_url:
                  type: string
                system_prompt:
                  type: string
                is_active:
                  type: boolean
                model_name:
                  type: string
                chat_tool_profile:
                  type: string
                  enum:
                  - full
                  - core
      responses:
        '200':
          description: Global AI service setting updated
        '400':
          description: Invalid request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Setting not found
      operationId: putAdminAiServiceSettingsGlobalById
      x-operation-id-source: derived
    delete:
      summary: Delete a global AI service setting
      tags:
      - System & Admin
      security:
      - apiKeyAuth: []
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Global AI service setting deleted
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Setting not found
      operationId: deleteAdminAiServiceSettingsGlobalById
      x-operation-id-source: derived
  /admin/external-data-providers/global:
    get:
      summary: Get all global external data providers
      tags:
      - System & Admin
      security:
      - apiKeyAuth: []
      responses:
        '200':
          description: List of global external data providers
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
      operationId: getAdminExternalDataProvidersGlobal
      x-operation-id-source: derived
    post:
      summary: Create a new global external data provider
      tags:
      - System & Admin
      security:
      - apiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                provider_name:
                  type: string
                provider_type:
                  type: string
                app_id:
                  type: string
                app_key:
                  type: string
                base_url:
                  type: string
                is_active:
                  type: boolean
      responses:
        '201':
          description: Global external data provider created
        '400':
          description: Invalid request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
      operationId: postAdminExternalDataProvidersGlobal
      x-operation-id-source: derived
  /admin/external-data-providers/global/{id}:
    put:
      summary: Update a global external data provider
      tags:
      - System & Admin
      security:
      - apiKeyAuth: []
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                provider_name:
                  type: string
                provider_type:
                  type: string
                app_id:
                  type: string
                app_key:
                  type: string
                base_url:
                  type: string
                is_active:
                  type: boolean
      responses:
        '200':
          description: Global external data provider updated
        '400':
          description: Invalid request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Provider not found
      operationId: putAdminExternalDataProvidersGlobalById
      x-operation-id-source: derived
    delete:
      summary: Delete a global external data provider
      tags:
      - System & Admin
      security:
      - apiKeyAuth: []
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Global external data provider deleted
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Provider not found
      operationId: deleteAdminExternalDataProvidersGlobalById
      x-operation-id-source: derived
  /announcement/current:
    get:
      summary: Get current active announcement from GitHub
      tags:
      - System & Admin
      responses:
        '200':
          description: Announcement payload.
      operationId: getAnnouncementCurrent
      x-operation-id-source: derived
  /admin/backup/manual:
    post:
      summary: Trigger a manual backup
      tags:
      - System & Admin
      security:
      - apiKeyAuth: []
      responses:
        '200':
          description: Backup completed successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  path:
                    type: string
                  fileName:
                    type: string
        '500':
          description: Server error during backup.
      operationId: postAdminBackupManual
      x-operation-id-source: derived
  /admin/backup/restore:
    post:
      summary: Upload and restore a backup
      tags:
      - System & Admin
      security:
      - apiKeyAuth: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                backupFile:
                  type: string
                  format: binary
                  description: The backup file to upload.
      responses:
        '200':
          description: Restore completed successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '400':
          description: No backup file uploaded.
        '500':
          description: Server error during restore.
      operationId: postAdminBackupRestore
      x-operation-id-source: derived
  /admin/backup/settings:
    get:
      summary: Get backup settings
      tags:
      - System & Admin
      security:
      - apiKeyAuth: []
      responses:
        '200':
          description: Backup settings retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BackupSettings'
        '500':
          description: Server error.
      operationId: getAdminBackupSettings
      x-operation-id-source: derived
    post:
      summary: Update backup settings
      tags:
      - System & Admin
      security:
      - apiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                backupEnabled:
                  type: boolean
                backupDays:
                  type: array
                  items:
                    type: string
                backupTime:
                  type: string
                retentionDays:
                  type: integer
      responses:
        '200':
          description: Backup settings saved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  settings:
                    $ref: '#/components/schemas/BackupSettings'
        '500':
          description: Server error.
      operationId: postAdminBackupSettings
      x-operation-id-source: derived
  /admin/backup/list:
    get:
      summary: List all available backup files
      tags:
      - System & Admin
      security:
      - apiKeyAuth: []
      responses:
        '200':
          description: Backup files listed successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  backups:
                    type: array
                    items:
                      type: object
                      properties:
                        fileName:
                          type: string
                        size:
                          type: integer
                        createdAt:
                          type: string
                          format: date-time
                          description: When the backup run started.
                        completedAt:
                          type: string
                          format: date-time
                          description: When the backup run finished.
        '500':
          description: Server error.
      operationId: getAdminBackupList
      x-operation-id-source: derived
  /admin/backup/download/{fileName}:
    get:
      summary: Download a specific backup file
      tags:
      - System & Admin
      security:
      - apiKeyAuth: []
      parameters:
      - in: path
        name: fileName
        required: true
        schema:
          type: string
        description: The backup file name, as returned by GET /admin/backup/list.
      responses:
        '200':
          description: Backup file downloaded successfully.
          content:
            application/gzip:
              schema:
                type: string
                format: binary
        '400':
          description: Invalid backup file name.
        '404':
          description: Backup file not found.
        '500':
          description: Server error.
      operationId: getAdminBackupDownloadByFileName
      x-operation-id-source: derived
  /admin/global-settings:
    get:
      summary: GET Global Authentication Settings (Admin Only)
      tags:
      - System & Admin
      security:
      - apiKeyAuth: []
      responses:
        '200':
          description: Global settings.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GlobalSettings'
      operationId: getAdminGlobalSettings
      x-operation-id-source: derived
    put:
      summary: Update Global Authentication Settings (Admin Only)
      tags:
      - System & Admin
      security:
      - apiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GlobalSettings'
      responses:
        '200':
          description: Settings updated successfully.
      operationId: putAdminGlobalSettings
      x-operation-id-source: derived
  /global-settings/allow-user-ai-config:
    get:
      summary: Check if users are allowed to configure AI services (Public)
      tags:
      - System & Admin
      security:
      - apiKeyAuth: []
      responses:
        '200':
          description: Returns whether user AI config is allowed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  allow_user_ai_config:
                    type: boolean
      operationId: getGlobalSettingsAllowUserAiConfig
      x-operation-id-source: derived
  /health:
    get:
      summary: System health check
      tags:
      - System & Admin
      responses:
        '200':
          description: System is up and running.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: UP
      operationId: getHealth
      x-operation-id-source: derived
  /review/needs-review-count:
    get:
      summary: Get the count of items needing review
      tags:
      - System & Admin
      security:
      - apiKeyAuth: []
      responses:
        '200':
          description: Count of items.
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
      operationId: getReviewNeedsReviewCount
      x-operation-id-source: derived
  /review/needs-review:
    get:
      summary: Get the list of items needing review
      tags:
      - System & Admin
      security:
      - apiKeyAuth: []
      responses:
        '200':
          description: List of items needing review.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                      format: uuid
                    type:
                      type: string
                      enum:
                      - food
                      - exercise
                    name:
                      type: string
      operationId: getReviewNeedsReview
      x-operation-id-source: derived
  /version/current:
    get:
      summary: Get current app version
      tags:
      - System & Admin
      responses:
        '200':
          description: App version.
          content:
            application/json:
              schema:
                type: object
                properties:
                  version:
                    type: string
      operationId: getVersionCurrent
      x-operation-id-source: derived
  /version/latest-github:
    get:
      summary: Get latest GitHub release
      tags:
      - System & Admin
      responses:
        '200':
          description: Latest release.
      operationId: getVersionLatestGithub
      x-operation-id-source: derived
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier for the user.
        email:
          type: string
          format: email
          description: The user's email address.
        role:
          type: string
          enum:
          - user
          - admin
          description: The user's role in the system.
        is_active:
          type: boolean
          description: Indicates if the user account is active.
        full_name:
          type:
          - string
          - 'null'
          description: The user's full name.
        created_at:
          type: string
          format: date-time
          description: The date and time when the user account was created.
        last_login_at:
          type:
          - string
          - 'null'
          format: date-time
          description: The date and time of the user's last login.
      required:
      - id
      - email
      - role
      - is_active
    BackupSettings:
      type: object
      properties:
        backupEnabled:
          type: boolean
        backupDays:
          type: array
          items:
            type: string
        backupTime:
          type: string
        retentionDays:
          type: integer
        lastBackupStatus:
          type: string
        lastBackupTimestamp:
          type: string
          format: date-time
        backupLocation:
          type: string
    GlobalSettings:
      type: object
      properties:
        enable_email_password_login:
          type: boolean
        is_oidc_active:
          type: boolean
        is_mfa_mandatory:
          type: boolean
        default_vision_ai_service_id:
          type:
          - string
          - 'null'
          format: uuid
          description: Global default AI service used for vision tasks (food-photo, label scan) by users on the global default. Null clears it.
  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)