Food Data Central API — FDC

naftiko: 1.0.0-alpha2
info:
  label: Food Data Central API — FDC
  description: 'Food Data Central API — FDC. 9 operations. Lead operation: Fetches details for one food item by FDC ID. Self-contained
    Naftiko capability covering one National Agricultural Library business surface.'
  tags:
  - National Agricultural Library
  - FDC
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    NATIONAL_AGRICULTURAL_LIBRARY_API_KEY: NATIONAL_AGRICULTURAL_LIBRARY_API_KEY
capability:
  consumes:
  - type: http
    namespace: national-agricultural-library-fdc
    baseUri: https://api.nal.usda.gov/fdc
    description: Food Data Central API — FDC business capability. Self-contained, no shared references.
    resources:
    - name: v1-food-fdcId
      path: /v1/food/{fdcId}
      operations:
      - name: getfood
        method: GET
        description: Fetches details for one food item by FDC ID
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: fdcId
          in: path
          type: string
          description: FDC id of the food to retrieve
          required: true
        - name: format
          in: query
          type: string
          description: Optional. 'abridged' for an abridged set of elements, 'full' for all elements (default).
        - name: nutrients
          in: query
          type: array
          description: Optional. List of up to 25 nutrient numbers. Only the nutrient information for the specified nutrients
            will be returned. Should be comma separated list (e.g. nu
    - name: v1-foods
      path: /v1/foods
      operations:
      - name: getfoods
        method: GET
        description: Fetches details for multiple food items using input FDC IDs
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: fdcIds
          in: query
          type: array
          description: List of multiple FDC ID's. Should be comma separated list (e.g. fdcIds=534358,373052) or repeating
            parameters (e.g. fdcIds=534358&fdcIds=373052).
          required: true
        - name: format
          in: query
          type: string
          description: Optional. 'abridged' for an abridged set of elements, 'full' for all elements (default).
        - name: nutrients
          in: query
          type: array
          description: Optional. List of up to 25 nutrient numbers. Only the nutrient information for the specified nutrients
            will be returned. Should be comma separated list (e.g. nu
      - name: postfoods
        method: POST
        description: Fetches details for multiple food items using input FDC IDs
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: v1-foods-list
      path: /v1/foods/list
      operations:
      - name: getfoodslist
        method: GET
        description: Returns a paged list of foods, in the 'abridged' format
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: dataType
          in: query
          type: array
          description: Optional. Filter on a specific data type; specify one or more values in an array.
        - name: pageSize
          in: query
          type: integer
          description: Optional. Maximum number of results to return for the current page. Default is 50.
        - name: pageNumber
          in: query
          type: integer
          description: Optional. Page number to retrieve. The offset into the overall result set is expressed as (pageNumber
            * pageSize)
        - name: sortBy
          in: query
          type: string
          description: Optional. Specify one of the possible values to sort by that field. Note, dataType.keyword will be
            dataType and lowercaseDescription.keyword will be description
        - name: sortOrder
          in: query
          type: string
          description: Optional. The sort direction for the results. Only applicable if sortBy is specified.
      - name: postfoodslist
        method: POST
        description: Returns a paged list of foods, in the 'abridged' format
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: v1-foods-search
      path: /v1/foods/search
      operations:
      - name: getfoodssearch
        method: GET
        description: Returns a list of foods that matched search (query) keywords
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: query
          in: query
          type: string
          description: One or more search terms.  The string may include [search operators](https://fdc.nal.usda.gov/help.html#bkmk-2)
          required: true
        - name: dataType
          in: query
          type: array
          description: Optional. Filter on a specific data type; specify one or more values in an array.
        - name: pageSize
          in: query
          type: integer
          description: Optional. Maximum number of results to return for the current page. Default is 50.
        - name: pageNumber
          in: query
          type: integer
          description: Optional. Page number to retrieve. The offset into the overall result set is expressed as (pageNumber
            * pageSize)
        - name: sortBy
          in: query
          type: string
          description: Optional. Specify one of the possible values to sort by that field. Note, dataType.keyword will be
            dataType and lowercaseDescription.keyword will be description
        - name: sortOrder
          in: query
          type: string
          description: Optional. The sort direction for the results. Only applicable if sortBy is specified.
        - name: brandOwner
          in: query
          type: string
          description: Optional. Filter results based on the brand owner of the food. Only applies to Branded Foods
      - name: postfoodssearch
        method: POST
        description: Returns a list of foods that matched search (query) keywords
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: v1-json-spec
      path: /v1/json-spec
      operations:
      - name: getjsonspec
        method: GET
        description: Returns this documentation in JSON format
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: v1-yaml-spec
      path: /v1/yaml-spec
      operations:
      - name: getyamlspec
        method: GET
        description: Returns this documentation in JSON format
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    authentication:
      type: apikey
      key: api_key
      value: '{{env.NATIONAL_AGRICULTURAL_LIBRARY_API_KEY}}'
      placement: query
  exposes:
  - type: rest
    namespace: national-agricultural-library-fdc-rest
    port: 8080
    description: REST adapter for Food Data Central API — FDC. One Spectral-compliant resource per consumed operation, prefixed
      with /v1.
    resources:
    - path: /v1/v1/food/{fdcid}
      name: v1-food-fdcid
      description: REST surface for v1-food-fdcId.
      operations:
      - method: GET
        name: getfood
        description: Fetches details for one food item by FDC ID
        call: national-agricultural-library-fdc.getfood
        with:
          fdcId: rest.fdcId
          format: rest.format
          nutrients: rest.nutrients
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v1/foods
      name: v1-foods
      description: REST surface for v1-foods.
      operations:
      - method: GET
        name: getfoods
        description: Fetches details for multiple food items using input FDC IDs
        call: national-agricultural-library-fdc.getfoods
        with:
          fdcIds: rest.fdcIds
          format: rest.format
          nutrients: rest.nutrients
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: postfoods
        description: Fetches details for multiple food items using input FDC IDs
        call: national-agricultural-library-fdc.postfoods
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v1/foods/list
      name: v1-foods-list
      description: REST surface for v1-foods-list.
      operations:
      - method: GET
        name: getfoodslist
        description: Returns a paged list of foods, in the 'abridged' format
        call: national-agricultural-library-fdc.getfoodslist
        with:
          dataType: rest.dataType
          pageSize: rest.pageSize
          pageNumber: rest.pageNumber
          sortBy: rest.sortBy
          sortOrder: rest.sortOrder
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: postfoodslist
        description: Returns a paged list of foods, in the 'abridged' format
        call: national-agricultural-library-fdc.postfoodslist
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v1/foods/search
      name: v1-foods-search
      description: REST surface for v1-foods-search.
      operations:
      - method: GET
        name: getfoodssearch
        description: Returns a list of foods that matched search (query) keywords
        call: national-agricultural-library-fdc.getfoodssearch
        with:
          query: rest.query
          dataType: rest.dataType
          pageSize: rest.pageSize
          pageNumber: rest.pageNumber
          sortBy: rest.sortBy
          sortOrder: rest.sortOrder
          brandOwner: rest.brandOwner
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: postfoodssearch
        description: Returns a list of foods that matched search (query) keywords
        call: national-agricultural-library-fdc.postfoodssearch
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v1/json-spec
      name: v1-json-spec
      description: REST surface for v1-json-spec.
      operations:
      - method: GET
        name: getjsonspec
        description: Returns this documentation in JSON format
        call: national-agricultural-library-fdc.getjsonspec
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v1/yaml-spec
      name: v1-yaml-spec
      description: REST surface for v1-yaml-spec.
      operations:
      - method: GET
        name: getyamlspec
        description: Returns this documentation in JSON format
        call: national-agricultural-library-fdc.getyamlspec
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: national-agricultural-library-fdc-mcp
    port: 9090
    transport: http
    description: MCP adapter for Food Data Central API — FDC. One tool per consumed operation, routed inline through this
      capability's consumes block.
    tools:
    - name: fetches-details-one-food-item
      description: Fetches details for one food item by FDC ID
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: national-agricultural-library-fdc.getfood
      with:
        fdcId: tools.fdcId
        format: tools.format
        nutrients: tools.nutrients
      outputParameters:
      - type: object
        mapping: $.
    - name: fetches-details-multiple-food-items
      description: Fetches details for multiple food items using input FDC IDs
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: national-agricultural-library-fdc.getfoods
      with:
        fdcIds: tools.fdcIds
        format: tools.format
        nutrients: tools.nutrients
      outputParameters:
      - type: object
        mapping: $.
    - name: fetches-details-multiple-food-items-2
      description: Fetches details for multiple food items using input FDC IDs
      hints:
        readOnly: true
        destructive: false
        idempotent: false
      call: national-agricultural-library-fdc.postfoods
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: returns-paged-list-foods-abridged
      description: Returns a paged list of foods, in the 'abridged' format
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: national-agricultural-library-fdc.getfoodslist
      with:
        dataType: tools.dataType
        pageSize: tools.pageSize
        pageNumber: tools.pageNumber
        sortBy: tools.sortBy
        sortOrder: tools.sortOrder
      outputParameters:
      - type: object
        mapping: $.
    - name: returns-paged-list-foods-abridged-2
      description: Returns a paged list of foods, in the 'abridged' format
      hints:
        readOnly: true
        destructive: false
        idempotent: false
      call: national-agricultural-library-fdc.postfoodslist
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: returns-list-foods-that-matched
      description: Returns a list of foods that matched search (query) keywords
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: national-agricultural-library-fdc.getfoodssearch
      with:
        query: tools.query
        dataType: tools.dataType
        pageSize: tools.pageSize
        pageNumber: tools.pageNumber
        sortBy: tools.sortBy
        sortOrder: tools.sortOrder
        brandOwner: tools.brandOwner
      outputParameters:
      - type: object
        mapping: $.
    - name: returns-list-foods-that-matched-2
      description: Returns a list of foods that matched search (query) keywords
      hints:
        readOnly: true
        destructive: false
        idempotent: false
      call: national-agricultural-library-fdc.postfoodssearch
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: returns-this-documentation-json-format
      description: Returns this documentation in JSON format
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: national-agricultural-library-fdc.getjsonspec
      outputParameters:
      - type: object
        mapping: $.
    - name: returns-this-documentation-json-format-2
      description: Returns this documentation in JSON format
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: national-agricultural-library-fdc.getyamlspec
      outputParameters:
      - type: object
        mapping: $.