# Decent Cookbooks API

Read-only cookbook recipes with every ingredient weighed in grams, and each dish's spice mixes (masalas) weighed spice by spice so they can be made on a scale. Each recipe also has Decent's own method, description, nutrition, heat and fragrance ratings, substitutes, vegetarian and vegan swaps, and comparisons with similar dishes. Free to use; please credit (see below).

- **JSON version of this page:** <https://decentespresso.com/cookbooks/api/index.json> (Markdown: <https://decentespresso.com/cookbooks/api/?format=md>)
- **OpenAPI description:** <https://decentespresso.com/cookbooks/api/openapi.json>
- **Site description for AI agents:** <https://decentespresso.com/cookbooks/llms.txt>

## Books

| id | Section | Source books | Recipes | Ingredients | Web |
|---|---|---|---|---|---|
| `indian` | Indian cooking | *India: Cookbook* by Pushpesh Pant (Phaidon, 2010); *Curry* by Maunika Gowardhan (Quadrille, 2025); *Thali: Create and Eat Indian Thalis at Home* by Maunika Gowardhan (Hardie Grant, 2021); *Tandoori Home Cooking* by Maunika Gowardhan (Hardie Grant, 2023); *Indian Kitchen: Secrets of Indian Home Cooking* by Maunika Gowardhan (Hodder & Stoughton, 2015); *Kricket: An Indian-inspired Cookbook* by Will Bowlby (Hardie Grant, 2018) | 1566 (1502 dishes, 64 spice mixtures and pastes) | 1187 | <https://decentespresso.com/cookbooks/indian/> |

## Endpoints

All responses are JSON (`application/json; charset=utf-8`), allow cross-origin requests, and include a `license` block. A recipe or ingredient is named by its `slug` (as listed), or its exact name URL-encoded; an ingredient also by its Indian name.

| Endpoint | Returns | Example |
|---|---|---|
| `GET /cookbooks/api/{book}` | the book: counts, main-ingredient categories, source, licence | <https://decentespresso.com/cookbooks/api/indian> |
| `GET /cookbooks/api/{book}/recipes?offset=&limit=` | recipes, at most 50 per page, with `next`; each with `slug`, `subtitle`, `kind`, `diet`, `heat_level`, `kcal_per_portion` and links | <https://decentespresso.com/cookbooks/api/indian/recipes?limit=10> |
| … `&kind=dish` or `blend` | dishes, or spice mixtures and pastes | <https://decentespresso.com/cookbooks/api/indian/recipes?kind=blend&limit=10> |
| … `&diet=vegan` | recipes that already suit a diet: `vegan`, `vegetarian`, `pescatarian` or `omnivore` | <https://decentespresso.com/cookbooks/api/indian/recipes?diet=vegan&limit=10> |
| … `&main=Lentils` | dishes with that main ingredient (the names are in `/{book}`) | <https://decentespresso.com/cookbooks/api/indian/recipes?main=Lentils&limit=10> |
| … `&heat=2` | at most that hot, 0 (not hot) to 5 (fiery) | <https://decentespresso.com/cookbooks/api/indian/recipes?heat=1&limit=10> |
| `GET /cookbooks/api/{book}/recipes/{slug}` | one recipe in full | <https://decentespresso.com/cookbooks/api/indian/recipes/butter-chicken> |
| `GET /cookbooks/api/{book}/ingredients?offset=&limit=` | ingredient names, Indian names, kinds and links | <https://decentespresso.com/cookbooks/api/indian/ingredients?limit=10> |
| `GET /cookbooks/api/{book}/ingredients/{slug}` | one ingredient: weights, nutrition, heat, substitutes, swaps and the recipes using it | <https://decentespresso.com/cookbooks/api/indian/ingredients/haldi> |
| `GET /cookbooks/api/{book}/search?q=` | recipes and ingredients matching `q` (English or Indian names) | <https://decentespresso.com/cookbooks/api/indian/search?q=paneer> |

## A recipe

<https://decentespresso.com/cookbooks/api/indian/recipes/butter-chicken> gives:

| Field | What it is |
|---|---|
| `name`, `subtitle`, `slug` | the recipe's name, its English subtitle, and its id in URLs |
| `kind` | `dish`, or `blend`: a spice mixture, paste or basic that other recipes use |
| `chapter`, `origin`, `prep_time`, `cook_time`, `serves`, `makes` | as in the book |
| `feeds` | how many portions it makes: each portion is the dish's share of a meal of several dishes (rice or bread, a dal, a curry), the way Indian meals are eaten |
| `diet`, `main_ingredients` | `vegan`, `vegetarian`, `pescatarian` or `omnivore`; its 1-3 main ingredients |
| `description` | Decent's description of the dish |
| `masalas[]` | each spice mix, in the order it's used: `number`, `name`, `when` it goes in, what to do once it's weighed (`finish`), `total_grams`. Make one on the Half Decent Scale from the recipe's web page |
| `ingredients[]` | every ingredient line: `name`, `indian` name, `kind`, `stage` (masala, marinade, main, garnish), `grams` (with `grams_max` for a range, `estimate` true for a pinch or a handful), `book_amount` as the book writes it, `prep`, `optional`, `masala` (which spice mix it belongs to), `api_url`, and `uses_recipe` when the line is another recipe (a paste or masala) |
| `method[]` | Decent's own steps, with the weighed amounts |
| `nutrition` | `kcal` for the whole dish and `kcal_per_portion`; `fat`, `carb` and `protein`, each with `kcal`, `kcal_per_portion` and `percent`; `cooked_grams`, `portion_grams` |
| `heat` | `level` 0-5 and its `label`, worked out from each chilli's type and weight against the cooked dish (`scoville`); the book's own `book_rating` (0-3) |
| `fragrance` | `level` 0-3 and `label`, from the grams of spice per kg (`spice_grams_per_kg`) |
| `diet_swaps` | for `pescatarian`, `vegetarian` and `vegan`: what to use `instead_of` each ingredient that breaks it, `grams_per_gram`, and a `tip` |
| `similar[]` | the closest recipes by shared ingredients: what's the `same`, what's `different`, and how it tastes (`taste`) |
| `other_versions` | the book's other recipes of the same name |
| `image_url`, `images` | Decent's AI-generated photo of the dish (see Pictures) |
| `web_url`, `source_book`, `page` | the recipe's page on our site; the book it comes from (`id`, title, authors, publisher, year, ISBN) and its page (null when the book's ebook gives none) |
| `cite_as`, `license` | a ready-made credit line, and the licence |

## An ingredient

<https://decentespresso.com/cookbooks/api/indian/ingredients/haldi> gives `name`, `english` (its English name when the name is an Indian word: Amchoor is "Dried mango powder"), `indian`, `kind` (spice, aromatic, vegetable, meat...), `cupboard_staple` (counted in My Kitchen), `diet`; `weights` (`grams_per_teaspoon`, `grams_per_tablespoon`, `grams_per_piece` and what a `piece` is: a pod, a clove, a medium onion); `per_100g` (kcal, fat, carb, protein); `scoville` for chillies; `substitutes` (each with a `tip`, and its own `api_url` when the book uses it too), `no_true_substitute` (why, when nothing really replaces it), `vegetarian_swaps`, `diet_swaps`; the `recipes` that use it; `image_url`, `images` and `web_url`.

## Pictures

Every dish, spice mixture and ingredient has an AI-generated picture by Decent, on white. A recipe's or ingredient's `images` lists the URL of each copy that exists, so you needn't build them. To build them yourself, start from the picture's **name**, the path below `https://fast.decentespresso.com/cookbooks/img/` without the extension (`dishes/butter_chicken`, `ingredients/amchoor`); it is `images.name`, and the `image` column of the `dish` and `ingredient` tables. For a name `{dir}/{n}`:

| Copy | URL below /cookbooks/img/ | Size | Made for |
|---|---|---|---|
| `png` | `{dir}/{n}.png` | 1024×1024 | the master; large, about 1 MB |
| `jpg`, `avif` | `{dir}/{n}.jpg`, `.avif` | white margins trimmed; dishes 840px, ingredients 560px on the long side | the recipe page's photo |
| `thumb` | `{dir}/t/{n}.jpg` | dishes 360px, ingredients 192px | small pictures: cards, lists, recipe rows |
| `thumb_avif` | `{dir}/t/{n}.avif` | dishes 240px, ingredients 128px | the same, smaller, for browsers with AVIF |

How a name is made, should you have only the recipe's name: lowercase it, turn each run of characters other than letters and digits into one `_`, and trim `_` from the ends; a dish is `dishes/{that}`, an ingredient `ingredients/{that}`. The pictures are Decent's own and CC BY 4.0, as below.

## MCP server

For AI assistants (Claude and others), the same recipes are an MCP server: https://decentespresso.com/cookbooks/mcp (its guide: https://decentespresso.com/cookbooks/mcp in a browser). No account is needed to connect or for recipes; with a free decentespresso.com account, which the app asks for the first time a member tool is used (or connect https://decentespresso.com/cookbooks/mcp/account to sign in when connecting), it also keeps My Kitchen (the spices and staples in your cupboard, in one or more kitchens) and tells you which dishes you can cook, plus the Liked and Made lists, shared with the website.

## Your own data

Signed in (the website's login, or an OAuth bearer token), `https://decentespresso.com/cookbooks/api/me` is your own Liked and Made dishes, My Kitchen and sharing, the same data the website and the MCP server use. It is never cached and not rate-limited. A dish is its book's key (`india_cookbook`, `curry`, `thali`, `tandoori`, `indian_kitchen`, `kricket`) and its name, URL-encoded (a name may hold a slash).

| Request | What it does |
|---|---|
| `GET /cookbooks/api/me` | everything: `liked` and `made` (each `book`, `dish`, and `liked_at` or `last_made_at` and `times_made`, Unix seconds or null), `kitchen` (`cur` and `locs`, each with `id`, `name` and `have`: ingredient names, and `@Spice Mixture` for one you have made), `prefs`, `share` and `following` |
| `PUT /cookbooks/api/me/liked/{book}/{dish}` | like a dish; `DELETE` takes it off |
| `PUT /cookbooks/api/me/made/{book}/{dish}` | made it now (`?source=web`, `done` or `app`; making it again re-dates it and counts it); `DELETE` takes it off |
| `PUT /cookbooks/api/me/kitchen/items/{name}` | an ingredient into the current kitchen location; `DELETE` takes it out |
| `PUT /cookbooks/api/me/kitchen` | the whole kitchen, as `GET` gives it (form field `kitchen`, or the body) |
| `PUT /cookbooks/api/me/prefs` | any of `hide_unmakeable`, `share_made`, `share_liked` (0 or 1) |
| `PUT /cookbooks/api/me/following/{userid}` | add a member who shares to your kitchen menu; `DELETE` removes them |

Without a login these answer 401.

## Limits

- 60 requests per minute per IP address; over that you get HTTP 429 with `Retry-After`.
- There is no bulk download. Fetch the recipes you need, one at a time.
- Responses may be cached for an hour.

## Why we can publish these recipes

A recipe's ingredients and amounts are facts, and facts can't be copyrighted. The same goes for a dish's name, how many it serves, its cooking times and the region it comes from. The US Copyright Office says this directly: a "mere listing of ingredients" is not protected ([Circular 33](https://www.copyright.gov/circs/circ33.pdf)). Most other countries take the same view. What copyright does protect is the author's own writing: their stories, descriptions and instructions. We haven't reproduced any of that.

This isn't a copy of the books. We rebuilt every recipe as weighed steps: each amount converted to grams, each spice mix weighed spice by spice, and every method rewritten in our own words. Then we added what the books don't have: nutrition, heat and fragrance ratings, substitutes for every ingredient, vegetarian and vegan swaps, comparisons with similar dishes, our own descriptions and pictures, and ways to browse by main ingredient and by what's in your kitchen.

We built this because these books are wonderful, and we wanted their dishes to be easy to weigh, compare and cook. If you enjoy them, please buy the books. The stories and writing in them are worth having, and you won't find them here.

## Licence and credit

- **Decent's own content** is licensed under [Creative Commons Attribution 4.0](https://creativecommons.org/licenses/by/4.0/) (CC BY 4.0), to the extent Decent Espresso Ltd holds rights in it: the descriptions, the method wording, the spice-mix names and notes, the nutrition, heat and fragrance figures, portions, substitutes and diet swaps, similar-dish comparisons, and the AI-generated pictures.
- **The recipe facts** (recipe names, ingredients and amounts, servings, times and regions) come from the books above. They are facts, so Decent claims no rights in them and offers no licence for them. Please buy the books.
- **Nothing else comes from the books:** no text, photographs or illustrations; every picture was made by Decent. Recipes are served one at a time, never as a whole book. We have no licence or permission from the books' publishers: we don't need one for facts, and we use nothing else.
- Nutrition figures are estimates from standard food-composition values for the ingredients as weighed.
- **How to credit:** name "Decent Cookbooks" with a link to the recipe's `web_url`, and the source book. Every recipe response has a ready-made `cite_as`.
- **Questions**, including from authors and publishers: https://decentespresso.com/support/submit. Licence page: https://decentespresso.com/cookbooks/license · Privacy: https://decentespresso.com/cookbooks/privacy