openapi: 3.0.3
info:
  title: FatSecret Platform API
  description: >-
    The FatSecret Platform API provides programmatic access to a global food
    nutrition database covering more than 1.9 million verified food items
    across 56 countries. It supports food and recipe search, barcode scanning,
    image recognition, natural language processing, and full profile-based
    food diary, exercise diary, and weight tracking management.
  version: '3.0'
  contact:
    name: FatSecret Platform
    url: https://platform.fatsecret.com/platform-api
servers:
  - url: https://platform.fatsecret.com/rest
    description: REST endpoint for URL-based and method-based integration
security:
  - oauth2: []
  - oauth1: []
tags:
  - name: Foods
    description: Search and retrieve food nutrition data
  - name: Recipes
    description: Search and retrieve recipes
  - name: Reference
    description: Reference data for brands, categories, and exercises
  - name: Profile Foods
    description: User-managed custom foods and favorites
  - name: Profile Recipes
    description: User recipe favorites
  - name: Profile Meals
    description: Saved meals and meal items
  - name: Food Diary
    description: Daily food entries and summaries
  - name: Exercise Diary
    description: Daily exercise tracking
  - name: Weight Tracking
    description: User weight history
paths:
  /foods/search/v5:
    get:
      tags: [Foods]
      summary: Search foods
      description: Search the FatSecret food database for foods matching a query string.
      operationId: searchFoods
      parameters:
        - name: search_expression
          in: query
          required: true
          schema: { type: string }
        - name: page_number
          in: query
          schema: { type: integer, default: 0 }
        - name: max_results
          in: query
          schema: { type: integer, default: 20 }
      responses:
        '200':
          description: Matching foods
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FoodSearchResults'
  /foods/autocomplete/v2:
    get:
      tags: [Foods]
      summary: Autocomplete food search
      operationId: autocompleteFoods
      parameters:
        - name: expression
          in: query
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Suggestions
  /food/barcode/find-by-id/v1:
    get:
      tags: [Foods]
      summary: Find food by barcode
      operationId: findFoodByBarcode
      parameters:
        - name: barcode
          in: query
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Matching food
  /food/v4:
    get:
      tags: [Foods]
      summary: Get food by id
      operationId: getFood
      parameters:
        - name: food_id
          in: query
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Food details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Food'
  /food-brands/v2:
    get:
      tags: [Reference]
      summary: List food brands
      operationId: listFoodBrands
      responses:
        '200':
          description: Brands
  /food-categories/v2:
    get:
      tags: [Reference]
      summary: List food categories
      operationId: listFoodCategories
      responses:
        '200':
          description: Categories
  /food-sub-categories/v2:
    get:
      tags: [Reference]
      summary: List food sub-categories
      operationId: listFoodSubCategories
      responses:
        '200':
          description: Sub-categories
  /recipes/search/v3:
    get:
      tags: [Recipes]
      summary: Search recipes
      operationId: searchRecipes
      parameters:
        - name: search_expression
          in: query
          schema: { type: string }
      responses:
        '200':
          description: Matching recipes
  /recipe/v2:
    get:
      tags: [Recipes]
      summary: Get recipe by id
      operationId: getRecipe
      parameters:
        - name: recipe_id
          in: query
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Recipe details
  /recipe-types/v2:
    get:
      tags: [Recipes]
      summary: List recipe types
      operationId: listRecipeTypes
      responses:
        '200':
          description: Recipe types
  /exercises/v2:
    get:
      tags: [Reference]
      summary: List exercises
      operationId: listExercises
      responses:
        '200':
          description: Exercises
  /food/favorites/v2:
    get:
      tags: [Profile Foods]
      summary: Get favorite foods
      operationId: getFavoriteFoods
      responses:
        '200':
          description: Favorite foods
  /food/favorite/add/v2:
    post:
      tags: [Profile Foods]
      summary: Add favorite food
      operationId: addFavoriteFood
      responses:
        '200':
          description: Added
  /food/favorite/delete/v2:
    post:
      tags: [Profile Foods]
      summary: Delete favorite food
      operationId: deleteFavoriteFood
      responses:
        '200':
          description: Deleted
  /food-entries/v2:
    get:
      tags: [Food Diary]
      summary: Get food diary entries
      operationId: getFoodEntries
      parameters:
        - name: date
          in: query
          schema: { type: string, format: date }
      responses:
        '200':
          description: Entries
    post:
      tags: [Food Diary]
      summary: Create food diary entry
      operationId: createFoodEntry
      responses:
        '200':
          description: Created
  /food-entries/month/v2:
    get:
      tags: [Food Diary]
      summary: Monthly food diary summary
      operationId: getFoodEntriesMonth
      parameters:
        - name: month
          in: query
          schema: { type: string }
      responses:
        '200':
          description: Monthly summary
  /exercise-entries/v2:
    get:
      tags: [Exercise Diary]
      summary: Get exercise diary entries
      operationId: getExerciseEntries
      responses:
        '200':
          description: Exercise entries
    post:
      tags: [Exercise Diary]
      summary: Commit exercise diary entries
      operationId: commitExerciseEntries
      responses:
        '200':
          description: Committed
  /weights/v2:
    get:
      tags: [Weight Tracking]
      summary: Get weight history
      operationId: getWeights
      responses:
        '200':
          description: Weight entries
    post:
      tags: [Weight Tracking]
      summary: Update weight entry
      operationId: updateWeight
      responses:
        '200':
          description: Updated
  /saved-meals/v2:
    get:
      tags: [Profile Meals]
      summary: List saved meals
      operationId: listSavedMeals
      responses:
        '200':
          description: Saved meals
    post:
      tags: [Profile Meals]
      summary: Create saved meal
      operationId: createSavedMeal
      responses:
        '200':
          description: Created
components:
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://oauth.fatsecret.com/connect/token
          scopes:
            basic: Basic access to food and recipe data
            premier: Premier access including image recognition and NLP
    oauth1:
      type: http
      scheme: oauth
      description: OAuth 1.0a request signing
  schemas:
    Food:
      type: object
      properties:
        food_id:
          type: string
        food_name:
          type: string
        brand_name:
          type: string
        food_type:
          type: string
          enum: [Generic, Brand]
        food_url:
          type: string
          format: uri
        servings:
          type: object
    FoodSearchResults:
      type: object
      properties:
        foods:
          type: object
          properties:
            food:
              type: array
              items:
                $ref: '#/components/schemas/Food'
            max_results:
              type: integer
            page_number:
              type: integer
            total_results:
              type: integer