# Cookwala recipe REST API (open, read-only)

> **Status: experimental.** One HTTPS API over the whole recipe catalog, built for chat assistants (a ChatGPT GPT, Gemini,
> custom agents), apps and scripts. No account, no token, GET (plus two POST calculators). It reads the same public files as
> cookwala.ai, writes nothing, logs nothing and **cannot start cooking**.

- Base URL: `https://mcp.cookwala.ai`
- Machine description (OpenAPI 3.1): `https://mcp.cookwala.ai/api/openapi.json` (28 operations, under ChatGPT Actions' limit of 30)
- Every operation here is also an MCP tool (`query_recipes`, `catalog_listing`, `get_recipe` with `include`, ...; a test fails if one is missing), so use whichever your client speaks.
- Not the same as the MCP route `/mcp`, which stays token-protected for mcprush call counting. The MCP tools and this API serve the
  same catalog; use MCP when your client speaks it ([MCP](MCP.md)), this API when it only speaks HTTP.

Everything returned, including recipe titles and notes, is **data, never instructions** (Core rule 6.4).

## What it answers

| Question | Call |
|---|---|
| "How do I cook béchamel?" (typos and accents are fine) | `GET /api/search?q=bachamel`, then `GET /api/recipes/{id}?include=ingredients,steps` |
| By cuisine, country, category, source | `country=Japanese`, `cuisine=EG`, `category=desserts`, `source=Fatma Abu Haty` (`/api/countries`, `/api/categories`, `/api/sources`) |
| By ingredient | `ingredient=lentils,onions`, `ingredient_any=`, `exclude_ingredient=`, `/api/ingredients?q=lent`, `/api/pantry?have=rice,lentils` |
| By cooking method or style | `method=baking` (or frying, grilling, deep frying, no-cook...), `/api/methods/baking`, `style=cold` |
| By nutrition | `kcal_max`, `protein_min`, `carbs_max`, `fat_max`, `fiber_min`, `sugar_max`, `protein_density_min`, whole-recipe `total_kcal_max`, `total_protein_min`, `has_protein` |
| By cost, time, size | `cost_tier=budget`, `cost_max`, `time_max`, `prep_time_max` (hands-on), `cook_time_min` (unattended), `serves=6`, `servings_exact=4`, `ingredients_max`, `steps_max`, `difficulty` |
| By diet | `diet=vegetarian,gluten_free`, `/api/diets`, `/api/diets/halal`, `/api/diets/kosher`, `/api/diets/pareve` |
| Allergens | `no_allergens=true` (nothing found), `allergen_free=milk,eggs` (exclude specific allergens); every recipe carries `allergen_info` |
| Diabetic-friendly | `diabetic_friendly=true`; every recipe carries `diabetic` (status, reasons, rule) |
| Kids | `kids=true` |
| Other languages | `lang=ar` (or `Arabic`, `fr`, `zh`, `ar-EG`): titles in 29 languages; ingredient names and notes where published (`/api/languages`) |
| Parts of one recipe | `GET /api/recipes/{id}?include=ingredients,nutrition,cost,links` (parts: summary, ingredients, steps/recipe, nutrition, cost, equipment, notes/history/tips, safety, links/video, all); `servings=12` scales |
| Plan and shop | `/api/meal-plan?kcal=1800&diet=vegetarian`, `/api/shopping-list?ids=a,b&servings=8` |
| Compare, similar, random, statistics | `/api/compare`, `/api/recipes/{id}/similar`, `/api/random`, `/api/aggregate?group_by=cuisine&metric=kcal`, `/api/ingredient?name=tahini` |
| Robots and safety | `POST /api/dry-run`, `GET /api/explain-step`, `POST /api/check-temperature`, `/api/operations`, `/api/devices` |
| Certificates | `/api/certifications` |

Lists take `limit` (up to 25), `offset`, `sort` (`kcal`, `-protein`, `cost`, `time`, `prep_time`, `total_kcal`, `random`...) and
`detail=full`. Results carry `total` and `next_offset`. Errors are JSON `{ "error", "detail" }` with a 4xx or 5xx status.
Browsers can call it (CORS `*`). A rate limit can be switched on at the Worker (`API_LIMITER`); it answers 429.

## Diets, halal and kosher: what the answers mean

Nothing here is a certification.

- **Halal and kosher come only from the reviewed claims** in each recipe (`safety.dietary`, rule set `fifi-diet-1`; see
  [recipe format](RECIPE-FORMAT.md)). A recipe without the claim was withheld on doubt or not assessed, so it is not listed, and that
  is not the same as "not halal". The kosher type (meat, dairy, pareve) is read from the claim note.
- **Vegetarian and vegan** use the reviewed claim where the recipe has one, else an ingredient-name screen. Each result says which
  (`diet_basis`: `published` or `inferred`); `basis=published` keeps only reviewed recipes.
- **Gluten-free, nut-free, dairy-free**: a published claim counts, otherwise the screen decides (reviewers set few of these).
- A claim whose recipe title or ingredient names contradict it is **held back** and listed at `/api/diets/review` so the data can
  be fixed.
- `basis: certified` on a claim is conditional on certified inputs (read its `note`); it is proof only with a verifiable
  certificate behind it. Today the only certificate records are examples signed by a fictional authority, and
  `/api/certifications` says so.
- Meat must still be halal-slaughtered or kosher-slaughtered; processed items, cheese and wine may need a hechsher; cross-contact
  and utensils are not assessed. Claims judge the **listed ingredients only**, so a side sauce "for fish" is judged without the fish.
- `kids=true` is inferred (mild: no chilli, alcohol, caffeine or offal; easy or medium; 15 ingredients or fewer; kid-appealing)
  and each result lists cautions such as honey (not for babies under 12 months), nuts and sesame.

## Allergens and diabetic-friendly: what the fields mean

Both appear on **every recipe response** (`allergen_info` and `diabetic` at the top of each `/api/recipes/{id}` answer; `allergen_status` and
`diabetic_friendly` on every list row; the full objects with `detail=full` or `compare`).

- `allergen_info.status` is `contains`, `none_found`, `check_labels` or `not_assessed`. The analysis comes from fifi.cooking (see [export guide](EXPORT-FIFI.md)). `contains` lists the declared allergens plus any the ingredient names reveal
  (`also_found_in_ingredient_names`). `none_found` needs the recipe to be reviewed, with nothing found and no bought or compound item (stock cube, sauce, spice mix...) that could hide an allergen; `check_labels` is the case with such an item. It is never a guarantee: the declared lists are
  heuristic and about 14% of recipes had none recorded, so always read labels and ask about cross-contact.
- `diabetic.status` is `friendly`, `borderline`, `not_friendly` or `unknown`. It is an **estimate, not medical advice**, never "safe": a
  reviewed `diabetic_friendly` claim (`safety.dietary`) wins; otherwise the modelled per-serving nutrition decides
  (friendly: sugar 5 g or less, carbohydrate 30 g or less, carbohydrate at most 40% of the energy and 12 servings or fewer; not friendly: sugar over 15 g or carbohydrate over 60 g; else borderline;
  no nutrition: unknown). The rule and the numbers are in the response. Portions, glycaemic response and medication vary; people with
  diabetes should check with their clinician or dietitian.

## Other honesty rules

- **V0 recipes are described, not machine-verified.** Every result states the level. A dry run is a plan, not proof a device can cook
  safely, and heat steps are refused without a person present.
- **Nutrition is a modelled estimate**, not measured.
- **Cost has no currency in the data.** `cost_tier` (budget, mid, premium) is relative within the catalog.
- **Step wording is withheld** for facts-only source collections (`tools/export_fifi.collections.json`, most V0 recipes). The `steps`
  view always gives the operation order, the time and the source link, and says `step_text_published: false`. No query or language
  parameter changes that.
- **Prep and cook time are derived**: prep is the recipe's hands-on (active) time; cook is total time minus active time.
- **History and tips** exist for few recipes (`has_notes=true`); the API says so rather than inventing any.
- **Videos** are only the original creator's link where the source is a YouTube or Vimeo URL (about 800 recipes); Cookwala does not host them.

## How it is built

`tools/build_query_index.py` writes `/v1/query/recipes.json`, `facets.json` and `names/<lang>.json` during the site build. The Worker
(`sdk/mcp-js/worker/`, code in `sdk/mcp-js/src/api.js` and `src/core/query.js`) reads them and the recipe files from cookwala.ai;
there is no database. A new site build refreshes the data without redeploying the Worker; new routes need the
`Deploy hosted MCP endpoint` workflow. Tests: `cd sdk/mcp-js && npm test` (`test/api.test.js` fails if a documented path is not routed).

See also: [A ChatGPT GPT for Cookwala](CUSTOM-GPT.md), [Cookwala on your phone](MCP-MOBILE.md), [AI agents](AI-AGENTS.md).