openapi: 3.0.3
info:
  title: Nutritionix Track API v2
  version: '2.0'
  description: >-
    The Nutritionix Track API converts natural-language food and exercise
    descriptions into detailed nutrient and calorie analysis, and provides
    search and lookup access to the world's largest verified nutrition
    database, including USDA-linked common foods and over a million branded
    and restaurant menu items.
  contact:
    name: Nutritionix Developer Support
    url: https://developer.nutritionix.com/
  x-generated-from: documentation
  x-last-validated: '2026-06-03'
servers:
- url: https://trackapi.nutritionix.com/v2
  description: Nutritionix Track API v2 production server
security:
- AppId: []
  AppKey: []
tags:
- name: Natural Language
  description: Translate plain-text food and exercise phrases into structured nutrition data.
- name: Search
  description: Search the nutrition database for common and branded foods.
- name: Item
  description: Look up detailed nutrition for branded and restaurant menu items.
- name: Brands
  description: Search the database of food and restaurant brands.
paths:
  /natural/nutrients:
    post:
      operationId: getNaturalNutrients
      summary: Nutritionix Analyze Natural Language Nutrients
      description: >-
        Submit a plain-text description of one or more foods and receive a full
        nutrient breakdown for each detected food, including calories, macros,
        micronutrients, serving sizes, and photos.
      tags:
      - Natural Language
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NaturalNutrientsRequest'
            examples:
              GetNaturalNutrientsRequestExample:
                summary: Default getNaturalNutrients request
                x-microcks-default: true
                value:
                  query: 1 cup mashed potatoes and 2 tbsp gravy
                  num_servings: 1
                  aggregate: aggregate
                  line_delimited: false
                  use_raw_foods: false
                  include_subrecipe: false
                  timezone: US/Eastern
                  consumed_at: consumed_at
                  use_branded_foods: false
                  locale: en_US
      responses:
        '200':
          description: Foods successfully analyzed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NaturalNutrientsResponse'
              examples:
                GetNaturalNutrients200Example:
                  summary: Default getNaturalNutrients 200 response
                  x-microcks-default: true
                  value:
                    foods:
                    - food_name: Big Mac
                      brand_name: McDonald's
                      serving_qty: 1
                      serving_unit: burger
                      serving_weight_grams: 219
                      nf_calories: 540
                      nf_total_fat: 28
                      nf_saturated_fat: 10
                      nf_cholesterol: 80
                      nf_sodium: 970
                      nf_total_carbohydrate: 47
                      nf_dietary_fiber: 3
                      nf_sugars: 9
                      nf_protein: 25
                      nf_potassium: 1
                      nf_p: 1
                      full_nutrients:
                      - attr_id: 203
                        value: 25
                      nix_brand_name: McDonald's
                      nix_brand_id: 513fbc1283aa2dc80c000053
                      nix_item_name: Big Mac
                      nix_item_id: 513fc9e73fe3ffd40300109f
                      metadata: {}
                      source: 8
                      ndb_no: 1
                      tags: {}
                      alt_measures:
                      - serving_weight: 219
                        measure: burger
                        seq: 1
                        qty: 1
                      photo:
                        thumb: https://nix-tag-images.s3.amazonaws.com/402_thumb.jpg
                        highres: highres
                        is_user_uploaded: false
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /natural/exercise:
    post:
      operationId: getNaturalExercise
      summary: Nutritionix Analyze Natural Language Exercise
      description: >-
        Submit a plain-text description of physical activity and receive an
        estimate of calories burned, personalized by the user's gender, weight,
        height, and age.
      tags:
      - Natural Language
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NaturalExerciseRequest'
            examples:
              GetNaturalExerciseRequestExample:
                summary: Default getNaturalExercise request
                x-microcks-default: true
                value:
                  query: ran 3 miles
                  gender: male
                  weight_kg: 72.5
                  height_cm: 167.64
                  age: 30
      responses:
        '200':
          description: Exercise successfully analyzed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NaturalExerciseResponse'
              examples:
                GetNaturalExercise200Example:
                  summary: Default getNaturalExercise 200 response
                  x-microcks-default: true
                  value:
                    exercises:
                    - tag_id: 1
                      user_input: user_input
                      duration_min: 30
                      met: 9.8
                      nf_calories: 372.5
                      photo:
                        thumb: https://nix-tag-images.s3.amazonaws.com/402_thumb.jpg
                        highres: highres
                        is_user_uploaded: false
                      compendium_code: 1
                      name: running
                      benefits: benefits
        '401':
          $ref: '#/components/responses/Unauthorized'
  /search/instant:
    get:
      operationId: searchInstant
      summary: Nutritionix Search Instant
      description: >-
        Typeahead search that returns matched common foods and branded foods for
        a partial or complete query string. Ideal for building food autocomplete
        experiences.
      tags:
      - Search
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      parameters:
      - name: query
        in: query
        required: true
        description: The food search phrase to match against common and branded foods.
        schema:
          type: string
        example: cheese
      - name: branded
        in: query
        required: false
        description: Whether to include branded foods in the results.
        schema:
          type: boolean
          default: true
      - name: common
        in: query
        required: false
        description: Whether to include common foods in the results.
        schema:
          type: boolean
          default: true
      - name: detailed
        in: query
        required: false
        description: Whether to return full nutrient detail for each result.
        schema:
          type: boolean
          default: false
      - name: branded_type
        in: query
        required: false
        description: Filter branded results by type (1 for restaurant, 2 for grocery/CPG).
        schema:
          type: integer
          enum: [1, 2]
      - name: locale
        in: query
        required: false
        description: Locale code used to localize results (e.g. en_US).
        schema:
          type: string
          default: en_US
      responses:
        '200':
          description: Matching common and branded foods.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstantSearchResponse'
              examples:
                SearchInstant200Example:
                  summary: Default searchInstant 200 response
                  x-microcks-default: true
                  value:
                    common:
                    - food_name: cheese
                      serving_unit: cup, diced
                      tag_name: cheese
                      serving_qty: 1
                      common_type: 1
                      tag_id: '402'
                      photo:
                        thumb: https://nix-tag-images.s3.amazonaws.com/402_thumb.jpg
                        highres: highres
                        is_user_uploaded: false
                      locale: en_US
                    branded:
                    - food_name: Big Mac
                      serving_unit: burger
                      nix_brand_id: 513fbc1283aa2dc80c000053
                      brand_name_item_name: McDonald's Big Mac
                      serving_qty: 1
                      nf_calories: 540
                      photo:
                        thumb: https://nix-tag-images.s3.amazonaws.com/402_thumb.jpg
                        highres: highres
                        is_user_uploaded: false
                      brand_name: McDonald's
                      region: 1
                      brand_type: 1
                      nix_item_id: 513fc9e73fe3ffd40300109f
                      locale: en_US
        '401':
          $ref: '#/components/responses/Unauthorized'
  /search/item:
    get:
      operationId: searchItem
      summary: Nutritionix Search Item
      description: >-
        Retrieve full nutrition detail for a branded or restaurant menu item by
        its Nutritionix item identifier or UPC barcode.
      tags:
      - Item
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      parameters:
      - name: nix_item_id
        in: query
        required: false
        description: The Nutritionix item identifier for a branded or restaurant item.
        schema:
          type: string
        example: 513fc9e73fe3ffd40300109f
      - name: upc
        in: query
        required: false
        description: The UPC barcode of a branded grocery item.
        schema:
          type: string
      - name: claims
        in: query
        required: false
        description: Whether to include marketing/regulatory claims in the response.
        schema:
          type: boolean
          default: false
      - name: allergens
        in: query
        required: false
        description: Whether to include allergen information in the response.
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Branded item nutrition detail.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FoodsResponse'
              examples:
                SearchItem200Example:
                  summary: Default searchItem 200 response
                  x-microcks-default: true
                  value:
                    foods:
                    - food_name: Big Mac
                      brand_name: McDonald's
                      serving_qty: 1
                      serving_unit: burger
                      serving_weight_grams: 219
                      nf_calories: 540
                      nf_total_fat: 28
                      nf_saturated_fat: 10
                      nf_cholesterol: 80
                      nf_sodium: 970
                      nf_total_carbohydrate: 47
                      nf_dietary_fiber: 3
                      nf_sugars: 9
                      nf_protein: 25
                      nf_potassium: 1
                      nf_p: 1
                      full_nutrients:
                      - attr_id: 203
                        value: 25
                      nix_brand_name: McDonald's
                      nix_brand_id: 513fbc1283aa2dc80c000053
                      nix_item_name: Big Mac
                      nix_item_id: 513fc9e73fe3ffd40300109f
                      metadata: {}
                      source: 8
                      ndb_no: 1
                      tags: {}
                      alt_measures:
                      - serving_weight: 219
                        measure: burger
                        seq: 1
                        qty: 1
                      photo:
                        thumb: https://nix-tag-images.s3.amazonaws.com/402_thumb.jpg
                        highres: highres
                        is_user_uploaded: false
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /item:
    get:
      operationId: getItem
      summary: Nutritionix Get Item
      description: >-
        Retrieve a single item by its item identifier, resource identifier, or
        UPC. This is the legacy item-lookup endpoint; new integrations should
        prefer /search/item.
      tags:
      - Item
      deprecated: true
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      parameters:
      - name: id
        in: query
        required: false
        description: The item identifier or resource identifier to look up.
        schema:
          type: string
      - name: upc
        in: query
        required: false
        description: The UPC barcode of a branded grocery item.
        schema:
          type: string
      - name: nix_item_id
        in: query
        required: false
        description: The Nutritionix item identifier.
        schema:
          type: string
      responses:
        '200':
          description: Item nutrition detail.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FoodsResponse'
              examples:
                GetItem200Example:
                  summary: Default getItem 200 response
                  x-microcks-default: true
                  value:
                    foods:
                    - food_name: Big Mac
                      brand_name: McDonald's
                      serving_qty: 1
                      serving_unit: burger
                      serving_weight_grams: 219
                      nf_calories: 540
                      nf_total_fat: 28
                      nf_saturated_fat: 10
                      nf_cholesterol: 80
                      nf_sodium: 970
                      nf_total_carbohydrate: 47
                      nf_dietary_fiber: 3
                      nf_sugars: 9
                      nf_protein: 25
                      nf_potassium: 1
                      nf_p: 1
                      full_nutrients:
                      - attr_id: 203
                        value: 25
                      nix_brand_name: McDonald's
                      nix_brand_id: 513fbc1283aa2dc80c000053
                      nix_item_name: Big Mac
                      nix_item_id: 513fc9e73fe3ffd40300109f
                      metadata: {}
                      source: 8
                      ndb_no: 1
                      tags: {}
                      alt_measures:
                      - serving_weight: 219
                        measure: burger
                        seq: 1
                        qty: 1
                      photo:
                        thumb: https://nix-tag-images.s3.amazonaws.com/402_thumb.jpg
                        highres: highres
                        is_user_uploaded: false
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /brands/search:
    get:
      operationId: searchBrands
      summary: Nutritionix Search Brands
      description: >-
        Search the database of food and restaurant brands by name, optionally
        filtering by brand type (restaurant or grocery/CPG).
      tags:
      - Brands
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      parameters:
      - name: query
        in: query
        required: true
        description: The brand name search phrase.
        schema:
          type: string
        example: mcdonald
      - name: type
        in: query
        required: false
        description: Filter by brand type (1 for restaurant, 2 for grocery/CPG).
        schema:
          type: integer
          enum: [1, 2]
      - name: limit
        in: query
        required: false
        description: Maximum number of brands to return.
        schema:
          type: integer
          default: 10
      responses:
        '200':
          description: Matching brands.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BrandSearchResponse'
              examples:
                SearchBrands200Example:
                  summary: Default searchBrands 200 response
                  x-microcks-default: true
                  value:
                    brands:
                    - _id: 513fbc1283aa2dc80c000053
                      name: McDonald's
                      website: website
                      type: 1
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  securitySchemes:
    AppId:
      type: apiKey
      in: header
      name: x-app-id
      description: Your Nutritionix application identifier.
    AppKey:
      type: apiKey
      in: header
      name: x-app-key
      description: Your Nutritionix application key.
  responses:
    Unauthorized:
      description: Missing or invalid x-app-id / x-app-key credentials.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource could not be found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    NaturalNutrientsRequest:
      type: object
      description: Request body for the natural language nutrients endpoint.
      required:
      - query
      properties:
        query:
          type: string
          description: Plain-text description of the food(s) to analyze.
          example: 1 cup mashed potatoes and 2 tbsp gravy
        num_servings:
          type: integer
          description: Multiplier applied to the parsed serving quantities.
        aggregate:
          type: string
          description: When set, aggregates all foods into a single named result.
        line_delimited:
          type: boolean
          description: Treat each newline in the query as a separate food.
          default: false
        use_raw_foods:
          type: boolean
          description: Prefer raw (uncooked) USDA foods when resolving the query.
          default: false
        include_subrecipe:
          type: boolean
          description: Include sub-recipe ingredient breakdowns where available.
          default: false
        timezone:
          type: string
          description: IANA timezone used for consumed_at calculations.
          example: US/Eastern
        consumed_at:
          type: string
          format: date-time
          description: Timestamp the food was consumed.
        use_branded_foods:
          type: boolean
          description: Allow branded foods to satisfy the query.
          default: false
        locale:
          type: string
          description: Locale code used to localize results.
          example: en_US
    NaturalNutrientsResponse:
      type: object
      description: Response from the natural language nutrients endpoint.
      properties:
        foods:
          type: array
          description: One food object per detected food in the query.
          items:
            $ref: '#/components/schemas/Food'
    NaturalExerciseRequest:
      type: object
      description: Request body for the natural language exercise endpoint.
      required:
      - query
      properties:
        query:
          type: string
          description: Plain-text description of the physical activity.
          example: ran 3 miles
        gender:
          type: string
          description: User gender, used to refine calorie-burn estimates.
          enum: [male, female]
        weight_kg:
          type: number
          description: User weight in kilograms.
          example: 72.5
        height_cm:
          type: number
          description: User height in centimeters.
          example: 167.64
        age:
          type: integer
          description: User age in years.
          example: 30
    NaturalExerciseResponse:
      type: object
      description: Response from the natural language exercise endpoint.
      properties:
        exercises:
          type: array
          description: One exercise object per detected activity.
          items:
            $ref: '#/components/schemas/Exercise'
    Exercise:
      type: object
      description: A single analyzed physical activity.
      properties:
        tag_id:
          type: integer
          description: Internal exercise tag identifier.
        user_input:
          type: string
          description: The portion of the query that mapped to this exercise.
        duration_min:
          type: number
          description: Duration of the activity in minutes.
          example: 30
        met:
          type: number
          description: Metabolic Equivalent of Task value for the activity.
          example: 9.8
        nf_calories:
          type: number
          description: Estimated calories burned.
          example: 372.5
        photo:
          $ref: '#/components/schemas/Photo'
        compendium_code:
          type: integer
          description: Compendium of Physical Activities code for the exercise.
        name:
          type: string
          description: Canonical name of the activity.
          example: running
        benefits:
          type: string
          nullable: true
          description: Optional notes on the benefits of the activity.
    InstantSearchResponse:
      type: object
      description: Response from the instant search endpoint.
      properties:
        common:
          type: array
          description: Matched common (generic) foods.
          items:
            $ref: '#/components/schemas/CommonFood'
        branded:
          type: array
          description: Matched branded and restaurant foods.
          items:
            $ref: '#/components/schemas/BrandedFood'
    CommonFood:
      type: object
      description: A matched common (generic) food from instant search.
      properties:
        food_name:
          type: string
          example: cheese
        serving_unit:
          type: string
          example: cup, diced
        tag_name:
          type: string
          example: cheese
        serving_qty:
          type: number
          example: 1
        common_type:
          type: integer
          nullable: true
        tag_id:
          type: string
          example: '402'
        photo:
          $ref: '#/components/schemas/Photo'
        locale:
          type: string
          example: en_US
    BrandedFood:
      type: object
      description: A matched branded or restaurant food from instant search.
      properties:
        food_name:
          type: string
          example: Big Mac
        serving_unit:
          type: string
          example: burger
        nix_brand_id:
          type: string
          example: 513fbc1283aa2dc80c000053
        brand_name_item_name:
          type: string
          example: McDonald's Big Mac
        serving_qty:
          type: number
          example: 1
        nf_calories:
          type: number
          example: 540
        photo:
          $ref: '#/components/schemas/Photo'
        brand_name:
          type: string
          example: McDonald's
        region:
          type: integer
          example: 1
        brand_type:
          type: integer
          example: 1
        nix_item_id:
          type: string
          example: 513fc9e73fe3ffd40300109f
        locale:
          type: string
          example: en_US
    FoodsResponse:
      type: object
      description: A response that wraps one or more fully detailed food objects.
      properties:
        foods:
          type: array
          items:
            $ref: '#/components/schemas/Food'
    Food:
      type: object
      description: A fully detailed food object with complete nutrient information.
      properties:
        food_name:
          type: string
          example: Big Mac
        brand_name:
          type: string
          nullable: true
          example: McDonald's
        serving_qty:
          type: number
          example: 1
        serving_unit:
          type: string
          example: burger
        serving_weight_grams:
          type: number
          nullable: true
          example: 219
        nf_calories:
          type: number
          example: 540
        nf_total_fat:
          type: number
          example: 28
        nf_saturated_fat:
          type: number
          example: 10
        nf_cholesterol:
          type: number
          example: 80
        nf_sodium:
          type: number
          example: 970
        nf_total_carbohydrate:
          type: number
          example: 47
        nf_dietary_fiber:
          type: number
          nullable: true
          example: 3
        nf_sugars:
          type: number
          nullable: true
          example: 9
        nf_protein:
          type: number
          example: 25
        nf_potassium:
          type: number
          nullable: true
        nf_p:
          type: number
          nullable: true
        full_nutrients:
          type: array
          description: Complete list of nutrient values keyed by USDA attribute id.
          items:
            $ref: '#/components/schemas/FullNutrient'
        nix_brand_name:
          type: string
          nullable: true
          example: McDonald's
        nix_brand_id:
          type: string
          nullable: true
          example: 513fbc1283aa2dc80c000053
        nix_item_name:
          type: string
          nullable: true
          example: Big Mac
        nix_item_id:
          type: string
          nullable: true
          example: 513fc9e73fe3ffd40300109f
        metadata:
          type: object
          additionalProperties: true
        source:
          type: integer
          description: Internal source identifier for the food record.
          example: 8
        ndb_no:
          type: integer
          nullable: true
          description: USDA National Nutrient Database number for common foods.
        tags:
          type: object
          nullable: true
          additionalProperties: true
        alt_measures:
          type: array
          nullable: true
          description: Alternative serving measures for the food.
          items:
            $ref: '#/components/schemas/AltMeasure'
        photo:
          $ref: '#/components/schemas/Photo'
    FullNutrient:
      type: object
      description: A nutrient value identified by its USDA attribute id.
      properties:
        attr_id:
          type: integer
          description: USDA NUTR_DEF attribute identifier.
          example: 203
        value:
          type: number
          description: Nutrient value for the serving.
          example: 25
    AltMeasure:
      type: object
      description: An alternative serving measure for a food.
      properties:
        serving_weight:
          type: number
          example: 219
        measure:
          type: string
          example: burger
        seq:
          type: integer
          nullable: true
        qty:
          type: number
          example: 1
    Photo:
      type: object
      description: Image URLs associated with a food or exercise.
      properties:
        thumb:
          type: string
          format: uri
          nullable: true
          example: https://nix-tag-images.s3.amazonaws.com/402_thumb.jpg
        highres:
          type: string
          format: uri
          nullable: true
        is_user_uploaded:
          type: boolean
          default: false
    BrandSearchResponse:
      type: object
      description: Response from the brand search endpoint.
      properties:
        brands:
          type: array
          items:
            $ref: '#/components/schemas/Brand'
    Brand:
      type: object
      description: A food or restaurant brand.
      properties:
        _id:
          type: string
          example: 513fbc1283aa2dc80c000053
        name:
          type: string
          example: McDonald's
        website:
          type: string
          format: uri
          nullable: true
        type:
          type: integer
          description: Brand type (1 for restaurant, 2 for grocery/CPG).
          example: 1
    Error:
      type: object
      description: Standard error response.
      properties:
        message:
          type: string
          description: Human-readable error message.
        id:
          type: string
          description: Internal error identifier.