openapi: 3.2.0
info:
  title: Food Info API V1 API
  description: 'Nutrition data for millions of foods, merged from five national food-composition datasets: USDA FoodData Central (US), McCance & Widdowson''s CoFID (UK), ANSES Ciqual (France), the Danish Food Composition Database, and FSANZ AUSNUT (Australia/NZ), plus Open Food Facts for branded products.'
  contact:
    name: Food Info
    url: https://food-info.org/developer
    email: info@food-info.org
  version: v1
servers:
- url: https://api.food-info.org
security:
- {}
tags:
- name: api v1
paths:
  /api/v1/nutrients:
    get:
      tags:
      - api v1
      summary: List the nutrient catalogue (id, name, unit, category) so callers can discover…
      operationId: listNutrients
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NutrientDto'
  /api/v1/foods/search:
    get:
      tags:
      - api v1
      summary: Search foods by name (case-insensitive substring)
      operationId: searchFoods
      parameters:
      - name: q
        in: query
        schema:
          type: string
      - name: home_nation
        in: query
        schema:
          type: string
      - name: limit
        in: query
        schema:
          type: integer
          format: int32
          default: 25
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FoodSearchResultDto'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /api/v1/foods/{id}:
    get:
      tags:
      - api v1
      summary: Look up a single food by FoodData Central id
      operationId: getFood
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FoodSummaryDto'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /api/v1/foods/{id}/panel:
    get:
      tags:
      - api v1
      summary: 'Full nutrient panel for a food: grouped per-100 g + per-serving amounts and %…'
      operationId: getFoodNutrientPanel
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
          format: int32
      - name: portionId
        in: query
        schema:
          type: integer
          format: int32
      - name: source
        in: query
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FoodPanelDto'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /api/v1/nutrients/{nutrientId}/top-foods:
    get:
      tags:
      - api v1
      summary: 'Reverse nutrient search: reference foods richest in a nutrient, per 100 g…'
      operationId: listTopFoodsByNutrient
      parameters:
      - name: nutrientId
        in: path
        required: true
        schema:
          type: integer
          format: int32
      - name: home_nation
        in: query
        schema:
          type: string
      - name: limit
        in: query
        schema:
          type: integer
          format: int32
          default: 25
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TopByNutrientDto'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
  /api/v1/nutrients/{nutrientId}/bottom-foods:
    get:
      tags:
      - api v1
      summary: 'Inverse of top-foods: reference foods with the LEAST of a nutrient, per 100 g'
      operationId: listBottomFoodsByNutrient
      parameters:
      - name: nutrientId
        in: path
        required: true
        schema:
          type: integer
          format: int32
      - name: home_nation
        in: query
        schema:
          type: string
      - name: limit
        in: query
        schema:
          type: integer
          format: int32
          default: 25
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TopByNutrientDto'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
components:
  schemas:
    NutrientRefDto:
      type: object
      properties:
        id:
          type: integer
          format: int32
        name:
          type:
          - string
          - 'null'
        unit:
          type:
          - string
          - 'null'
      additionalProperties: false
      description: The nutrient a reverse-search was run for.
    PanelServingDto:
      type: object
      properties:
        portionId:
          type:
          - integer
          - 'null'
          format: int32
        label:
          type:
          - string
          - 'null'
        gramWeight:
          type: number
          format: double
        milliliters:
          type:
          - number
          - 'null'
          format: double
        massEstimated:
          type: boolean
      additionalProperties: false
    InflammationDto:
      type: object
      properties:
        score:
          type: number
          format: double
        paramCount:
          type: integer
          format: int32
        band:
          type:
          - string
          - 'null'
        isWholeFood:
          type: boolean
      additionalProperties: false
      description: 'Inflammatory-potential summary for a food. FoodInfo.Api.Dtos.InflammationDto.Band is "anti" / "neutral" / "pro".

        FoodInfo.Api.Dtos.InflammationDto.ParamCount (of 29) drives the UI confidence radial. FoodInfo.Api.Dtos.InflammationDto.IsWholeFood is true

        only for verified whole foods whose score may read anti-inflammatory; for everything else the score

        is floored at neutral and the UI shows "not rated for anti-inflammatory effect" instead of the radial.'
    TopByNutrientDto:
      type: object
      properties:
        nutrient:
          $ref: '#/components/schemas/NutrientRefDto'
        results:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/NutrientRankingDto'
      additionalProperties: false
      description: Result of GET /foods/top-by-nutrient.
    NutrientRowDto:
      type: object
      properties:
        nutrientId:
          type: integer
          format: int32
        name:
          type:
          - string
          - 'null'
        unit:
          type:
          - string
          - 'null'
        amountPer100g:
          type:
          - number
          - 'null'
          format: double
        amountPerServing:
          type:
          - number
          - 'null'
          format: double
        percentDailyValue:
          type:
          - number
          - 'null'
          format: double
        referenceAmount:
          type:
          - number
          - 'null'
          format: double
      additionalProperties: false
    NutrientRankingDto:
      type: object
      properties:
        foodId:
          type: integer
          format: int32
        description:
          type:
          - string
          - 'null'
        amount:
          type: number
          format: double
      additionalProperties: false
      description: One food in a "best sources of X" ranking — Amount is per 100 g, in the nutrient's unit.
    ProblemDetails:
      type: object
      properties:
        type:
          type:
          - string
          - 'null'
        title:
          type:
          - string
          - 'null'
        status:
          type:
          - integer
          - 'null'
          format: int32
        detail:
          type:
          - string
          - 'null'
        instance:
          type:
          - string
          - 'null'
      additionalProperties: {}
    FoodSearchResultDto:
      type: object
      properties:
        id:
          type: integer
          format: int32
        description:
          type:
          - string
          - 'null'
        ndbNumber:
          type:
          - string
          - 'null'
      additionalProperties: false
      description: Single search hit (`GET /foods/search`). Lean by design — clients pull the full panel via the id.
    FoodPanelDto:
      type: object
      properties:
        foodId:
          type: integer
          format: int32
        description:
          type:
          - string
          - 'null'
        foodCategory:
          type:
          - string
          - 'null'
        foodCategoryId:
          type:
          - integer
          - 'null'
          format: int32
        ndbNumber:
          type:
          - string
          - 'null'
        dataType:
          $ref: '#/components/schemas/DataType'
        source:
          $ref: '#/components/schemas/FoodSource'
        publicationDate:
          type:
          - string
          - 'null'
          format: date
        nameLanguage:
          type:
          - string
          - 'null'
        inflammation:
          $ref: '#/components/schemas/InflammationDto'
        dailyValueSource:
          type:
          - string
          - 'null'
        serving:
          $ref: '#/components/schemas/PanelServingDto'
        availableServings:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/PanelServingDto'
        groups:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/NutrientGroupDto'
        countries:
          type:
          - array
          - 'null'
          items:
            type: string
        relatedFoods:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/RelatedFoodDto'
        nutrientCount:
          type:
          - integer
          - 'null'
          format: int32
        canonicalFoodId:
          type:
          - integer
          - 'null'
          format: int32
      additionalProperties: false
      description: 'Self.com-style food page: assembled view with portions and grouped nutrient panel.'
    FoodSource:
      enum:
      - Fdc
      - CofidUk
      - Ciqual
      - Frida
      - Ausnut
      - OpenFoodFacts
      - Cnf
      - Fineli
      type: string
    DataType:
      enum:
      - SrLegacy
      - Foundation
      - Branded
      - SurveyFndds
      - Sample
      - AgriculturalAcquisition
      - MarketAcquisition
      - SubSample
      - Experimental
      - Other
      - CofidUk
      - Ciqual
      - Frida
      - Ausnut
      - OpenFoodFacts
      - Cnf
      - Fineli
      type: string
    NutrientDto:
      type: object
      properties:
        id:
          type: integer
          format: int32
        name:
          type:
          - string
          - 'null'
        unit:
          type:
          - string
          - 'null'
        category:
          type:
          - string
          - 'null'
        rank:
          type:
          - integer
          - 'null'
          format: int32
        hasRda:
          type: boolean
      additionalProperties: false
      description: 'A nutrient in the picker catalogue (GET /nutrients). FoodInfo.Api.Dtos.NutrientDto.HasRda is true when an

        established reference intake (RDA/DV) exists for it; the reverse-search picker defaults to

        these and hides the rest behind an opt-in. Optional positional default so other callers

        (e.g. the developer API) don''t have to supply it.'
    FoodSummaryDto:
      type: object
      properties:
        id:
          type: integer
          format: int32
        description:
          type:
          - string
          - 'null'
        ndbNumber:
          type:
          - string
          - 'null'
        dataType:
          $ref: '#/components/schemas/DataType'
        publicationDate:
          type:
          - string
          - 'null'
          format: date
      additionalProperties: false
      description: Compact food record for single-food lookup (`GET /foods/{id}`).
    NutrientGroupDto:
      type: object
      properties:
        name:
          type:
          - string
          - 'null'
        sortOrder:
          type: integer
          format: int32
        rows:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/NutrientRowDto'
      additionalProperties: false
    RelatedFoodDto:
      type: object
      properties:
        foodId:
          type: integer
          format: int32
        description:
          type:
          - string
          - 'null'
        source:
          type:
          - string
          - 'null'
      additionalProperties: false
  securitySchemes:
    ApiKey:
      type: apiKey
      description: Developer API key. Create one at https://food-info.org/developer
      name: X-Api-Key
      in: header