# Health & Nutrition Facts — agent instructions

Service ID: `nb:health-nutrition-facts` · version 0.1.0 · status **Beta** · consumable: **true**

Developer API for US USDA FoodData Central and the UK CoFID 2021 food composition dataset, returning source IDs, nutrient units, data basis and provenance.

> **Public beta.** USDA FoodData Central (US) and CoFID 2021 (UK) routes are live with `payment=false` free previews, limited to five requests per minute per client IP. Paid routes use x402 Base Sepolia testnet.

## REST routes
- `GET https://bb457y9nc28rvwv3.7dn.lambda-web.eu-west-2.on.aws/v1/nutrition/us/search?q=black%20beans&limit=5&payment=false` — free USDA FoodData Central search.
- `GET https://bb457y9nc28rvwv3.7dn.lambda-web.eu-west-2.on.aws/v1/nutrition/us/foods/{fdc_id}?payment=false` — retrieve an exact USDA FDC record.
- `GET https://bb457y9nc28rvwv3.7dn.lambda-web.eu-west-2.on.aws/v1/nutrition/uk/search?q=porridge%20oats&limit=5&payment=false` — free search of the pinned CoFID 2021 snapshot.
- `GET https://bb457y9nc28rvwv3.7dn.lambda-web.eu-west-2.on.aws/v1/nutrition/uk/foods/{food_code}?payment=false` — retrieve an exact CoFID record.

US lookups use the server-side USDA FoodData Central credential. UK lookups use the bundled CoFID 2021 dataset. Missing and trace values are preserved; this is not medical advice.

## Does not do
- medical, clinical, diet or treatment advice
- recipe nutrition estimates or nutrient totals for prepared meals
- allergen-safety determinations
- guaranteed product label accuracy or current branded-food availability

## Connection
- Endpoint: https://bb457y9nc28rvwv3.7dn.lambda-web.eu-west-2.on.aws
- Transport: http-rest
- Auth: none
- Manifest: /manifests/health-nutrition-facts/0.1.0.json

## Tools

| Tool | Built | Read-only | Price |
|---|---|---|---|
| `nutrition_us_search` | yes | yes | 0.005 USDC per call [x402-exact, not approved] |
| `nutrition_us_get` | yes | yes | 0.005 USDC per call [x402-exact, not approved] |
| `nutrition_uk_search` | yes | yes | 0.005 USDC per call [x402-exact, not approved] |
| `nutrition_uk_get` | yes | yes | 0.005 USDC per call [x402-exact, not approved] |

## Data
- Coverage: US on-demand search/detail from USDA FoodData Central; UK search/detail from all 2,886 food records in a versioned CoFID 2021 snapshot. The API preserves provider IDs, nutrient units, source basis, and CoFID trace/not-reported statuses.
- Freshness: US data is fetched from the live FDC API for each successful request. UK data is a pinned CoFID 2021 release; it changes only when a new source snapshot is imported and released.
- Document schema: `/schemas/health-nutrition-facts-v1.json`
- Sources:
  - USDA FoodData Central API (CC0 1.0; attribution requested to USDA Agricultural Research Service)
  - McCance and Widdowson’s Composition of Foods Integrated Dataset (CoFID 2021) (Open Government Licence v3.0)

## Limitations
- FDC nutrient basis varies by record type and is returned as provider-reported; callers should inspect the source record before comparing values
- CoFID nutrient basis is preserved per nutrient; most values are per 100 g of food, while fatty-acid tables may use a fatty-acid basis
- A missing, trace or not-detected source value is not converted to zero
- Records are food-composition references, not lab measurements of a particular product or meal
- Search is text matching and does not guarantee that similarly named foods are equivalent
- The data is informational only, not medical or clinical advice

## Rights
- Status: open_data
- Attribution: US: USDA Agricultural Research Service, FoodData Central.
- Attribution: UK: Crown copyright, McCance and Widdowson’s CoFID 2021, Open Government Licence v3.0.

See also: /agents/payments.md · /agents/security.md · /agents/licensing.md