openapi: 3.0.3
info:
  title: FatSecret Platform Exercise Diary Foods 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
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'
components:
  schemas:
    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
    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
  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