SparkyFitness

SparkyFitness AI & Insights API

AI-powered chat assistance, reports, trends, and analytical insights.

Documentation GitHub OpenAPI

Operations 17

POST /chat Process a chat message or save AI service settings #

POST /chat/clear-old-history Clear old chat history for the authenticated user #

GET /chat/ai-service-settings Retrieve AI service settings for the authenticated user #

GET /chat/ai-service-settings/active Retrieve the active AI service setting for the authenticated user #

POST /chat/ai-service-settings/test Test an AI service connection with a minimal live completion #

DELETE /chat/ai-service-settings/{id} Delete an AI service setting #

GET /chat/sparky-chat-history Retrieve Sparky chat history for the authenticated user #

GET /chat/sparky-chat-history/entry/{id} Retrieve a single Sparky chat history entry #

PUT /chat/sparky-chat-history/{id} Update a Sparky chat history entry #

DELETE /chat/sparky-chat-history/{id} Delete a Sparky chat history entry #

POST /chat/clear-all-history Clear all Sparky chat history for the authenticated user #

POST /chat/save-history Save a Sparky chat history entry #

POST /chat/food-options Generate food options for a given food name and unit #

GET /reports Get comprehensive reports data #

GET /reports/mini-nutrition-trends Get mini nutrition trends #

GET /reports/nutrition-trends-with-goals Get nutrition trends with goals #

GET /reports/exercise-dashboard Get exercise dashboard data #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this

find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/sparkyfitness-ai-insights-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

openapi: 3.2.0
info:
  title: SparkyFitness AI & Insights 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: AI & Insights
  description: AI-powered chat assistance, reports, trends, and analytical insights.
paths:
  /chat:
    post:
      summary: Process a chat message or save AI service settings
      tags:
      - AI & Insights
      security:
      - apiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                messages:
                  type: array
                  items:
                    type: object
                    properties:
                      role:
                        type: string
                        enum:
                        - user
                        - assistant
                        - system
                      content:
                        type: string
                service_config_id:
                  type: string
                  format: uuid
                action:
                  type: string
                  enum:
                  - save_ai_service_settings
                service_data:
                  type: object
      responses:
        '200':
          description: Successful response from the AI service or confirmation of settings save.
        '400':
          description: Bad request.
        '404':
          description: Not found.
        '500':
          description: Server error.
      operationId: postChat
      x-operation-id-source: derived
  /chat/clear-old-history:
    post:
      summary: Clear old chat history for the authenticated user
      tags:
      - AI & Insights
      security:
      - apiKeyAuth: []
      responses:
        '200':
          description: Confirmation of successful clearing.
        '500':
          description: Server error.
      operationId: postChatClearOldHistory
      x-operation-id-source: derived
  /chat/ai-service-settings:
    get:
      summary: Retrieve AI service settings for the authenticated user
      tags:
      - AI & Insights
      security:
      - apiKeyAuth: []
      responses:
        '200':
          description: List of AI service settings.
        '403':
          description: Forbidden.
        '500':
          description: Server error.
      operationId: getChatAiServiceSettings
      x-operation-id-source: derived
  /chat/ai-service-settings/active:
    get:
      summary: Retrieve the active AI service setting for the authenticated user
      tags:
      - AI & Insights
      security:
      - apiKeyAuth: []
      responses:
        '200':
          description: Active AI service setting.
        '403':
          description: Forbidden.
        '404':
          description: Not found.
        '500':
          description: Server error.
      operationId: getChatAiServiceSettingsActive
      x-operation-id-source: derived
  /chat/ai-service-settings/test:
    post:
      summary: Test an AI service connection with a minimal live completion
      description: 'Runs a minimal completion against the supplied provider config without persisting anything. Returns HTTP 200 for both pass (`ok: true`) and provider failure (`ok: false`, with a `category`), so the client can show a friendly, category-specific message instead of a generic API error. On edit, a blank `api_key` falls back to the stored encrypted key.'
      tags:
      - AI & Insights
      security:
      - apiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - service_type
              properties:
                id:
                  type: string
                  format: uuid
                service_type:
                  type: string
                api_key:
                  type: string
                custom_url:
                  type: string
                model_name:
                  type: string
      responses:
        '200':
          description: Test result (pass or provider failure).
        '400':
          description: Bad request (malformed body or missing required model).
        '403':
          description: Forbidden (per-user AI config disabled, or non-admin testing a global service).
        '500':
          description: Server error.
      operationId: postChatAiServiceSettingsTest
      x-operation-id-source: derived
  /chat/ai-service-settings/{id}:
    delete:
      summary: Delete an AI service setting
      tags:
      - AI & Insights
      security:
      - apiKeyAuth: []
      parameters:
      - in: path
        name: id
        schema:
          type: string
          format: uuid
        required: true
      responses:
        '200':
          description: Confirmation of successful deletion.
        '400':
          description: Bad request.
        '403':
          description: Forbidden.
        '404':
          description: Not found.
        '500':
          description: Server error.
      operationId: deleteChatAiServiceSettingsById
      x-operation-id-source: derived
  /chat/sparky-chat-history:
    get:
      summary: Retrieve Sparky chat history for the authenticated user
      tags:
      - AI & Insights
      security:
      - apiKeyAuth: []
      responses:
        '200':
          description: Chat history.
        '403':
          description: Forbidden.
        '500':
          description: Server error.
      operationId: getChatSparkyChatHistory
      x-operation-id-source: derived
  /chat/sparky-chat-history/entry/{id}:
    get:
      summary: Retrieve a single Sparky chat history entry
      tags:
      - AI & Insights
      security:
      - apiKeyAuth: []
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Chat history entry.
        '400':
          description: Bad request.
        '403':
          description: Forbidden.
        '404':
          description: Not found.
        '500':
          description: Server error.
      operationId: getChatSparkyChatHistoryEntryById
      x-operation-id-source: derived
  /chat/sparky-chat-history/{id}:
    put:
      summary: Update a Sparky chat history entry
      tags:
      - AI & Insights
      security:
      - apiKeyAuth: []
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Updated chat history entry.
        '400':
          description: Bad request.
        '403':
          description: Forbidden.
        '404':
          description: Not found.
        '500':
          description: Server error.
      operationId: putChatSparkyChatHistoryById
      x-operation-id-source: derived
    delete:
      summary: Delete a Sparky chat history entry
      tags:
      - AI & Insights
      security:
      - apiKeyAuth: []
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Confirmation of successful deletion.
        '400':
          description: Bad request.
        '403':
          description: Forbidden.
        '404':
          description: Not found.
        '500':
          description: Server error.
      operationId: deleteChatSparkyChatHistoryById
      x-operation-id-source: derived
  /chat/clear-all-history:
    post:
      summary: Clear all Sparky chat history for the authenticated user
      tags:
      - AI & Insights
      security:
      - apiKeyAuth: []
      responses:
        '200':
          description: Confirmation of successful clearing.
        '403':
          description: Forbidden.
        '500':
          description: Server error.
      operationId: postChatClearAllHistory
      x-operation-id-source: derived
  /chat/save-history:
    post:
      summary: Save a Sparky chat history entry
      tags:
      - AI & Insights
      security:
      - apiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                content:
                  type: string
                messageType:
                  type: string
                metadata:
                  type: object
      responses:
        '201':
          description: Confirmation of successful saving.
        '400':
          description: Bad request.
        '403':
          description: Forbidden.
        '500':
          description: Server error.
      operationId: postChatSaveHistory
      x-operation-id-source: derived
  /chat/food-options:
    post:
      summary: Generate food options for a given food name and unit
      tags:
      - AI & Insights
      security:
      - apiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                foodName:
                  type: string
                unit:
                  type: string
                service_config_id:
                  type: string
                  format: uuid
      responses:
        '200':
          description: Raw AI JSON text containing the generated food options, returned as a string in `content`.
        '400':
          description: Missing service_config_id.
        '404':
          description: No AI service configured, or its API key / custom URL is missing.
        '422':
          description: AI response unusable (refused, truncated, empty, invalid JSON, or unsupported provider).
        '500':
          description: Server error.
        '502':
          description: Upstream AI service error.
        '504':
          description: AI service timed out.
      operationId: postChatFoodOptions
      x-operation-id-source: derived
  /reports:
    get:
      summary: Get comprehensive reports data
      tags:
      - AI & Insights
      security:
      - apiKeyAuth: []
      parameters:
      - in: query
        name: userId
        required: true
        schema:
          type: string
          format: uuid
      - in: query
        name: startDate
        required: true
        schema:
          type: string
          format: date
      - in: query
        name: endDate
        required: true
        schema:
          type: string
          format: date
      responses:
        '200':
          description: Reports data.
      operationId: getReports
      x-operation-id-source: derived
  /reports/mini-nutrition-trends:
    get:
      summary: Get mini nutrition trends
      tags:
      - AI & Insights
      security:
      - apiKeyAuth: []
      parameters:
      - in: query
        name: userId
        required: true
        schema:
          type: string
          format: uuid
      - in: query
        name: startDate
        required: true
        schema:
          type: string
          format: date
      - in: query
        name: endDate
        required: true
        schema:
          type: string
          format: date
      responses:
        '200':
          description: Mini nutrition trends.
      operationId: getReportsMiniNutritionTrends
      x-operation-id-source: derived
  /reports/nutrition-trends-with-goals:
    get:
      summary: Get nutrition trends with goals
      tags:
      - AI & Insights
      security:
      - apiKeyAuth: []
      parameters:
      - in: query
        name: userId
        required: true
        schema:
          type: string
          format: uuid
      - in: query
        name: startDate
        required: true
        schema:
          type: string
          format: date
      - in: query
        name: endDate
        required: true
        schema:
          type: string
          format: date
      responses:
        '200':
          description: Nutrition trends with goals.
      operationId: getReportsNutritionTrendsWithGoals
      x-operation-id-source: derived
  /reports/exercise-dashboard:
    get:
      summary: Get exercise dashboard data
      tags:
      - AI & Insights
      security:
      - apiKeyAuth: []
      parameters:
      - in: query
        name: userId
        required: true
        schema:
          type: string
          format: uuid
      - in: query
        name: startDate
        required: true
        schema:
          type: string
          format: date
      - in: query
        name: endDate
        required: true
        schema:
          type: string
          format: date
      - in: query
        name: equipment
        schema:
          type: string
      - in: query
        name: muscle
        schema:
          type: string
      - in: query
        name: exercise
        schema:
          type: string
      responses:
        '200':
          description: Exercise dashboard data.
      operationId: getReportsExerciseDashboard
      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)