openapi: 3.0.3
info:
  title: fatsecret Natural Language Processing API
  description: >-
    The fatsecret Natural Language Processing method accepts a free-text description of what a user
    has eaten — "for breakfast I had a bowl of cereal, a banana, and a cappuccino" — estimates the
    serving sizes and weights, and matches each item against fatsecret's verified nutrition database
    for the requested region and language.
  version: '1.0'
  contact:
    name: fatsecret Platform
    url: https://platform.fatsecret.com/platform-api
  x-provenance:
    generated: '2026-08-12'
    method: generated
    source: https://platform.fatsecret.com/docs/v1/natural.language.processing
    note: >-
      Authored from fatsecret's own published method documentation, which specifies the HTTP verb,
      endpoint, every request parameter and the response fields. fatsecret publishes no
      machine-readable contract for this method; nothing here is inferred beyond what that page
      states.
servers:
- url: https://platform.fatsecret.com/rest
  description: REST endpoint for URL-based and method-based integration
security:
- oauth2: []
- oauth1: []
tags:
- name: Natural Language Processing
  description: Turn a free-text meal description into matched foods and nutrition
paths:
  /natural-language-processing/v1:
    post:
      tags:
      - Natural Language Processing
      summary: Parse a free-text meal description
      description: >-
        Accepts a natural-language description of what a user has eaten, which may contain multiple
        items, and returns the matched foods with suggested servings and nutritional content.
      operationId: processNaturalLanguageMeal
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NaturalLanguageRequest'
      responses:
        '200':
          description: Foods matched from the description
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FoodResponse'
        '400':
          description: Invalid request — see the fatsecret error code catalog
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Invalid or expired token (error code 13) or invalid signature (error code 8)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Missing scope (error code 14) or invalid IP address detected (error code 21)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Application request limit reached (error code 11)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    NaturalLanguageRequest:
      type: object
      required:
      - user_input
      properties:
        user_input:
          type: string
          maxLength: 1000
          description: >-
            A description of what a user has eaten. May contain multiple items. Limited to 1000
            characters.
          example: for breakfast I had a bowl of cereal, a banana, and a cappuccino
        include_food_data:
          type: boolean
          description: Include full food data inline in the response.
        eaten_foods:
          type: array
          description: Previously consumed foods, provided to assist with more accurate matching.
          items:
            $ref: '#/components/schemas/EatenFood'
        region:
          type: string
          description: Filter results by region. Defaults to US.
          default: US
          example: FR
        language:
          type: string
          description: Return results in the specified language. Only used when region is specified.
          example: fr
    EatenFood:
      type: object
      required:
      - food_id
      - food_name
      properties:
        food_id:
          type: integer
          format: int64
        food_name:
          type: string
        food_brand:
          type: string
        serving_description:
          type: string
        serving_size:
          type: string
    FoodResponse:
      type: object
      properties:
        food_response:
          type: array
          items:
            $ref: '#/components/schemas/MatchedFood'
    MatchedFood:
      type: object
      properties:
        food_id:
          type: integer
          format: int64
        food_entry_name:
          type: string
        eaten:
          type: object
          description: Nutritional content of the portion described.
          properties:
            total_nutritional_content:
              type: object
              description: Calories, macronutrients and micronutrients for the portion.
        suggested_serving:
          type: object
          description: Serving fatsecret suggests for the described portion.
        food:
          type: object
          description: Complete food record, returned when include_food_data is true.
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: integer
              description: fatsecret error code — see errors/fatsecret-error-codes.yml
            message:
              type: string
  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