# Cook Nutrition API

> Nutrition lookup, aggregation, ingredient resolution and unit conversion for
> Cooklang recipes. Backed by USDA FoodData Central.

## Docs
- [OpenAPI 3.1 spec](/openapi.json): machine-readable contract (all endpoints, schemas, error shapes).
- [Interactive reference](/docs): Scalar UI with a Try-It console.
- [Report-template guides](/docs/guides): writing nutrition report templates (jinja extension).
- [MCP server](https://www.npmjs.com/package/@cookmd/nutrition-mcp): `npx -y @cookmd/nutrition-mcp` — stdio MCP
  server exposing render_report + nutrition tools for agent clients (Claude Code, Claude Desktop, Cursor).

## Endpoints
- GET /nutrition: nutrition for one ingredient (amount, unit, prep, region, reference).
- POST /aggregate: sum nutrition across a list of ingredients (a recipe or meal).
  Every item has an allergens block (status verified|unverified); /aggregate
  adds allergen_summary (contains = union over verified items — a floor when
  unverified_ingredients is non-empty; never treat absence as allergen-free).
- GET /ingredients/lookup: resolve a name/alias/translation to a canonical ingredient.
- GET /categories: list all categories (the valid slugs for the category check).
- GET /categories/{slug}/check: is an ingredient in a category?
- GET /convert: convert an amount between units for an ingredient.
- GET /reference-intakes: raw daily reference-intake tables (all standards or filtered by ?standard=).

## Tips for agents
- Prefer POST /aggregate for a whole recipe or meal instead of many /nutrition calls.
- Volume units (ml, l, tsp, tbsp, cup) need a recorded density; when you get
  `density_unavailable`, retry with a mass unit (g, kg, oz, lb).
- When the ingredient name is uncertain, call /ingredients/lookup first to get
  the canonical name and which preparations have data.
- On `ingredient_not_found`, check the `suggestions` field for close names, or
  call /ingredients/lookup first.
- `region` affects cup/tbsp/tsp sizing; valid values are `us` (default), `uk`, `metric`.
- Nutrition responses include a `reference_intakes` daily-value table (a
  `{nutrient_slug: value}` map) plus `reference_standard` at the top level.
  Select the standard with `reference=fda|eu|uk` (default `fda`) on `/nutrition`
  or the `reference` body field on `/aggregate`. Raw tables are at GET /reference-intakes.
- Errors follow RFC 9457 (application/problem+json) with a stable `code` plus
  `field`/`received`/`suggestions` to help you self-correct.