SparkyFitness Nutrition & Meals API

openapi: 3.2.0
info:
  title: SparkyFitness Nutrition & Meals 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: Nutrition & Meals
  description: Food database, diary logging, meal planning, and nutritional preferences.
paths:
  /custom-nutrients:
    post:
      summary: Create a new custom nutrient
      tags:
      - Nutrition & Meals
      description: Creates a new custom nutrient for the authenticated user.
      security:
      - apiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              - unit
              properties:
                name:
                  type: string
                  description: The name of the custom nutrient.
                unit:
                  type: string
                  description: The unit of measurement for the custom nutrient.
                aliases:
                  type: array
                  items:
                    type: string
                  description: Alternate nutrient names online food providers may use for this nutrient.
      responses:
        '201':
          description: The new custom nutrient was created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomNutrient'
        '401':
          description: Unauthorized, authentication token is missing or invalid.
        '500':
          description: Failed to create custom nutrient.
    get:
      summary: Retrieve all custom nutrients
      tags:
      - Nutrition & Meals
      description: Retrieves all custom nutrients available to the authenticated user.
      security:
      - apiKeyAuth: []
      responses:
        '200':
          description: A list of custom nutrients.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CustomNutrient'
        '401':
          description: Unauthorized, authentication token is missing or invalid.
        '500':
          description: Failed to fetch custom nutrients.
  /custom-nutrients/from-catalog:
    post:
      summary: Find-or-create custom nutrients from the canonical micronutrient catalog
      tags:
      - Nutrition & Meals
      description: 'Ensures the authenticated user has a custom nutrient for each supplied canonical catalog id, seeded with the catalog''s name, unit, aliases and Daily Value. Idempotent: ids the user already has (matched by name or alias) are skipped, as are catalog entries that are already first-class nutrient columns.

        '
      security:
      - apiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - catalogIds
              properties:
                catalogIds:
                  type: array
                  items:
                    type: string
                  description: Canonical micronutrient catalog ids (e.g. "vitamin_d", "magnesium").
      responses:
        '200':
          description: The user's custom nutrients after seeding.
          content:
            application/json:
              schema:
                type: object
                properties:
                  resolved:
                    type: array
                    description: Each requested catalog id mapped to the nutrient key to store against.
                    items:
                      type: object
                      properties:
                        catalogId:
                          type: string
                        name:
                          type: string
                          description: The custom nutrient's actual name (may pre-date the catalog).
                        fixedField:
                          type: string
                          description: Set when the nutrient is a built-in column rather than a custom nutrient.
                  created:
                    type: array
                    items:
                      $ref: '#/components/schemas/CustomNutrient'
                  nutrients:
                    type: array
                    items:
                      $ref: '#/components/schemas/CustomNutrient'
        '400':
          description: catalogIds must be an array of strings.
        '401':
          description: Unauthorized, authentication token is missing or invalid.
        '500':
          description: Failed to seed custom nutrients.
  /custom-nutrients/{id}:
    get:
      summary: Retrieve a single custom nutrient by ID
      tags:
      - Nutrition & Meals
      description: Retrieves a single custom nutrient by its ID.
      security:
      - apiKeyAuth: []
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
        description: The ID of the custom nutrient to retrieve.
      responses:
        '200':
          description: The requested custom nutrient.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomNutrient'
        '401':
          description: Unauthorized, authentication token is missing or invalid.
        '404':
          description: Custom nutrient not found.
        '500':
          description: Failed to fetch custom nutrient.
    put:
      summary: Update a custom nutrient
      tags:
      - Nutrition & Meals
      description: Updates an existing custom nutrient.
      security:
      - apiKeyAuth: []
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
        description: The ID of the custom nutrient to update.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: The new name for the custom nutrient.
                unit:
                  type: string
                  description: The new unit of measurement for the custom nutrient.
                aliases:
                  type: array
                  items:
                    type: string
                  description: Alternate nutrient names online food providers may use for this nutrient.
      responses:
        '200':
          description: The custom nutrient was updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomNutrient'
        '401':
          description: Unauthorized, authentication token is missing or invalid.
        '404':
          description: Custom nutrient not found or unauthorized.
        '500':
          description: Failed to update custom nutrient.
    delete:
      summary: Delete a custom nutrient
      tags:
      - Nutrition & Meals
      description: Deletes a specific custom nutrient and performs cascading cleanup.
      security:
      - apiKeyAuth: []
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
        description: The ID of the custom nutrient to delete.
      - in: query
        name: deleteAllHistory
        schema:
          type: boolean
        description: Whether to also remove the nutrient data from past diary entries and goals.
      responses:
        '200':
          description: Custom nutrient deleted successfully.
        '401':
          description: Unauthorized, authentication token is missing or invalid.
        '404':
          description: Custom nutrient not found or unauthorized.
        '500':
          description: Failed to delete custom nutrient.
  /favorites:
    get:
      summary: List the user's favorite (starred) foods and meals
      tags:
      - Nutrition & Meals
      responses:
        '200':
          description: The user's favorite foods and meals.
  /favorites/{type}/{id}:
    post:
      summary: Star a food or meal as a favorite
      tags:
      - Nutrition & Meals
    delete:
      summary: Remove a food or meal from favorites
      tags:
      - Nutrition & Meals
  /foods/search:
    get:
      summary: Search for foods (AI-dedicated)
      tags:
      - Nutrition & Meals
      description: Searches for foods based on a name query. This endpoint is dedicated for AI-powered searches.
      parameters:
      - in: query
        name: name
        schema:
          type: string
        required: true
        description: The name of the food to search for.
      - in: query
        name: exactMatch
        schema:
          type: boolean
        description: If true, performs an exact match search.
      - in: query
        name: broadMatch
        schema:
          type: boolean
        description: If true, performs a broad match search.
      - in: query
        name: checkCustom
        schema:
          type: boolean
        description: If true, includes custom foods in the search.
      responses:
        '200':
          description: A list of foods matching the search criteria.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Food'
        '400':
          description: Invalid request parameters.
  /foods:
    get:
      summary: Search for foods
      tags:
      - Nutrition & Meals
      description: Searches for foods based on various criteria.
      parameters:
      - in: query
        name: name
        schema:
          type: string
        description: The name of the food to search for.
      - in: query
        name: exactMatch
        schema:
          type: boolean
        description: If true, performs an exact match search.
      - in: query
        name: broadMatch
        schema:
          type: boolean
        description: If true, performs a broad match search.
      - in: query
        name: checkCustom
        schema:
          type: boolean
        description: If true, includes custom foods in the search.
      - in: query
        name: limit
        schema:
          type: integer
        description: The maximum number of results to return.
      - in: query
        name: mealType
        schema:
          type: string
        description: The type of meal to filter by.
      responses:
        '200':
          description: A list of foods matching the search criteria.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Food'
        '400':
          description: Invalid request parameters.
    post:
      summary: Create a new food
      tags:
      - Nutrition & Meals
      description: Creates a new food item.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Food'
      responses:
        '201':
          description: The food was created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Food'
        '403':
          description: User does not have permission to create a food.
  /foods/foods-paginated:
    get:
      summary: Get foods with pagination
      tags:
      - Nutrition & Meals
      description: Retrieves a paginated list of foods.
      parameters:
      - in: query
        name: searchTerm
        schema:
          type: string
        description: The term to search for.
      - in: query
        name: foodFilter
        schema:
          type: string
        description: The filter to apply to the food list.
      - in: query
        name: currentPage
        schema:
          type: integer
        description: The current page number.
      - in: query
        name: itemsPerPage
        schema:
          type: integer
        description: The number of items to return per page.
      - in: query
        name: sortBy
        schema:
          type: string
        description: The field to sort by.
      responses:
        '200':
          description: A paginated list of foods.
          content:
            application/json:
              schema:
                type: object
                properties:
                  foods:
                    type: array
                    items:
                      $ref: '#/components/schemas/Food'
                  totalCount:
                    type: integer
  /foods/food-variants:
    post:
      summary: Create a new food variant
      tags:
      - Nutrition & Meals
      description: Creates a new variant for a food item.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FoodVariant'
      responses:
        '201':
          description: The food variant was created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FoodVariant'
        '403':
          description: User does not have permission to create a food variant.
        '404':
          description: Food not found.
    get:
      summary: Get food variants by food ID
      tags:
      - Nutrition & Meals
      description: Retrieves all variants for a specific food item.
      parameters:
      - in: query
        name: food_id
        schema:
          type: string
          format: uuid
        required: true
        description: The ID of the food to retrieve variants for.
      responses:
        '200':
          description: A list of food variants.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FoodVariant'
        '400':
          description: Food ID is required.
  /foods/food-variants/bulk:
    post:
      summary: Bulk create food variants
      tags:
      - Nutrition & Meals
      description: Creates multiple food variants in a single request.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/FoodVariant'
      responses:
        '201':
          description: The food variants were created successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FoodVariant'
        '403':
          description: User does not have permission to create food variants.
  /foods/food-variants/{id}:
    get:
      summary: Get a food variant by ID
      tags:
      - Nutrition & Meals
      description: Retrieves a specific food variant by its ID.
      parameters:
      - in: path
        name: id
        schema:
          type: string
          format: uuid
        required: true
        description: The ID of the food variant to retrieve.
      responses:
        '200':
          description: The requested food variant.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FoodVariant'
        '400':
          description: Food Variant ID is required.
        '403':
          description: User does not have permission to access this resource.
        '404':
          description: Food variant not found.
    put:
      summary: Update a food variant
      tags:
      - Nutrition & Meals
      description: Updates an existing food variant.
      parameters:
      - in: path
        name: id
        schema:
          type: string
          format: uuid
        required: true
        description: The ID of the food variant to update.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FoodVariant'
      responses:
        '200':
          description: The updated food variant.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FoodVariant'
        '400':
          description: Food Variant ID and Food ID are required.
        '403':
          description: User does not have permission to update this food variant.
        '404':
          description: Food variant not found.
    delete:
      summary: Delete a food variant
      tags:
      - Nutrition & Meals
      description: Deletes a specific food variant.
      parameters:
      - in: path
        name: id
        schema:
          type: string
          format: uuid
        required: true
        description: The ID of the food variant to delete.
      responses:
        '200':
          description: Food variant deleted successfully.
        '400':
          description: Food Variant ID is required.
        '403':
          description: User does not have permission to delete this food variant.
        '404':
          description: Food variant not found.
  /foods/barcode/{barcode}:
    get:
      summary: Look up a food by barcode
      tags:
      - Nutrition & Meals
      description: Checks the local database first, then queries an external barcode provider (USDA, FatSecret, YAZIO, or OpenFoodFacts). The provider can be specified via the providerId query parameter or the user's default_barcode_provider_id preference. If the chosen provider returns no results, OpenFoodFacts is tried as a fallback.
      parameters:
      - in: path
        name: barcode
        schema:
          type: string
        required: true
        description: The barcode to look up (8-14 digits).
      - in: query
        name: providerId
        schema:
          type: string
          format: uuid
        description: Optional external data provider ID to use for barcode lookup (e.g. a USDA provider). Falls back to the user's default barcode provider preference if not specified.
      responses:
        '200':
          description: Barcode lookup result.
          content:
            application/json:
              schema:
                type: object
                properties:
                  source:
                    type: string
                    enum:
                    - local
                    - openfoodfacts
                    - usda
                    - fatsecret
                    - yazio
                    - not_found
                  food:
                    $ref: '#/components/schemas/Food'
        '400':
          description: Invalid barcode format.
  /foods/{foodId}:
    get:
      summary: Get a food by ID
      tags:
      - Nutrition & Meals
      description: Retrieves a specific food item by its ID.
      parameters:
      - in: path
        name: foodId
        schema:
          type: string
          format: uuid
        required: true
        description: The ID of the food to retrieve.
      responses:
        '200':
          description: The requested food item.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Food'
        '400':
          description: Food ID is required.
        '403':
          description: User does not have permission to access this resource.
        '404':
          description: Food not found.
  /foods/{id}:
    put:
      summary: Update a food
      tags:
      - Nutrition & Meals
      description: Updates an existing food item.
      parameters:
      - in: path
        name: id
        schema:
          type: string
          format: uuid
        required: true
        description: The ID of the food to update.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Food'
      responses:
        '200':
          description: The updated food item.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Food'
        '400':
          description: Food ID is required.
        '403':
          description: User does not have permission to update this food.
        '404':
          description: Food not found or not authorized to update.
    delete:
      summary: Delete a food
      tags:
      - Nutrition & Meals
      description: Deletes a specific food item.
      parameters:
      - in: path
        name: id
        schema:
          type: string
          format: uuid
        required: true
        description: The ID of the food to delete.
      - in: query
        name: forceDelete
        schema:
          type: boolean
        description: If true, forces deletion even if there are dependencies.
      responses:
        '200':
          description: Food deleted successfully.
        '400':
          description: Food ID is required.
        '403':
          description: User does not have permission to delete this food.
        '404':
          description: Food not found.
  /foods/{id}/deletion-impact:
    get:
      summary: Get food deletion impact
      tags:
      - Nutrition & Meals
      description: Retrieves the impact of deleting a specific food item.
      parameters:
      - in: path
        name: id
        schema:
          type: string
          format: uuid
        required: true
        description: The ID of the food to check.
      responses:
        '200':
          description: The deletion impact report.
        '400':
          description: Food ID is required.
        '403':
          description: User does not have permission to access this resource.
        '404':
          description: Food not found.
  /foods/import-from-csv:
    post:
      summary: Import foods from CSV
      tags:
      - Nutrition & Meals
      description: Imports a list of foods from a CSV file.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                foods:
                  type: array
                  items:
                    $ref: '#/components/schemas/Food'
      responses:
        '200':
          description: Food data imported successfully.
        '400':
          description: Food data is required.
  /foods/needs-review:
    get:
      summary: Get foods needing review
      tags:
      - Nutrition & Meals
      description: Retrieves a list of foods that need to be reviewed.
      responses:
        '200':
          description: A list of foods needing review.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Food'
  /foods/update-snapshot:
    post:
      summary: Update food entries snapshot
      tags:
      - Nutrition & Meals
      description: Updates the snapshot of food entries.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                foodId:
                  type: string
                  format: uuid
                variantId:
                  type: string
                  format: uuid
                syncImages:
                  type: boolean
                  default: true
                  description: 'When true (the default), past entries are forced onto the food''s current photos, replacing photos the user set on individual diary entries; the replaced files are unlinked. When false, nutrition is rewritten and every entry keeps the photo it is showing.

                    '
      responses:
        '200':
          description: The result of the snapshot update.
        '400':
          description: foodId is required.
  /food-entry-meals:
    post:
      summary: Create a new FoodEntryMeal
      tags:
      - Nutrition & Meals
      description: Creates a new food entry meal for the authenticated user.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FoodEntryMeal'
      responses:
        '201':
          description: The FoodEntryMeal was created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FoodEntryMeal'
        '403':
          description: User does not have permission to create a food entry meal.
  /food-entry-meals/by-date/{date}:
    get:
      summary: Get FoodEntryMeals by date
      tags:
      - Nutrition & Meals
      description: Retrieves a list of all food entry meals for a specific date.
      parameters:
      - in: path
        name: date
        required: true
        schema:
          type: string
          format: date
        description: The date to retrieve food entry meals for (YYYY-MM-DD).
      responses:
        '200':
          description: A list of food entry meals for the specified date.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FoodEntryMeal'
        '403':
          description: User does not have permission to access this resource.
  /food-entry-meals/{id}:
    get:
      summary: Get a specific FoodEntryMeal with its components
      tags:
      - Nutrition & Meals
      description: Retrieves a specific food entry meal by its ID, including its associated food components.
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
        description: The ID of the food entry meal to retrieve.
      responses:
        '200':
          description: The requested FoodEntryMeal with components.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FoodEntryMeal'
        '403':
          description: User does not have permission to access this resource.
        '404':
          description: FoodEntryMeal not found.
    put:
      summary: Update an existing FoodEntryMeal
      tags:
      - Nutrition & Meals
      description: Updates an existing food entry meal with new information.
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
        description: The ID of the food entry meal to update.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FoodEntryMeal'
      responses:
        '200':
          description: The FoodEntryMeal was updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FoodEntryMeal'
        '403':
          description: User does not have permission to update this food entry meal.
        '404':
          description: FoodEntryMeal not found.
    delete:
      summary: Delete a FoodEntryMeal
      tags:
      - Nutrition & Meals
      description: Deletes a specific food entry meal.
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          format: uuid
        description: The ID of the food entry meal to delete.
      responses:
        '204':
          description: FoodEntryMeal deleted successfully.
        '403':
          description: User does not have permission to delete this food entry meal.
        '404':
          description: FoodEntryMeal not found.
  /food-entry-meals/{id}/image:
    post:
      summary: Set a logged meal's override photo
      tags:
      - Nutrition & Meals
      description: 'Attaches a photo to this diary entry only. It never modifies the meal template''s own images; entries without an override fall back to those.

        '
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                images:
                  description: 'Repeated file parts for newly uploaded photos, plus a JSON string field of the same name holding the desired final order. Entries in that array are either existing image paths being kept, or `__new__<n>` placeholders marking where the n-th uploaded file belongs.

                    '
                  type: array
                  items:
                    type: string
                    format: binary
      responses:
        '200':
          description: The updated logged meal.
        '400':
          description: No image supplied.
        '404':
          description: FoodEntryMeal not found.
    delete:
      summary: Clear a logged meal's override photo
      tags:
      - Nutrition & Meals
      description: 'Removes the entry-specific photo so the entry falls back to the meal template''s own image. The template is never modified.

        '
      responses:
        '200':
          description: The updated logged meal.
        '404':
          description: FoodEntryMeal not found.
  /food-entries/export/csv:
    get:
      summary: Export all food entries as CSV
      tags:
      - Nutrition & Meals
      security:
      - apiKeyAuth: []
      responses:
        '200':
          description: A CSV stream of all food entries
          content:
            text/csv:
              schema:
                type: string
  /food-entries/import-from-csv:
    post:
      summary: Import diary log entries from CSV
      tags:
      - Nutrition & Meals
      description: 'Bulk-creates diary log entries (food_entries) from CSV rows, distinct from /foods/import-from-csv which only imports food-library master data. Unmatched foods are auto-created from the row''s own nutrient columns; a row with no match and no nutrients is a per-row error.

        '
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                entries:
                  type: array
                  items:
                    type: object
                scope:
                  type: object
                  properties:
                    family:
                      type: boolean
                    public:
                      type: boolean
      responses:
        '200':
          description: Per-row import results (processed/errors/skipped).
        '400':
          description: Entries are required.
  /food-entries:
    post:
      summary: Create a new food entry
      tags:
      - Nutrition & Meals
      description: Adds a new food entry to the user's diary for a specific meal and date.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FoodEntry'
      responses:
        '201':
          description: The food entry was created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FoodEntry'
        '400':
          description: Invalid request body.
        '403':
          description: User does not have permission to create a food entry.
    get:
      summary: Get food entries by selected date
      tags:
      - Nutrition & Meals
      description: Retrieves a list of all food entries for a specific date, passed as a q

# --- truncated at 32 KB (98 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/sparkyfitness/refs/heads/main/openapi/sparkyfitness-nutrition-meals-api-openapi.yml