Tiny Plates
Recipe API and MCP server for structured recipes, semantic search, pantry matching, serving adjustments, and shopping lists.
Gehosteter MCP-Server
npx add-mcp 'https://api.tinyplates.dev/mcp'Installiert in Claude Code, Codex, Cursor und mehr
Dokumentation
Use from your agent
The API is also an MCP server, so a coding agent such as Claude Code, Codex, Cursor or VS Code can search recipes, cook from a pantry and build shopping lists on its own. You sign in with your Tiny Plates account; there is no key to copy.
Connecting
https://api.tinyplates.dev/mcp
- Add the server for every project:
claude mcp add --transport http --scope user \ tinyplates https://api.tinyplates.dev/mcp - Sign in: run /mcp in Claude Code, pick tinyplates and choose Authenticate, or from your shell:
claude mcp login tinyplates
Use an API key instead
Add the server with your key as a header:
claude mcp add --transport http --scope user \
--header "Authorization: Bearer rd_your_api_key" \
tinyplates https://api.tinyplates.dev/mcp
Tools
build_shopping_list
Build a shopping list
Build one shopping list from several recipes, grouped by aisle, with quantities added up across recipes. A recipe asked for at a different serving count is scaled first. A line may also carry extras: amounts a recipe asked for in a unit its quantity cannot take, such as the 3 tbsp in "1 cup + 3 tbsp". They are not folded into quantity, so buy them as well.
Parameters
recipesstring[]required 1 to 20 recipe ids from a search or list result, each optionally followed by ":" and the servings to cook, such as "66d0a1b2c3d4e5f6a7b8c9d0:6".
Returns
items[] object[]
category string
The aisle: bakery, dairy, drinks, frozen, meat, other, pantry, produce, seafood or spices.
display string
The line as a reader would write it.
extras object[]optional
Amounts a recipe asked for in a unit the quantity cannot take, one per unit, such as the 3 tbsp in "1 cup + 3 tbsp". Buy them as well as the quantity.
name string
The ingredient name.
plusMore booleanoptional
Present when a recipe also asked for this without saying how much — oil for frying, a garnish — so the quantity is a minimum rather than the whole of it.
quantity objectoptional
The amount to buy. Absent when no recipe gave one, such as "salt to taste".
recipeIds string[]
The ids of the recipes that asked for it.
The list, grouped by aisle and then by name.
recipes[] object[]
id string
The recipe id.
servings number
The servings the recipe was scaled to.
title string
The recipe title.
The recipes the list was built from, in the order they were asked for, with the servings each was scaled to.
Example response
{
"items": [
{
"category": "dairy",
"display": "250 ml double cream",
"name": "double cream",
"quantity": {
"unit": "ml",
"value": 250
},
"recipeIds": [
"6a9820a88f8122ec891b680b"
]
},
{
"category": "dairy",
"display": "1 cup + 3 tbsp pecorino romano",
"extras": [
{
"unit": "tbsp",
"value": 3
}
],
"name": "pecorino romano",
"quantity": {
"unit": "cup",
"value": 1
},
"recipeIds": [
"6a9820e58f8122ec891b68a4"
]
},
{
"category": "meat",
"display": "1.2 kg chicken thighs",
"name": "chicken thighs",
"quantity": {
"unit": "kg",
"value": 1.2
},
"recipeIds": [
"6a9820a88f8122ec891b680b",
"6a9820e58f8122ec891b68a4"
]
},
{
"category": "produce",
"display": "5 onion",
"name": "onion",
"quantity": {
"value": 5
},
"recipeIds": [
"6a9820a88f8122ec891b680b",
"6a9820e58f8122ec891b68a4"
]
},
{
"category": "spices",
"display": "salt",
"name": "salt",
"recipeIds": [
"6a9820e58f8122ec891b68a4"
]
}
],
"recipes": [
{
"id": "6a9820a88f8122ec891b680b",
"servings": 6,
"title": "Chicken Tikka Masala"
},
{
"id": "6a9820e58f8122ec891b68a4",
"servings": 4,
"title": "Slow-Roasted Cherry Tomatoes"
}
]
}
cook_from_pantry
Cook from your pantry
Find what you can cook from the ingredients you have, best covered first. Each recipe lists the pantry ingredients it uses and the ones you are missing; maxMissing: 0 returns what you can cook right now. Common staples — salt, pepper, water, oil, sugar, flour — are assumed to be on hand: they are left out of the coverage and of missingIngredients and returned in assumedIngredients instead. Send staples: false to count them as ingredients you need.
Parameters
ingredientsstring[]required The ingredients you have. 1 to 20 names or canonical ids from list_ingredients, such as "chicken" or "chicken-thigh".languagestring Only recipes written in this language, as a two-letter ISO 639-1 code such as "en" or "sv".limitinteger How many recipes to return, 1–5. Defaults to 5.maxMissinginteger Only recipes missing at most this many ingredients, 0–20. Left out, any number may be missing.offsetinteger How many recipes to skip, to fetch the next page. The response’s pagination.total says how many match.staplesstring Whether salt, pepper, water, oil, sugar and flour count as already in the kitchen. Defaults to true; false counts them as ingredients you need.
Returns
pagination object
limit integer
How many recipes this response holds. Capped at 100.
offset integer
How many were skipped.
total integer
How many match the filter in total.
Offset pagination.
recipes[] object[]
allergens objectoptional
<allergen> boolean
One key per allergen identifier from GET /vocabularies, such as "milk" or "gluten-cereals": true when the recipe contains it.
disclaimer string
The required informational-use warning.
Whether the recipe contains each EU and US regulated allergen: one true or false for each of the 16 allergen identifiers, keyed by identifier, beside the disclaimer. Informational only; verify product labels before serving someone with an allergy.
author objectoptional
Who wrote the recipe, and a link to them when the site published one.
categories string[]
Normalized category slugs from an open set, such as "pasta" or "soup". The value the `category` filter takes.
courses string[]
Course slugs from the closed list. The value the `course` filter takes.
createdAt string
When the recipe first entered the database. ISO 8601.
cuisines string[]
Cuisine slugs from the closed list. The value the `cuisine` filter takes.
description stringoptional
The recipe’s own summary.
dietary objectoptional
Dietary flags, declared by the site or inferred from the required ingredients. A declared flag wins; a missing flag is unknown, and false is a known no. An inferred `glutenFree` or `dairyFree` can disagree with `allergens` by design: the diet reads the required ingredients, so a dish is gluten-free once the optional pita is left out, while the allergen block counts every line and stays cautious.
equipment string[]optional
Equipment the recipe calls for, as words rather than slugs.
groups string[]
The section headers of the recipe: the distinct `group` values of the ingredients and then the steps, in the order they first appear. Empty when the recipe has no sections.
id string
The recipe id.
ingredients[] object[]
display string
The line to render. Equal to the source line until the structure and the source part company — a converted unit, an amount enrichment filled in.
group stringoptional
The section header the line sat under, such as "For the sauce".
ingredientId stringoptional
The canonical ingredient id, such as "chicken-thigh". Absent until the recipe has been enriched, or when the name could not be resolved. This is the value the `ingredient` filter of GET /recipes takes.
localName stringoptional
The ingredient as this recipe’s own language names it, when that differs from `name`.
localPreparation stringoptional
How the ingredient is prepared, in the recipe’s own words, such as "finhackade" where `preparation` says "finely chopped". Absent on an English recipe, where `preparation` already is the reader’s, and on a line that says nothing of the kind. `display` is written with this one.
name string
The canonical English name.
note stringoptional
Anything the parser understood but could not place, such as "(400 g)". Kept as the source wrote it, in the recipe’s language, and never translated.
optional boolean
Whether the recipe marks this ingredient as optional.
original string
The source line, verbatim. Rewriting a recipe — scaling it, converting its units — leaves this alone.
preparation stringoptional
How the ingredient is prepared, in English, such as "finely chopped". Read `localPreparation` for the words the recipe itself uses.
quantity objectoptional
max numberoptional
The top of a range.
unit stringoptional
One of the units listed by GET /vocabularies.
value number
The amount itself.
The amount. A range such as "2-3 tomatoes" is a value of 2 with a max of 3. A value with no unit is a count of pieces.
size stringoptional
A size qualifier, such as "large".
One ingredient line, parsed. `original` is the line the site published; `display` is the same line written back from these fields, in the recipe’s own language.
instructions[] object[]
duration objectoptional
seconds integer
Seconds.
A length of time. Always seconds, never a formatted string.
equipment string[]optional
Equipment slugs the step calls for.
group stringoptional
The section the step sat under or, where the page named no section, the heading the step carried of its own.
ingredients string[]optional
Canonical ingredient ids the step uses.
step integer
The step number. Steps always run 1, 2, 3… in order.
techniques string[]optional
Technique slugs the step uses, such as "saute".
temperature objectoptional
An oven or pan temperature, with its unit as "C" or "F".
text string
The step text.
One step. The text is authoritative; everything else on a step comes from enrichment and may be absent.
language string
The language the recipe is written in, as a two-letter ISO 639-1 code.
media[] object[]
alt stringoptional
Alternative text.
caption stringoptional
A caption published with the item.
id string
Unique within the recipe.
role string
Where the item sits in the recipe.
step integeroptional
For role "step", the step number the item illustrates.
type string
"image" or "video".
url string
The file itself.
variants object[]optional
The same photo in other sizes or crops. Images only.
Images and videos. An image carries a `role` of hero, gallery, step or thumbnail; a video carries gallery or step. A recipe has at most one hero image.
notes string[]optional
What the writer added beside the method: storage, make-ahead, substitutions. One entry per note, in the order the page wrote them.
nutrition objectoptional
basis object
What the numbers are per. `type` is "serving", "recipe" or "100g"; `servings` is the serving count the site worked the numbers out on, which is not always the serving count the recipe is written for; `description` is the serving size the site named, such as "1 cup".
calories objectoptional
Energy, with its unit.
carbohydrates objectoptional
Carbohydrates.
fat objectoptional
Fat.
fiber objectoptional
Fibre.
micronutrients objectoptional
Anything else the source declared, keyed by nutrient slug.
protein objectoptional
Protein.
saturatedFat objectoptional
Saturated fat.
sodium objectoptional
Sodium.
source string
"provided": the site published these numbers itself, in the structured data the recipe was read from, so they are as current as the last read of that page.
sugar objectoptional
Sugar.
Nutrition as the site published it. `basis` says whether the numbers are per serving, per recipe or per 100 g. The API does not compute nutrition from the ingredients, so a recipe whose site publishes none has no nutrition object at all.
rating objectoptional
The rating the source published, with how many people rated it.
servings objectoptional
How much the recipe makes. "Serves 4-6" is a quantity of 4 with a max of 6; "Makes 24 cookies" is a quantity of 24 with a unit of "cookie".
tags string[]
The source site’s own keywords, cleaned but not mapped to any vocabulary.
techniques string[]optional
Techniques the recipe uses, as words rather than slugs.
text object
ingredients string[]
One line per ingredient.
instructions string[]
One line per step.
The recipe as plain lines: every ingredient’s `display` and every step’s `text`, in order. A convenience for rendering; nothing here is missing from the structured fields.
times object
cook objectoptional
seconds integer
Seconds.
A length of time. Always seconds, never a formatted string.
inactive objectoptional
seconds integer
Seconds.
A length of time. Always seconds, never a formatted string.
prep objectoptional
seconds integer
Seconds.
A length of time. Always seconds, never a formatted string.
total objectoptional
seconds integer
Seconds.
A length of time. Always seconds, never a formatted string.
Preparation, cooking, inactive and total time, each in seconds.
title string
The recipe title.
updatedAt string
When the recipe was last written. ISO 8601.
url string
The page the recipe was read from. One source URL is one recipe.
assumedIngredients string[]
The staples the recipe uses, taken as already in your kitchen. Empty when "staples=false".
coverage number
The share of the recipe's ingredients your pantry covers, from 0 to 1, rounded to two decimals. Staples are in neither half of it.
matchedIngredients string[]
The recipe ingredients your pantry covers.
missingIngredients string[]
The recipe ingredients your pantry does not cover.
The recipes, best covered first.
Example response
{
"pagination": {
"limit": 1,
"offset": 0,
"total": 112
},
"recipes": [
{
"allergens": {
"celery": false,
"crustaceans": false,
"eggs": false,
"fish": false,
"gluten-cereals": false,
"lupin": false,
"milk": true,
"molluscs": false,
"mustard": false,
"nuts-eu": false,
"peanuts": true,
"sesame": false,
"soy": false,
"sulphites": false,
"tree-nuts-us": false,
"wheat": false,
"disclaimer": "Informational only; not medical advice. Verify ingredients and product labels before serving someone with an allergy."
},
"id": "6a9820e58f8122ec891b68a3",
"author": {
"name": "Lindsay Ostrom",
"url": "https://pinchofyum.com/about"
},
"description": "This peanut butter dark chocolate hummus is a sweet alternative to traditional hummus. Perfect served on graham crackers as an afternoon snack!",
"instructions": [
{
"group": "Hummus",
"step": 1,
"text": "Blend everything through milk in a food processor."
},
{
"group": "Hummus",
"step": 2,
"text": "Add flour by the spoonful and blend until desired consistency is reached."
},
{
"step": 3,
"text": "Stir in dark chocolate."
},
{
"step": 4,
"text": "Chill before serving."
}
],
"language": "en",
"media": [
{
"id": "hero",
"role": "hero",
"type": "image",
"url": "https://pinchofyum.com/tachyon/2011/05/Peanut-Butter-Dark-Chocolate-Hummus.jpeg?fit=225%2C225",
"variants": [
{
"url": "https://pinchofyum.com/tachyon/2011/05/Peanut-Butter-Dark-Chocolate-Hummus.jpeg?fit=195%2C195"
},
{
"url": "https://pinchofyum.com/tachyon/2011/05/Peanut-Butter-Dark-Chocolate-Hummus.jpeg?fit=180%2C180"
},
{
"url": "https://pinchofyum.com/tachyon/2011/05/Peanut-Butter-Dark-Chocolate-Hummus.jpeg"
}
]
}
],
"notes": [
"Keeps in an airtight container in the fridge for up to five days.",
"Swap the peanut butter for almond butter to make it peanut free."
],
"nutrition": {
"basis": {
"description": "¼ cup",
"servings": 8,
"type": "serving"
},
"calories": {
"unit": "kcal",
"value": 201
},
"carbohydrates": {
"unit": "g",
"value": 29.4
},
"cholesterol": {
"unit": "mg",
"value": 0.8
},
"fat": {
"unit": "g",
"value": 7.4
},
"fiber": {
"unit": "g",
"value": 3.3
},
"micronutrients": {
"trans-fat": {
"unit": "g",
"value": 0
}
},
"protein": {
"unit": "g",
"value": 5.6
},
"saturatedFat": {
"unit": "g",
"value": 2.5
},
"sodium": {
"unit": "mg",
"value": 76
},
"source": "provided",
"sugar": {
"unit": "g",
"value": 16.9
}
},
"rating": {
"count": 1,
"reviewCount": 1,
"value": 5
},
"servings": {
"max": 8,
"original": "6-8",
"quantity": 6
},
"times": {
"cook": {
"seconds": 600
},
"prep": {
"seconds": 300
},
"total": {
"seconds": 900
}
},
"title": "Peanut Butter Dark Chocolate Hummus",
"categories": [],
"courses": [
"dessert"
],
"createdAt": "2026-09-02T13:13:09.089Z",
"cuisines": [
"american"
],
"groups": [
"Hummus"
],
"ingredients": [
{
"display": "1 can white beans or chickpeas, rinsed",
"name": "white beans or chickpeas",
"optional": false,
"original": "1 can white beans or chickpeas, rinsed",
"preparation": "rinsed",
"quantity": {
"unit": "can",
"value": 1
}
},
{
"display": "¼ cup peanut butter",
"name": "peanut butter",
"optional": false,
"original": "¼ cup peanut butter",
"quantity": {
"unit": "cup",
"value": 0.25
}
},
{
"display": "2 tbsp caramel sauce",
"name": "caramel sauce",
"optional": false,
"original": "2 tbsp caramel sauce",
"quantity": {
"unit": "tbsp",
"value": 2
}
},
{
"display": "2 tbsp maple syrup",
"name": "maple syrup",
"optional": false,
"original": "2 tbsp maple syrup",
"quantity": {
"unit": "tbsp",
"value": 2
}
},
{
"display": "¼ cup brown sugar",
"name": "brown sugar",
"optional": false,
"original": "¼ cup brown sugar",
"quantity": {
"unit": "cup",
"value": 0.25
}
},
{
"display": "pinch of cinnamon",
"name": "pinch of cinnamon",
"optional": false,
"original": "pinch of cinnamon"
},
{
"display": "¼ cup milk",
"name": "milk",
"optional": false,
"original": "¼ cup milk",
"quantity": {
"unit": "cup",
"value": 0.25
}
},
{
"display": "¼ cup flour",
"name": "flour",
"optional": false,
"original": "¼ cup flour",
"quantity": {
"unit": "cup",
"value": 0.25
}
},
{
"display": "chopped dark chocolate",
"name": "chopped dark chocolate",
"optional": false,
"original": "chopped dark chocolate"
}
],
"tags": [
"chocolate hummus",
"peanut butter hummus",
"peanut butter chocolate",
"hummus recipe",
"dessert hummus"
],
"text": {
"ingredients": [
"1 can white beans or chickpeas, rinsed",
"¼ cup peanut butter",
"2 tbsp caramel sauce",
"2 tbsp maple syrup",
"¼ cup brown sugar",
"pinch of cinnamon",
"¼ cup milk",
"¼ cup flour",
"chopped dark chocolate"
],
"instructions": [
"Blend everything through milk in a food processor.",
"Add flour by the spoonful and blend until desired consistency is reached.",
"Stir in dark chocolate.",
"Chill before serving."
]
},
"updatedAt": "2026-09-06T01:11:59.223Z",
"url": "https://pinchofyum.com/pb-dark-chocolate-hummus",
"assumedIngredients": [
"flour"
],
"coverage": 0.75,
"matchedIngredients": [
"white beans or chickpeas",
"peanut butter",
"maple syrup",
"brown sugar",
"pinch of cinnamon",
"milk"
],
"missingIngredients": [
"caramel sauce",
"chopped dark chocolate"
]
}
]
}
find_recipes
Find recipes
List recipes newest first, filtered by any combination of cuisine, course, category, diet, ingredients, equipment, time and nutrition. Use search_recipes instead to search by meaning. Allowed cuisines, courses and diets come from list_vocabularies.
Parameters
categorystring A category slug such as "pasta" or "soup", as a recipe's categories field carries it.coursestring A course from list_vocabularies, such as "main-course".cuisinestring A cuisine from list_vocabularies, such as "italian".dietstring A diet from list_vocabularies, such as "vegetarian". Matches recipes the site declared it for and recipes whose required ingredients suit it; recipes not known to suit it are excluded. An inferred "gluten-free" or "dairy-free" reads the required ingredients only, so it can be stated where the allergen block, which counts optional and serving lines too, stays cautious.equipmentstring[] Equipment every recipe must use, such as "air fryer" or "slow cooker".excludeIngredientsstring[] Leave out recipes using any of these ingredient names or ids. Not an allergen guarantee.ingredientsstring[] Ingredient names or ids every recipe must use.languagestring Only recipes written in this language, as a two-letter ISO 639-1 code such as "en" or "sv".limitinteger How many recipes to return, 1–5. Defaults to 5.maxCaloriesinteger Maximum kilocalories per serving.maxCookMinutesinteger Maximum cooking time in minutes.maxSodiuminteger Maximum milligrams of sodium per serving.maxTotalMinutesinteger Maximum total time in minutes.minFiberinteger Minimum grams of fiber per serving.minProteininteger Minimum grams of protein per serving.nutritionstring[] Nutrition presets: "high-fiber", "high-protein", "low-calorie", "low-sodium".offsetinteger How many recipes to skip, to fetch the next page. The response’s pagination.total says how many match.timestring A total-time preset: "under-15", "under-30" or "weekend".
Returns
pagination object
limit integer
How many recipes this response holds. Capped at 100.
offset integer
How many were skipped.
total integer
How many match the filter in total.
Offset pagination.
recipes[] object[]
allergens objectoptional
<allergen> boolean
One key per allergen identifier from GET /vocabularies, such as "milk" or "gluten-cereals": true when the recipe contains it.
disclaimer string
The required informational-use warning.
Whether the recipe contains each EU and US regulated allergen: one true or false for each of the 16 allergen identifiers, keyed by identifier, beside the disclaimer. Informational only; verify product labels before serving someone with an allergy.
author objectoptional
Who wrote the recipe, and a link to them when the site published one.
categories string[]
Normalized category slugs from an open set, such as "pasta" or "soup". The value the `category` filter takes.
courses string[]
Course slugs from the closed list. The value the `course` filter takes.
createdAt string
When the recipe first entered the database. ISO 8601.
cuisines string[]
Cuisine slugs from the closed list. The value the `cuisine` filter takes.
description stringoptional
The recipe’s own summary.
dietary objectoptional
Dietary flags, declared by the site or inferred from the required ingredients. A declared flag wins; a missing flag is unknown, and false is a known no. An inferred `glutenFree` or `dairyFree` can disagree with `allergens` by design: the diet reads the required ingredients, so a dish is gluten-free once the optional pita is left out, while the allergen block counts every line and stays cautious.
equipment string[]optional
Equipment the recipe calls for, as words rather than slugs.
groups string[]
The section headers of the recipe: the distinct `group` values of the ingredients and then the steps, in the order they first appear. Empty when the recipe has no sections.
id string
The recipe id.
ingredients[] object[]
display string
The line to render. Equal to the source line until the structure and the source part company — a converted unit, an amount enrichment filled in.
group stringoptional
The section header the line sat under, such as "For the sauce".
ingredientId stringoptional
The canonical ingredient id, such as "chicken-thigh". Absent until the recipe has been enriched, or when the name could not be resolved. This is the value the `ingredient` filter of GET /recipes takes.
localName stringoptional
The ingredient as this recipe’s own language names it, when that differs from `name`.
localPreparation stringoptional
How the ingredient is prepared, in the recipe’s own words, such as "finhackade" where `preparation` says "finely chopped". Absent on an English recipe, where `preparation` already is the reader’s, and on a line that says nothing of the kind. `display` is written with this one.
name string
The canonical English name.
note stringoptional
Anything the parser understood but could not place, such as "(400 g)". Kept as the source wrote it, in the recipe’s language, and never translated.
optional boolean
Whether the recipe marks this ingredient as optional.
original string
The source line, verbatim. Rewriting a recipe — scaling it, converting its units — leaves this alone.
preparation stringoptional
How the ingredient is prepared, in English, such as "finely chopped". Read `localPreparation` for the words the recipe itself uses.
quantity objectoptional
max numberoptional
The top of a range.
unit stringoptional
One of the units listed by GET /vocabularies.
value number
The amount itself.
The amount. A range such as "2-3 tomatoes" is a value of 2 with a max of 3. A value with no unit is a count of pieces.
size stringoptional
A size qualifier, such as "large".
One ingredient line, parsed. `original` is the line the site published; `display` is the same line written back from these fields, in the recipe’s own language.
instructions[] object[]
duration objectoptional
seconds integer
Seconds.
A length of time. Always seconds, never a formatted string.
equipment string[]optional
Equipment slugs the step calls for.
group stringoptional
The section the step sat under or, where the page named no section, the heading the step carried of its own.
ingredients string[]optional
Canonical ingredient ids the step uses.
step integer
The step number. Steps always run 1, 2, 3… in order.
techniques string[]optional
Technique slugs the step uses, such as "saute".
temperature objectoptional
An oven or pan temperature, with its unit as "C" or "F".
text string
The step text.
One step. The text is authoritative; everything else on a step comes from enrichment and may be absent.
language string
The language the recipe is written in, as a two-letter ISO 639-1 code.
media[] object[]
alt stringoptional
Alternative text.
caption stringoptional
A caption published with the item.
id string
Unique within the recipe.
role string
Where the item sits in the recipe.
step integeroptional
For role "step", the step number the item illustrates.
type string
"image" or "video".
url string
The file itself.
variants object[]optional
The same photo in other sizes or crops. Images only.
Images and videos. An image carries a `role` of hero, gallery, step or thumbnail; a video carries gallery or step. A recipe has at most one hero image.
notes string[]optional
What the writer added beside the method: storage, make-ahead, substitutions. One entry per note, in the order the page wrote them.
nutrition objectoptional
basis object
What the numbers are per. `type` is "serving", "recipe" or "100g"; `servings` is the serving count the site worked the numbers out on, which is not always the serving count the recipe is written for; `description` is the serving size the site named, such as "1 cup".
calories objectoptional
Energy, with its unit.
carbohydrates objectoptional
Carbohydrates.
fat objectoptional
Fat.
fiber objectoptional
Fibre.
micronutrients objectoptional
Anything else the source declared, keyed by nutrient slug.
protein objectoptional
Protein.
saturatedFat objectoptional
Saturated fat.
sodium objectoptional
Sodium.
source string
"provided": the site published these numbers itself, in the structured data the recipe was read from, so they are as current as the last read of that page.
sugar objectoptional
Sugar.
Nutrition as the site published it. `basis` says whether the numbers are per serving, per recipe or per 100 g. The API does not compute nutrition from the ingredients, so a recipe whose site publishes none has no nutrition object at all.
rating objectoptional
The rating the source published, with how many people rated it.
servings objectoptional
How much the recipe makes. "Serves 4-6" is a quantity of 4 with a max of 6; "Makes 24 cookies" is a quantity of 24 with a unit of "cookie".
tags string[]
The source site’s own keywords, cleaned but not mapped to any vocabulary.
techniques string[]optional
Techniques the recipe uses, as words rather than slugs.
text object
ingredients string[]
One line per ingredient.
instructions string[]
One line per step.
The recipe as plain lines: every ingredient’s `display` and every step’s `text`, in order. A convenience for rendering; nothing here is missing from the structured fields.
times object
cook objectoptional
seconds integer
Seconds.
A length of time. Always seconds, never a formatted string.
inactive objectoptional
seconds integer
Seconds.
A length of time. Always seconds, never a formatted string.
prep objectoptional
seconds integer
Seconds.
A length of time. Always seconds, never a formatted string.
total objectoptional
seconds integer
Seconds.
A length of time. Always seconds, never a formatted string.
Preparation, cooking, inactive and total time, each in seconds.
title string
The recipe title.
updatedAt string
When the recipe was last written. ISO 8601.
url string
The page the recipe was read from. One source URL is one recipe.
The matching recipes.
Example response
{
"pagination": {
"limit": 2,
"offset": 0,
"total": 1930
},
"recipes": [
{
"allergens": {
"celery": false,
"crustaceans": false,
"eggs": false,
"fish": false,
"gluten-cereals": false,
"lupin": false,
"milk": true,
"molluscs": false,
"mustard": false,
"nuts-eu": false,
"peanuts": true,
"sesame": false,
"soy": false,
"sulphites": false,
"tree-nuts-us": false,
"wheat": false,
"disclaimer": "Informational only; not medical advice. Verify ingredients and product labels before serving someone with an allergy."
},
"id": "6a9820e58f8122ec891b68a3",
"author": {
"name": "Lindsay Ostrom",
"url": "https://pinchofyum.com/about"
},
"description": "This peanut butter dark chocolate hummus is a sweet alternative to traditional hummus. Perfect served on graham crackers as an afternoon snack!",
"instructions": [
{
"group": "Hummus",
"step": 1,
"text": "Blend everything through milk in a food processor."
},
{
"group": "Hummus",
"step": 2,
"text": "Add flour by the spoonful and blend until desired consistency is reached."
},
{
"step": 3,
"text": "Stir in dark chocolate."
},
{
"step": 4,
"text": "Chill before serving."
}
],
"language": "en",
"media": [
{
"id": "hero",
"role": "hero",
"type": "image",
"url": "https://pinchofyum.com/tachyon/2011/05/Peanut-Butter-Dark-Chocolate-Hummus.jpeg?fit=225%2C225",
"variants": [
{
"url": "https://pinchofyum.com/tachyon/2011/05/Peanut-Butter-Dark-Chocolate-Hummus.jpeg?fit=195%2C195"
},
{
"url": "https://pinchofyum.com/tachyon/2011/05/Peanut-Butter-Dark-Chocolate-Hummus.jpeg?fit=180%2C180"
},
{
"url": "https://pinchofyum.com/tachyon/2011/05/Peanut-Butter-Dark-Chocolate-Hummus.jpeg"
}
]
}
],
"notes": [
"Keeps in an airtight container in the fridge for up to five days.",
"Swap the peanut butter for almond butter to make it peanut free."
],
"nutrition": {
"basis": {
"description": "¼ cup",
"servings": 8,
"type": "serving"
},
"calories": {
"unit": "kcal",
"value": 201
},
"carbohydrates": {
"unit": "g",
"value": 29.4
},
"cholesterol": {
"unit": "mg",
"value": 0.8
},
"fat": {
"unit": "g",
"value": 7.4
},
"fiber": {
"unit": "g",
"value": 3.3
},
"micronutrients": {
"trans-fat": {
"unit": "g",
"value": 0
}
},
"protein": {
"unit": "g",
"value": 5.6
},
"saturatedFat": {
"unit": "g",
"value": 2.5
},
"sodium": {
"unit": "mg",
"value": 76
},
"source": "provided",
"sugar": {
"unit": "g",
"value": 16.9
}
},
"rating": {
"count": 1,
"reviewCount": 1,
"value": 5
},
"servings": {
"max": 8,
"original": "6-8",
"quantity": 6
},
"times": {
"cook": {
"seconds": 600
},
"prep": {
"seconds": 300
},
"total": {
"seconds": 900
}
},
"title": "Peanut Butter Dark Chocolate Hummus",
"categories": [],
"courses": [
"dessert"
],
"createdAt": "2026-09-02T13:13:09.089Z",
"cuisines": [
"american"
],
"groups": [
"Hummus"
],
"ingredients": [
{
"display": "1 can white beans or chickpeas, rinsed",
"name": "white beans or chickpeas",
"optional": false,
"original": "1 can white beans or chickpeas, rinsed",
"preparation": "rinsed",
"quantity": {
"unit": "can",
"value": 1
}
},
{
"display": "¼ cup peanut butter",
"name": "peanut butter",
"optional": false,
"original": "¼ cup peanut butter",
"quantity": {
"unit": "cup",
"value": 0.25
}
},
{
"display": "2 tbsp caramel sauce",
"name": "caramel sauce",
"optional": false,
"original": "2 tbsp caramel sauce",
"quantity": {
"unit": "tbsp",
"value": 2
}
},
{
"display": "2 tbsp maple syrup",
"name": "maple syrup",
"optional": false,
"original": "2 tbsp maple syrup",
"quantity": {
"unit": "tbsp",
"value": 2
}
},
{
"display": "¼ cup brown sugar",
"name": "brown sugar",
"optional": false,
"original": "¼ cup brown sugar",
"quantity": {
"unit": "cup",
"value": 0.25
}
},
{
"display": "pinch of cinnamon",
"name": "pinch of cinnamon",
"optional": false,
"original": "pinch of cinnamon"
},
{
"display": "¼ cup milk",
"name": "milk",
"optional": false,
"original": "¼ cup milk",
"quantity": {
"unit": "cup",
"value": 0.25
}
},
{
"display": "¼ cup flour",
"name": "flour",
"optional": false,
"original": "¼ cup flour",
"quantity": {
"unit": "cup",
"value": 0.25
}
},
{
"display": "chopped dark chocolate",
"name": "chopped dark chocolate",
"optional": false,
"original": "chopped dark chocolate"
}
],
"tags": [
"chocolate hummus",
"peanut butter hummus",
"peanut butter chocolate",
"hummus recipe",
"dessert hummus"
],
"text": {
"ingredients": [
"1 can white beans or chickpeas, rinsed",
"¼ cup peanut butter",
"2 tbsp caramel sauce",
"2 tbsp maple syrup",
"¼ cup brown sugar",
"pinch of cinnamon",
"¼ cup milk",
"¼ cup flour",
"chopped dark chocolate"
],
"instructions": [
"Blend everything through milk in a food processor.",
"Add flour by the spoonful and blend until desired consistency is reached.",
"Stir in dark chocolate.",
"Chill before serving."
]
},
"updatedAt": "2026-09-06T01:11:59.223Z",
"url": "https://pinchofyum.com/pb-dark-chocolate-hummus"
},
{
"id": "6a9820e58f8122ec891b68a4",
"description": "Slow-roasted cherry tomatoes are intensely sweet and tangy. Add them to salads, pastas, pizza and more.",
"instructions": [
{
"step": 1,
"text": "Preheat the oven to 275°F (135°C) and set an oven rack in the middle position. Line a baking sheet with wide heavy-duty aluminum foil."
},
{
"step": 2,
"text": "Directly on the lined baking sheet, using a rubber spatula, toss the tomatoes with the olive oil, vinegar, sugar, salt, pepper, and garlic. Roast for 2 hours, until the tomatoes are soft and beginning to burst. Serve hot or at room temperature."
}
],
"language": "en",
"media": [
{
"id": "hero",
"role": "hero",
"type": "image",
"url": "https://www.onceuponachef.com/images/2022/07/slow-roasted-cherry-tomatoes.jpg",
"variants": [
{
"url": "https://www.onceuponachef.com/images/2022/07/slow-roasted-cherry-tomatoes-500x500.jpg"
},
{
"url": "https://www.onceuponachef.com/images/2022/07/slow-roasted-cherry-tomatoes-500x375.jpg"
},
{
"url": "https://www.onceuponachef.com/images/2022/07/slow-roasted-cherry-tomatoes-480x270.jpg"
}
]
}
],
"nutrition": {
"basis": {
"type": "serving"
},
"calories": {
"unit": "kcal",
"value": 117
},
"carbohydrates": {
"unit": "g",
"value": 8
},
"fat": {
"unit": "g",
"value": 9
},
"fiber": {
"unit": "g",
"value": 2
},
"protein": {
"unit": "g",
"value": 1
},
"saturatedFat": {
"unit": "g",
"value": 1
},
"sodium": {
"unit": "mg",
"value": 388
},
"source": "provided",
"sugar": {
"unit": "g",
"value": 6
}
},
"rating": {
"count": 25,
"reviewCount": 8,
"value": 4.8
},
"servings": {
"original": "6",
"quantity": 6
},
"times": {
"cook": {
"seconds": 7200
},
"prep": {
"seconds": 600
},
"total": {
"seconds": 7800
}
},
"title": "Roasted Cherry Tomatoes",
"categories": [
"vegetables-and-sides"
],
"courses": [
"appetizer",
"side-dish"
],
"createdAt": "2026-09-02T13:13:09.118Z",
"cuisines": [
"italian"
],
"groups": [],
"ingredients": [
{
"display": "2 lb cherry tomatoes (3 pints)",
"name": "cherry tomatoes",
"note": "3 pints",
"optional": false,
"original": "2 lb cherry tomatoes (3 pints)",
"quantity": {
"unit": "lb",
"value": 2
}
},
{
"display": "¼ cup extra-virgin olive oil",
"name": "extra-virgin olive oil",
"optional": false,
"original": "¼ cup extra-virgin olive oil",
"quantity": {
"unit": "cup",
"value": 0.25
}
},
{
"display": "1½ tbsp balsamic vinegar",
"name": "balsamic vinegar",
"optional": false,
"original": "1½ tbsp balsamic vinegar",
"quantity": {
"unit": "tbsp",
"value": 1.5
}
},
{
"display": "2 tsp sugar",
"name": "sugar",
"optional": false,
"original": "2 tsp sugar",
"quantity": {
"unit": "tsp",
"value": 2
}
},
{
"display": "1 tsp salt",
"name": "salt",
"optional": false,
"original": "1 tsp salt",
"quantity": {
"unit": "tsp",
"value": 1
}
},
{
"display": "½ tsp freshly ground black pepper",
"name": "freshly ground black pepper",
"optional": false,
"original": "½ tsp freshly ground black pepper",
"quantity": {
"unit": "tsp",
"value": 0.5
}
},
{
"display": "2 clove garlic (minced)",
"name": "garlic",
"note": "minced",
"optional": false,
"original": "2 clove garlic (minced)",
"quantity": {
"unit": "clove",
"value": 2
}
}
],
"tags": [
"roasted cherry tomatoes"
],
"text": {
"ingredients": [
"2 lb cherry tomatoes (3 pints)",
"¼ cup extra-virgin olive oil",
"1½ tbsp balsamic vinegar",
"2 tsp sugar",
"1 tsp salt",
"½ tsp freshly ground black pepper",
"2 clove garlic (minced)"
],
"instructions": [
"Preheat the oven to 275°F (135°C) and set an oven rack in the middle position. Line a baking sheet with wide heavy-duty aluminum foil.",
"Directly on the lined baking sheet, using a rubber spatula, toss the tomatoes with the olive oil, vinegar, sugar, salt, pepper, and garlic. Roast for 2 hours, until the tomatoes are soft and beginning to burst. Serve hot or at room temperature."
]
},
"updatedAt": "2026-09-06T01:11:59.224Z",
"url": "https://www.onceuponachef.com/recipes/slow-roasted-cherry-tomatoes.html"
}
]
}
find_substitutions
Find substitutions
What to use instead of an ingredient: how much of each substitute to use for one unit of the original, how to handle it, and what it cannot be used for. Ingredients nothing is known to replace come back in unknown.
Parameters
ingredientsstring[]required The ingredients to replace. 1 to 20 names or canonical ids from list_ingredients, such as "chicken" or "chicken-thigh".
Returns
substitutions[] object[]
ingredient string
The ingredient asked about, normalized.
options object[]
The substitutes, each with `ingredient`, `ratio` (how much to use for one unit of the original), an optional `note` on handling it, and an optional `caution` saying what it cannot be used for.
One entry per ingredient that has substitutions.
unknown string[]
The ingredients nothing is known to substitute for. Nothing is suggested for them.
Example response
{
"substitutions": [
{
"ingredient": "butter",
"options": [
{
"caution": "Not for creaming into a batter or for pastry, where solid fat is what makes the texture.",
"ingredient": "olive oil",
"note": "Use three quarters as much. The result is softer and does not brown the same way.",
"ratio": 0.75
},
{
"ingredient": "margarine",
"note": "Use a block, not a spread: spreads carry more water.",
"ratio": 1
}
]
}
],
"unknown": [
"saffron"
]
}
get_recipe
Get a recipe
Fetch one recipe in full — structured ingredients, numbered steps, times and nutrition — optionally scaled to a number of servings or converted to metric or imperial units.
Parameters
idstringrequired The recipe id, from a search or list result.servingsinteger Rewrite every quantity for this many servings, 1–100.unitsstring Convert the recipe to these units. One of: metric, imperial.
Returns
conversion objectoptional
system string
The system the recipe was rewritten in.
unweighed string[]
Ingredients measured by volume that could not be weighed, because no density is known for them. Their lines keep the unit the source wrote them in.
What the unit conversion did. Present only when `units` was given.
nutritionTotals objectoptional
basisServings number
The serving count perRecipe was multiplied up from: the label's own basis when the recipe declares one — a recipe stored as serving 8 to 10 can carry a label worked out on 10, not the stored 8 — otherwise the serving count the recipe had before any scaling.
perRecipe object
Nutrition for the whole recipe.
perServing object
Nutrition for one serving.
servings number
The serving count both figures were worked out from.
The same nutrition told twice: for one serving, which is what recipes are compared on, and for the whole recipe, which is what the cook is making. Present only when the recipe carries nutrition and says how many servings it makes; figures published per 100 g cannot be split this way and are left out. Scaling with `servings` changes the whole-recipe figures and leaves the per-serving ones alone.
recipe object
allergens objectoptional
<allergen> boolean
One key per allergen identifier from GET /vocabularies, such as "milk" or "gluten-cereals": true when the recipe contains it.
disclaimer string
The required informational-use warning.
Whether the recipe contains each EU and US regulated allergen: one true or false for each of the 16 allergen identifiers, keyed by identifier, beside the disclaimer. Informational only; verify product labels before serving someone with an allergy.
author objectoptional
Who wrote the recipe, and a link to them when the site published one.
categories string[]
Normalized category slugs from an open set, such as "pasta" or "soup". The value the `category` filter takes.
courses string[]
Course slugs from the closed list. The value the `course` filter takes.
createdAt string
When the recipe first entered the database. ISO 8601.
cuisines string[]
Cuisine slugs from the closed list. The value the `cuisine` filter takes.
description stringoptional
The recipe’s own summary.
dietary objectoptional
Dietary flags, declared by the site or inferred from the required ingredients. A declared flag wins; a missing flag is unknown, and false is a known no. An inferred `glutenFree` or `dairyFree` can disagree with `allergens` by design: the diet reads the required ingredients, so a dish is gluten-free once the optional pita is left out, while the allergen block counts every line and stays cautious.
equipment string[]optional
Equipment the recipe calls for, as words rather than slugs.
groups string[]
The section headers of the recipe: the distinct `group` values of the ingredients and then the steps, in the order they first appear. Empty when the recipe has no sections.
id string
The recipe id.
ingredients[] object[]
display string
The line to render. Equal to the source line until the structure and the source part company — a converted unit, an amount enrichment filled in.
group stringoptional
The section header the line sat under, such as "For the sauce".
ingredientId stringoptional
The canonical ingredient id, such as "chicken-thigh". Absent until the recipe has been enriched, or when the name could not be resolved. This is the value the `ingredient` filter of GET /recipes takes.
localName stringoptional
The ingredient as this recipe’s own language names it, when that differs from `name`.
localPreparation stringoptional
How the ingredient is prepared, in the recipe’s own words, such as "finhackade" where `preparation` says "finely chopped". Absent on an English recipe, where `preparation` already is the reader’s, and on a line that says nothing of the kind. `display` is written with this one.
name string
The canonical English name.
note stringoptional
Anything the parser understood but could not place, such as "(400 g)". Kept as the source wrote it, in the recipe’s language, and never translated.
optional boolean
Whether the recipe marks this ingredient as optional.
original string
The source line, verbatim. Rewriting a recipe — scaling it, converting its units — leaves this alone.
preparation stringoptional
How the ingredient is prepared, in English, such as "finely chopped". Read `localPreparation` for the words the recipe itself uses.
quantity objectoptional
max numberoptional
The top of a range.
unit stringoptional
One of the units listed by GET /vocabularies.
value number
The amount itself.
The amount. A range such as "2-3 tomatoes" is a value of 2 with a max of 3. A value with no unit is a count of pieces.
size stringoptional
A size qualifier, such as "large".
One ingredient line, parsed. `original` is the line the site published; `display` is the same line written back from these fields, in the recipe’s own language.
instructions[] object[]
duration objectoptional
seconds integer
Seconds.
A length of time. Always seconds, never a formatted string.
equipment string[]optional
Equipment slugs the step calls for.
group stringoptional
The section the step sat under or, where the page named no section, the heading the step carried of its own.
ingredients string[]optional
Canonical ingredient ids the step uses.
step integer
The step number. Steps always run 1, 2, 3… in order.
techniques string[]optional
Technique slugs the step uses, such as "saute".
temperature objectoptional
An oven or pan temperature, with its unit as "C" or "F".
text string
The step text.
One step. The text is authoritative; everything else on a step comes from enrichment and may be absent.
language string
The language the recipe is written in, as a two-letter ISO 639-1 code.
media[] object[]
alt stringoptional
Alternative text.
caption stringoptional
A caption published with the item.
id string
Unique within the recipe.
role string
Where the item sits in the recipe.
step integeroptional
For role "step", the step number the item illustrates.
type string
"image" or "video".
url string
The file itself.
variants object[]optional
The same photo in other sizes or crops. Images only.
Images and videos. An image carries a `role` of hero, gallery, step or thumbnail; a video carries gallery or step. A recipe has at most one hero image.
notes string[]optional
What the writer added beside the method: storage, make-ahead, substitutions. One entry per note, in the order the page wrote them.
nutrition objectoptional
basis object
What the numbers are per. `type` is "serving", "recipe" or "100g"; `servings` is the serving count the site worked the numbers out on, which is not always the serving count the recipe is written for; `description` is the serving size the site named, such as "1 cup".
calories objectoptional
Energy, with its unit.
carbohydrates objectoptional
Carbohydrates.
fat objectoptional
Fat.
fiber objectoptional
Fibre.
micronutrients objectoptional
Anything else the source declared, keyed by nutrient slug.
protein objectoptional
Protein.
saturatedFat objectoptional
Saturated fat.
sodium objectoptional
Sodium.
source string
"provided": the site published these numbers itself, in the structured data the recipe was read from, so they are as current as the last read of that page.
sugar objectoptional
Sugar.
Nutrition as the site published it. `basis` says whether the numbers are per serving, per recipe or per 100 g. The API does not compute nutrition from the ingredients, so a recipe whose site publishes none has no nutrition object at all.
rating objectoptional
The rating the source published, with how many people rated it.
servings objectoptional
How much the recipe makes. "Serves 4-6" is a quantity of 4 with a max of 6; "Makes 24 cookies" is a quantity of 24 with a unit of "cookie".
tags string[]
The source site’s own keywords, cleaned but not mapped to any vocabulary.
techniques string[]optional
Techniques the recipe uses, as words rather than slugs.
text object
ingredients string[]
One line per ingredient.
instructions string[]
One line per step.
The recipe as plain lines: every ingredient’s `display` and every step’s `text`, in order. A convenience for rendering; nothing here is missing from the structured fields.
times object
cook objectoptional
seconds integer
Seconds.
A length of time. Always seconds, never a formatted string.
inactive objectoptional
seconds integer
Seconds.
A length of time. Always seconds, never a formatted string.
prep objectoptional
seconds integer
Seconds.
A length of time. Always seconds, never a formatted string.
total objectoptional
seconds integer
Seconds.
A length of time. Always seconds, never a formatted string.
Preparation, cooking, inactive and total time, each in seconds.
title string
The recipe title.
updatedAt string
When the recipe was last written. ISO 8601.
url string
The page the recipe was read from. One source URL is one recipe.
The recipe.
Example response
{
"recipe": {
"allergens": {
"celery": false,
"crustaceans": false,
"eggs": false,
"fish": false,
"gluten-cereals": false,
"lupin": false,
"milk": true,
"molluscs": false,
"mustard": false,
"nuts-eu": false,
"peanuts": true,
"sesame": false,
"soy": false,
"sulphites": false,
"tree-nuts-us": false,
"wheat": false,
"disclaimer": "Informational only; not medical advice. Verify ingredients and product labels before serving someone with an allergy."
},
"id": "6a9820e58f8122ec891b68a3",
"author": {
"name": "Lindsay Ostrom",
"url": "https://pinchofyum.com/about"
},
"description": "This peanut butter dark chocolate hummus is a sweet alternative to traditional hummus. Perfect served on graham crackers as an afternoon snack!",
"instructions": [
{
"group": "Hummus",
"step": 1,
"text": "Blend everything through milk in a food processor."
},
{
"group": "Hummus",
"step": 2,
"text": "Add flour by the spoonful and blend until desired consistency is reached."
},
{
"step": 3,
"text": "Stir in dark chocolate."
},
{
"step": 4,
"text": "Chill before serving."
}
],
"language": "en",
"media": [
{
"id": "hero",
"role": "hero",
"type": "image",
"url": "https://pinchofyum.com/tachyon/2011/05/Peanut-Butter-Dark-Chocolate-Hummus.jpeg?fit=225%2C225",
"variants": [
{
"url": "https://pinchofyum.com/tachyon/2011/05/Peanut-Butter-Dark-Chocolate-Hummus.jpeg?fit=195%2C195"
},
{
"url": "https://pinchofyum.com/tachyon/2011/05/Peanut-Butter-Dark-Chocolate-Hummus.jpeg?fit=180%2C180"
},
{
"url": "https://pinchofyum.com/tachyon/2011/05/Peanut-Butter-Dark-Chocolate-Hummus.jpeg"
}
]
}
],
"notes": [
"Keeps in an airtight container in the fridge for up to five days.",
"Swap the peanut butter for almond butter to make it peanut free."
],
"nutrition": {
"basis": {
"description": "¼ cup",
"servings": 8,
"type": "serving"
},
"calories": {
"unit": "kcal",
"value": 201
},
"carbohydrates": {
"unit": "g",
"value": 29.4
},
"cholesterol": {
"unit": "mg",
"value": 0.8
},
"fat": {
"unit": "g",
"value": 7.4
},
"fiber": {
"unit": "g",
"value": 3.3
},
"micronutrients": {
"trans-fat": {
"unit": "g",
"value": 0
}
},
"protein": {
"unit": "g",
"value": 5.6
},
"saturatedFat": {
"unit": "g",
"value": 2.5
},
"sodium": {
"unit": "mg",
"value": 76
},
"source": "provided",
"sugar": {
"unit": "g",
"value": 16.9
}
},
"rating": {
"count": 1,
"reviewCount": 1,
"value": 5
},
"servings": {
"max": 8,
"original": "6-8",
"quantity": 6
},
"times": {
"cook": {
"seconds": 600
},
"prep": {
"seconds": 300
},
"total": {
"seconds": 900
}
},
"title": "Peanut Butter Dark Chocolate Hummus",
"categories": [],
"courses": [
"dessert"
],
"createdAt": "2026-09-02T13:13:09.089Z",
"cuisines": [
"american"
],
"groups": [
"Hummus"
],
"ingredients": [
{
"display": "1 can white beans or chickpeas, rinsed",
"name": "white beans or chickpeas",
"optional": false,
"original": "1 can white beans or chickpeas, rinsed",
"preparation": "rinsed",
"quantity": {
"unit": "can",
"value": 1
}
},
{
"display": "¼ cup peanut butter",
"name": "peanut butter",
"optional": false,
"original": "¼ cup peanut butter",
"quantity": {
"unit": "cup",
"value": 0.25
}
},
{
"display": "2 tbsp caramel sauce",
"name": "caramel sauce",
"optional": false,
"original": "2 tbsp caramel sauce",
"quantity": {
"unit": "tbsp",
"value": 2
}
},
{
"display": "2 tbsp maple syrup",
"name": "maple syrup",
"optional": false,
"original": "2 tbsp maple syrup",
"quantity": {
"unit": "tbsp",
"value": 2
}
},
{
"display": "¼ cup brown sugar",
"name": "brown sugar",
"optional": false,
"original": "¼ cup brown sugar",
"quantity": {
"unit": "cup",
"value": 0.25
}
},
{
"display": "pinch of cinnamon",
"name": "pinch of cinnamon",
"optional": false,
"original": "pinch of cinnamon"
},
{
"display": "¼ cup milk",
"name": "milk",
"optional": false,
"original": "¼ cup milk",
"quantity": {
"unit": "cup",
"value": 0.25
}
},
{
"display": "¼ cup flour",
"name": "flour",
"optional": false,
"original": "¼ cup flour",
"quantity": {
"unit": "cup",
"value": 0.25
}
},
{
"display": "chopped dark chocolate",
"name": "chopped dark chocolate",
"optional": false,
"original": "chopped dark chocolate"
}
],
"tags": [
"chocolate hummus",
"peanut butter hummus",
"peanut butter chocolate",
"hummus recipe",
"dessert hummus"
],
"text": {
"ingredients": [
"1 can white beans or chickpeas, rinsed",
"¼ cup peanut butter",
"2 tbsp caramel sauce",
"2 tbsp maple syrup",
"¼ cup brown sugar",
"pinch of cinnamon",
"¼ cup milk",
"¼ cup flour",
"chopped dark chocolate"
],
"instructions": [
"Blend everything through milk in a food processor.",
"Add flour by the spoonful and blend until desired consistency is reached.",
"Stir in dark chocolate.",
"Chill before serving."
]
},
"updatedAt": "2026-09-06T01:11:59.223Z",
"url": "https://pinchofyum.com/pb-dark-chocolate-hummus"
}
}
list_ingredients
List ingredients
The canonical ingredient vocabulary, most used first. Its ids are what the ingredient filters take, and every spelling seen per language resolves to one of them.
Parameters
limitinteger How many results to return, 1–500. Defaults to 100.
Returns
ingredients[] object[]
aliases object
Every spelling seen, keyed by two-letter language code.
id string
The canonical id, such as "chicken-thigh".
names object
The canonical name, keyed by two-letter language code.
recipeCount integer
How many recipes use this ingredient.
The ingredients, most used first.
Example response
{
"ingredients": [
{
"aliases": {
"en": [
"salt",
"sea salt",
"kosher salt",
"salt and black pepper",
"salt and pepper"
],
"de": [
"Salz",
"Jodsalz",
"Bad Reichenhaller MarkenJodSalz mit Fluorid und Folsäure"
],
"sv": [
"salt",
"salt och svartpeppar",
"salt och peppar",
"flingsalt"
],
"es": [
"sal",
"Sal"
]
},
"id": "salt",
"names": {
"en": "salt"
},
"recipeCount": 783
},
{
"aliases": {
"en": [
"black pepper",
"freshly ground black pepper"
],
"de": [
"Pfeffer",
"schwarzer Pfeffer",
"frisch gemahlener Pfeffer",
"gemahlener Pfeffer",
"grober schwarzer Pfeffer"
],
"sv": [
"peppar",
"svartpeppar",
"nymalen svartpeppar",
"malen vitpeppar",
"svartpepparkorn"
],
"es": [
"pimienta",
"pimienta negra molida",
"Pimienta negra molida"
]
},
"id": "black-pepper",
"names": {
"en": "black pepper"
},
"recipeCount": 451
},
{
"aliases": {
"en": [
"garlic",
"garlic clove",
"garlic cloves"
],
"de": [
"Knoblauchzehe",
"Knoblauchzehen"
],
"sv": [
"vitlöksklyfta",
"vitlöksklyftor",
"vitlök"
],
"es": [
"Dientes de ajo",
"ajo"
]
},
"id": "garlic",
"names": {
"en": "garlic"
},
"recipeCount": 411
}
]
}
list_vocabularies
List vocabularies
The closed lists recipes are classified with: the cuisines, courses and diets find_recipes accepts, EU and US regulated allergen features with their jurisdictions, and the units a quantity can carry.
Parameters
This tool takes no parameters.
Returns
allergens object[]
The 16 EU and US regulated allergen features and their applicable jurisdictions.
courses string[]
The values the `course` filter accepts.
cuisines string[]
The values the `cuisine` filter accepts.
diets string[]
The values the `diet` filter accepts.
units string[]
The units a quantity can carry.
Example response
{
"allergens": [
{
"feature": "celery",
"jurisdictions": [
"eu"
]
},
{
"feature": "crustaceans",
"jurisdictions": [
"eu",
"us"
]
},
{
"feature": "eggs",
"jurisdictions": [
"eu",
"us"
]
},
{
"feature": "fish",
"jurisdictions": [
"eu",
"us"
]
},
{
"feature": "gluten-cereals",
"jurisdictions": [
"eu"
]
},
{
"feature": "lupin",
"jurisdictions": [
"eu"
]
},
{
"feature": "milk",
"jurisdictions": [
"eu",
"us"
]
},
{
"feature": "molluscs",
"jurisdictions": [
"eu"
]
},
{
"feature": "mustard",
"jurisdictions": [
"eu"
]
},
{
"feature": "nuts-eu",
"jurisdictions": [
"eu"
]
},
{
"feature": "peanuts",
"jurisdictions": [
"eu",
"us"
]
},
{
"feature": "sesame",
"jurisdictions": [
"eu",
"us"
]
},
{
"feature": "soy",
"jurisdictions": [
"eu",
"us"
]
},
{
"feature": "sulphites",
"jurisdictions": [
"eu"
]
},
{
"feature": "tree-nuts-us",
"jurisdictions": [
"us"
]
},
{
"feature": "wheat",
"jurisdictions": [
"us"
]
}
],
"courses": [
"appetizer",
"breakfast",
"brunch",
"dessert",
"dinner",
"drink",
"lunch",
"main-course",
"side-dish",
"snack"
],
"cuisines": [
"african",
"american",
"argentinian",
"asian",
"australian",
"austrian",
"belgian",
"brazilian",
"british",
"cajun",
"caribbean",
"chinese",
"cuban",
"danish",
"dutch",
"eastern-european",
"egyptian",
"ethiopian",
"filipino",
"finnish",
"french",
"german",
"greek",
"hungarian",
"indian",
"indonesian",
"iranian",
"irish",
"israeli",
"italian",
"jamaican",
"japanese",
"korean",
"latin-american",
"lebanese",
"malaysian",
"mediterranean",
"mexican",
"middle-eastern",
"moroccan",
"norwegian",
"pakistani",
"peruvian",
"polish",
"portuguese",
"russian",
"scandinavian",
"southern-us",
"spanish",
"swedish",
"swiss",
"tex-mex",
"thai",
"turkish",
"vietnamese"
],
"diets": [
"dairy-free",
"gluten-free",
"pescatarian",
"vegan",
"vegetarian"
],
"units": [
"g",
"kg",
"lb",
"oz",
"cl",
"cup",
"dl",
"fl-oz",
"gallon",
"l",
"ml",
"pint",
"quart",
"tbsp",
"tsp",
"bag",
"bottle",
"box",
"bunch",
"can",
"clove",
"cube",
"dash",
"drop",
"ear",
"handful",
"head",
"jar",
"knob",
"leaf",
"package",
"packet",
"piece",
"pinch",
"portion",
"pot",
"scoop",
"sheet",
"shot",
"slice",
"sprig",
"stalk",
"stick",
"tub",
"cm",
"inch"
]
}
popular_recipes
Popular recipes
The best-loved recipes, ranked by rating and by how many people rated them.
Parameters
languagestring Only recipes written in this language, as a two-letter ISO 639-1 code such as "en" or "sv".limitinteger How many recipes to return, 1–5. Defaults to 5.offsetinteger How many recipes to skip, to fetch the next page. The response’s pagination.total says how many match.
Returns
pagination object
limit integer
How many recipes this response holds. Capped at 100.
offset integer
How many were skipped.
total integer
How many match the filter in total.
Offset pagination.
recipes[] object[]
allergens objectoptional
<allergen> boolean
One key per allergen identifier from GET /vocabularies, such as "milk" or "gluten-cereals": true when the recipe contains it.
disclaimer string
The required informational-use warning.
Whether the recipe contains each EU and US regulated allergen: one true or false for each of the 16 allergen identifiers, keyed by identifier, beside the disclaimer. Informational only; verify product labels before serving someone with an allergy.
author objectoptional
Who wrote the recipe, and a link to them when the site published one.
categories string[]
Normalized category slugs from an open set, such as "pasta" or "soup". The value the `category` filter takes.
courses string[]
Course slugs from the closed list. The value the `course` filter takes.
createdAt string
When the recipe first entered the database. ISO 8601.
cuisines string[]
Cuisine slugs from the closed list. The value the `cuisine` filter takes.
description stringoptional
The recipe’s own summary.
dietary objectoptional
Dietary flags, declared by the site or inferred from the required ingredients. A declared flag wins; a missing flag is unknown, and false is a known no. An inferred `glutenFree` or `dairyFree` can disagree with `allergens` by design: the diet reads the required ingredients, so a dish is gluten-free once the optional pita is left out, while the allergen block counts every line and stays cautious.
equipment string[]optional
Equipment the recipe calls for, as words rather than slugs.
groups string[]
The section headers of the recipe: the distinct `group` values of the ingredients and then the steps, in the order they first appear. Empty when the recipe has no sections.
id string
The recipe id.
ingredients[] object[]
display string
The line to render. Equal to the source line until the structure and the source part company — a converted unit, an amount enrichment filled in.
group stringoptional
The section header the line sat under, such as "For the sauce".
ingredientId stringoptional
The canonical ingredient id, such as "chicken-thigh". Absent until the recipe has been enriched, or when the name could not be resolved. This is the value the `ingredient` filter of GET /recipes takes.
localName stringoptional
The ingredient as this recipe’s own language names it, when that differs from `name`.
localPreparation stringoptional
How the ingredient is prepared, in the recipe’s own words, such as "finhackade" where `preparation` says "finely chopped". Absent on an English recipe, where `preparation` already is the reader’s, and on a line that says nothing of the kind. `display` is written with this one.
name string
The canonical English name.
note stringoptional
Anything the parser understood but could not place, such as "(400 g)". Kept as the source wrote it, in the recipe’s language, and never translated.
optional boolean
Whether the recipe marks this ingredient as optional.
original string
The source line, verbatim. Rewriting a recipe — scaling it, converting its units — leaves this alone.
preparation stringoptional
How the ingredient is prepared, in English, such as "finely chopped". Read `localPreparation` for the words the recipe itself uses.
quantity objectoptional
max numberoptional
The top of a range.
unit stringoptional
One of the units listed by GET /vocabularies.
value number
The amount itself.
The amount. A range such as "2-3 tomatoes" is a value of 2 with a max of 3. A value with no unit is a count of pieces.
size stringoptional
A size qualifier, such as "large".
One ingredient line, parsed. `original` is the line the site published; `display` is the same line written back from these fields, in the recipe’s own language.
instructions[] object[]
duration objectoptional
seconds integer
Seconds.
A length of time. Always seconds, never a formatted string.
equipment string[]optional
Equipment slugs the step calls for.
group stringoptional
The section the step sat under or, where the page named no section, the heading the step carried of its own.
ingredients string[]optional
Canonical ingredient ids the step uses.
step integer
The step number. Steps always run 1, 2, 3… in order.
techniques string[]optional
Technique slugs the step uses, such as "saute".
temperature objectoptional
An oven or pan temperature, with its unit as "C" or "F".
text string
The step text.
One step. The text is authoritative; everything else on a step comes from enrichment and may be absent.
language string
The language the recipe is written in, as a two-letter ISO 639-1 code.
media[] object[]
alt stringoptional
Alternative text.
caption stringoptional
A caption published with the item.
id string
Unique within the recipe.
role string
Where the item sits in the recipe.
step integeroptional
For role "step", the step number the item illustrates.
type string
"image" or "video".
url string
The file itself.
variants object[]optional
The same photo in other sizes or crops. Images only.
Images and videos. An image carries a `role` of hero, gallery, step or thumbnail; a video carries gallery or step. A recipe has at most one hero image.
notes string[]optional
What the writer added beside the method: storage, make-ahead, substitutions. One entry per note, in the order the page wrote them.
nutrition objectoptional
basis object
What the numbers are per. `type` is "serving", "recipe" or "100g"; `servings` is the serving count the site worked the numbers out on, which is not always the serving count the recipe is written for; `description` is the serving size the site named, such as "1 cup".
calories objectoptional
Energy, with its unit.
carbohydrates objectoptional
Carbohydrates.
fat objectoptional
Fat.
fiber objectoptional
Fibre.
micronutrients objectoptional
Anything else the source declared, keyed by nutrient slug.
protein objectoptional
Protein.
saturatedFat objectoptional
Saturated fat.
sodium objectoptional
Sodium.
source string
"provided": the site published these numbers itself, in the structured data the recipe was read from, so they are as current as the last read of that page.
sugar objectoptional
Sugar.
Nutrition as the site published it. `basis` says whether the numbers are per serving, per recipe or per 100 g. The API does not compute nutrition from the ingredients, so a recipe whose site publishes none has no nutrition object at all.
rating objectoptional
The rating the source published, with how many people rated it.
servings objectoptional
How much the recipe makes. "Serves 4-6" is a quantity of 4 with a max of 6; "Makes 24 cookies" is a quantity of 24 with a unit of "cookie".
tags string[]
The source site’s own keywords, cleaned but not mapped to any vocabulary.
techniques string[]optional
Techniques the recipe uses, as words rather than slugs.
text object
ingredients string[]
One line per ingredient.
instructions string[]
One line per step.
The recipe as plain lines: every ingredient’s `display` and every step’s `text`, in order. A convenience for rendering; nothing here is missing from the structured fields.
times object
cook objectoptional
seconds integer
Seconds.
A length of time. Always seconds, never a formatted string.
inactive objectoptional
seconds integer
Seconds.
A length of time. Always seconds, never a formatted string.
prep objectoptional
seconds integer
Seconds.
A length of time. Always seconds, never a formatted string.
total objectoptional
seconds integer
Seconds.
A length of time. Always seconds, never a formatted string.
Preparation, cooking, inactive and total time, each in seconds.
title string
The recipe title.
updatedAt string
When the recipe was last written. ISO 8601.
url string
The page the recipe was read from. One source URL is one recipe.
popularityScore number
How popular this recipe is relative to the others in this response. Higher comes first.
The recipes, most popular first.
Example response
{
"pagination": {
"limit": 1,
"offset": 0,
"total": 1848
},
"recipes": [
{
"id": "6a9820a88f8122ec891b680b",
"description": "No canning, no fuss—just crisp, tangy pickles you’ll want to eat with everything!",
"instructions": [
{
"step": 1,
"text": "Combine the vinegar, salt and sugar in a small non-reactive saucepan (such as stainless steel, glass, ceramic or teflon) over high heat. Whisk until the salt and sugar are dissolved. Transfer the liquid into a bowl and whisk in the cold water. Refrigerate brine until ready to use."
},
{
"step": 2,
"text": "Stuff the cucumbers into two clean 1 qt (1L) jars. Add the coriander seeds, garlic cloves, mustard seeds, red pepper flakes, dill sprigs, and chilled brine into jars, dividing evenly. If necessary, add a bit of cold water to the jars until the brine covers the cucumbers. Cover and refrigerate about 24 hours, then serve. The pickles will keep in the refrigerator for up to one month."
}
],
"language": "en",
"media": [
{
"id": "hero",
"role": "hero",
"type": "image",
"url": "https://www.onceuponachef.com/images/2012/04/pickles.jpg",
"variants": [
{
"url": "https://www.onceuponachef.com/images/2012/04/pickles-500x500.jpg"
},
{
"url": "https://www.onceuponachef.com/images/2012/04/pickles-500x375.jpg"
},
{
"url": "https://www.onceuponachef.com/images/2012/04/pickles-480x270.jpg"
}
]
}
],
"rating": {
"count": 517,
"reviewCount": 11,
"value": 4.93
},
"servings": {
"original": "2 (1-qt) jars (about 24 spears)",
"quantity": 2
},
"times": {
"cook": {
"seconds": 300
},
"prep": {
"seconds": 900
},
"total": {
"seconds": 1200
}
},
"title": "Quick & Easy Refrigerator Pickles",
"categories": [],
"courses": [
"snack"
],
"createdAt": "2026-09-02T13:12:08.379Z",
"cuisines": [
"american"
],
"groups": [],
"ingredients": [
{
"display": "1¼ cup distilled white vinegar (5% acidity)",
"name": "distilled white vinegar",
"note": "5% acidity",
"optional": false,
"original": "1¼ cup distilled white vinegar (5% acidity)",
"quantity": {
"unit": "cup",
"value": 1.25
}
},
{
"display": "3 tbsp kosher salt",
"name": "kosher salt",
"optional": false,
"original": "3 tbsp kosher salt",
"quantity": {
"unit": "tbsp",
"value": 3
}
},
{
"display": "2 tbsp sugar",
"name": "sugar",
"optional": false,
"original": "2 tbsp sugar",
"quantity": {
"unit": "tbsp",
"value": 2
}
},
{
"display": "2 cup cold water",
"name": "cold water",
"optional": false,
"original": "2 cup cold water",
"quantity": {
"unit": "cup",
"value": 2
}
},
{
"display": "1¾-2 lb Kirby cucumbers, cut into halves or spears (about 6)",
"name": "Kirby cucumbers",
"note": "about 6",
"optional": false,
"original": "1¾-2 lb Kirby cucumbers, cut into halves or spears (about 6)",
"preparation": "cut into halves or spears",
"quantity": {
"max": 2,
"unit": "lb",
"value": 1.75
}
},
{
"display": "2 tbsp coriander seeds",
"name": "coriander seeds",
"optional": false,
"original": "2 tbsp coriander seeds",
"quantity": {
"unit": "tbsp",
"value": 2
}
},
{
"display": "6 large garlic cloves (peeled and halved)",
"name": "garlic cloves",
"note": "peeled and halved",
"optional": false,
"original": "6 large garlic cloves (peeled and halved)",
"quantity": {
"value": 6
},
"size": "large"
},
{
"display": "1 tsp mustard seeds",
"name": "mustard seeds",
"optional": false,
"original": "1 tsp mustard seeds",
"quantity": {
"unit": "tsp",
"value": 1
}
},
{
"display": "¼ tsp crushed red pepper flakes",
"name": "crushed red pepper flakes",
"optional": false,
"original": "¼ tsp crushed red pepper flakes",
"quantity": {
"unit": "tsp",
"value": 0.25
}
},
{
"display": "16 dill sprigs",
"name": "dill sprigs",
"optional": false,
"original": "16 dill sprigs",
"quantity": {
"value": 16
}
}
],
"tags": [
"pickles"
],
"text": {
"ingredients": [
"1¼ cup distilled white vinegar (5% acidity)",
"3 tbsp kosher salt",
"2 tbsp sugar",
"2 cup cold water",
"1¾-2 lb Kirby cucumbers, cut into halves or spears (about 6)",
"2 tbsp coriander seeds",
"6 large garlic cloves (peeled and halved)",
"1 tsp mustard seeds",
"¼ tsp crushed red pepper flakes",
"16 dill sprigs"
],
"instructions": [
"Combine the vinegar, salt and sugar in a small non-reactive saucepan (such as stainless steel, glass, ceramic or teflon) over high heat. Whisk until the salt and sugar are dissolved. Transfer the liquid into a bowl and whisk in the cold water. Refrigerate brine until ready to use.",
"Stuff the cucumbers into two clean 1 qt (1L) jars. Add the coriander seeds, garlic cloves, mustard seeds, red pepper flakes, dill sprigs, and chilled brine into jars, dividing evenly. If necessary, add a bit of cold water to the jars until the brine covers the cucumbers. Cover and refrigerate about 24 hours, then serve. The pickles will keep in the refrigerator for up to one month."
]
},
"updatedAt": "2026-09-06T01:11:59.030Z",
"url": "https://www.onceuponachef.com/recipes/quick-and-easy-dill-pickles.html",
"popularityScore": 4.89536312849162
}
]
}
search_recipes
Search recipes
Search recipes by meaning as well as wording across names, ingredients and descriptions, so "creamy pasta" also finds carbonara. Best matches first.
Parameters
fieldsstring[] Only return these recipe fields, such as "title", "url" and "times", to keep results small. id and score are always included.languagestring Only recipes written in this language, as a two-letter ISO 639-1 code such as "en" or "sv".limitinteger How many recipes to return, 1–5. Defaults to 5.querystringrequired What to search for.withoutstring[] Leave out recipes that contain any of these allergen features from list_vocabularies, such as "milk" or "peanuts". Informational, not a medical guarantee.
Returns
results[] object[]
allergens objectoptional
<allergen> boolean
One key per allergen identifier from GET /vocabularies, such as "milk" or "gluten-cereals": true when the recipe contains it.
disclaimer string
The required informational-use warning.
Whether the recipe contains each EU and US regulated allergen: one true or false for each of the 16 allergen identifiers, keyed by identifier, beside the disclaimer. Informational only; verify product labels before serving someone with an allergy.
author objectoptional
Who wrote the recipe, and a link to them when the site published one.
categories string[]
Normalized category slugs from an open set, such as "pasta" or "soup". The value the `category` filter takes.
courses string[]
Course slugs from the closed list. The value the `course` filter takes.
createdAt string
When the recipe first entered the database. ISO 8601.
cuisines string[]
Cuisine slugs from the closed list. The value the `cuisine` filter takes.
description stringoptional
The recipe’s own summary.
dietary objectoptional
Dietary flags, declared by the site or inferred from the required ingredients. A declared flag wins; a missing flag is unknown, and false is a known no. An inferred `glutenFree` or `dairyFree` can disagree with `allergens` by design: the diet reads the required ingredients, so a dish is gluten-free once the optional pita is left out, while the allergen block counts every line and stays cautious.
equipment string[]optional
Equipment the recipe calls for, as words rather than slugs.
groups string[]
The section headers of the recipe: the distinct `group` values of the ingredients and then the steps, in the order they first appear. Empty when the recipe has no sections.
id string
The recipe id.
ingredients[] object[]
display string
The line to render. Equal to the source line until the structure and the source part company — a converted unit, an amount enrichment filled in.
group stringoptional
The section header the line sat under, such as "For the sauce".
ingredientId stringoptional
The canonical ingredient id, such as "chicken-thigh". Absent until the recipe has been enriched, or when the name could not be resolved. This is the value the `ingredient` filter of GET /recipes takes.
localName stringoptional
The ingredient as this recipe’s own language names it, when that differs from `name`.
localPreparation stringoptional
How the ingredient is prepared, in the recipe’s own words, such as "finhackade" where `preparation` says "finely chopped". Absent on an English recipe, where `preparation` already is the reader’s, and on a line that says nothing of the kind. `display` is written with this one.
name string
The canonical English name.
note stringoptional
Anything the parser understood but could not place, such as "(400 g)". Kept as the source wrote it, in the recipe’s language, and never translated.
optional boolean
Whether the recipe marks this ingredient as optional.
original string
The source line, verbatim. Rewriting a recipe — scaling it, converting its units — leaves this alone.
preparation stringoptional
How the ingredient is prepared, in English, such as "finely chopped". Read `localPreparation` for the words the recipe itself uses.
quantity objectoptional
max numberoptional
The top of a range.
unit stringoptional
One of the units listed by GET /vocabularies.
value number
The amount itself.
The amount. A range such as "2-3 tomatoes" is a value of 2 with a max of 3. A value with no unit is a count of pieces.
size stringoptional
A size qualifier, such as "large".
One ingredient line, parsed. `original` is the line the site published; `display` is the same line written back from these fields, in the recipe’s own language.
instructions[] object[]
duration objectoptional
seconds integer
Seconds.
A length of time. Always seconds, never a formatted string.
equipment string[]optional
Equipment slugs the step calls for.
group stringoptional
The section the step sat under or, where the page named no section, the heading the step carried of its own.
ingredients string[]optional
Canonical ingredient ids the step uses.
step integer
The step number. Steps always run 1, 2, 3… in order.
techniques string[]optional
Technique slugs the step uses, such as "saute".
temperature objectoptional
An oven or pan temperature, with its unit as "C" or "F".
text string
The step text.
One step. The text is authoritative; everything else on a step comes from enrichment and may be absent.
language string
The language the recipe is written in, as a two-letter ISO 639-1 code.
media[] object[]
alt stringoptional
Alternative text.
caption stringoptional
A caption published with the item.
id string
Unique within the recipe.
role string
Where the item sits in the recipe.
step integeroptional
For role "step", the step number the item illustrates.
type string
"image" or "video".
url string
The file itself.
variants object[]optional
The same photo in other sizes or crops. Images only.
Images and videos. An image carries a `role` of hero, gallery, step or thumbnail; a video carries gallery or step. A recipe has at most one hero image.
notes string[]optional
What the writer added beside the method: storage, make-ahead, substitutions. One entry per note, in the order the page wrote them.
nutrition objectoptional
basis object
What the numbers are per. `type` is "serving", "recipe" or "100g"; `servings` is the serving count the site worked the numbers out on, which is not always the serving count the recipe is written for; `description` is the serving size the site named, such as "1 cup".
calories objectoptional
Energy, with its unit.
carbohydrates objectoptional
Carbohydrates.
fat objectoptional
Fat.
fiber objectoptional
Fibre.
micronutrients objectoptional
Anything else the source declared, keyed by nutrient slug.
protein objectoptional
Protein.
saturatedFat objectoptional
Saturated fat.
sodium objectoptional
Sodium.
source string
"provided": the site published these numbers itself, in the structured data the recipe was read from, so they are as current as the last read of that page.
sugar objectoptional
Sugar.
Nutrition as the site published it. `basis` says whether the numbers are per serving, per recipe or per 100 g. The API does not compute nutrition from the ingredients, so a recipe whose site publishes none has no nutrition object at all.
rating objectoptional
The rating the source published, with how many people rated it.
servings objectoptional
How much the recipe makes. "Serves 4-6" is a quantity of 4 with a max of 6; "Makes 24 cookies" is a quantity of 24 with a unit of "cookie".
tags string[]
The source site’s own keywords, cleaned but not mapped to any vocabulary.
techniques string[]optional
Techniques the recipe uses, as words rather than slugs.
text object
ingredients string[]
One line per ingredient.
instructions string[]
One line per step.
The recipe as plain lines: every ingredient’s `display` and every step’s `text`, in order. A convenience for rendering; nothing here is missing from the structured fields.
times object
cook objectoptional
seconds integer
Seconds.
A length of time. Always seconds, never a formatted string.
inactive objectoptional
seconds integer
Seconds.
A length of time. Always seconds, never a formatted string.
prep objectoptional
seconds integer
Seconds.
A length of time. Always seconds, never a formatted string.
total objectoptional
seconds integer
Seconds.
A length of time. Always seconds, never a formatted string.
Preparation, cooking, inactive and total time, each in seconds.
title string
The recipe title.
updatedAt string
When the recipe was last written. ISO 8601.
url string
The page the recipe was read from. One source URL is one recipe.
score number
A rank fusion of the meaning and the wording legs of the search, plus a bonus for a title that contains the query. Higher comes first. It is a rank, not a confidence: scores are comparable only within one response.
The matching recipes, best first. When `fields` is set, only the requested fields plus `id` and `score` are present.
Example response
{
"results": [
{
"id": "6a980d75ea7517554c2894b1",
"allergens": {
"celery": false,
"crustaceans": false,
"eggs": false,
"fish": false,
"gluten-cereals": false,
"lupin": false,
"milk": true,
"molluscs": false,
"mustard": false,
"nuts-eu": false,
"peanuts": true,
"sesame": false,
"soy": false,
"sulphites": false,
"tree-nuts-us": false,
"wheat": false,
"disclaimer": "Informational only; not medical advice. Verify ingredients and product labels before serving someone with an allergy."
},
"createdAt": "2026-09-02T11:50:13.886Z",
"dietary": {
"glutenFree": true,
"vegetarian": true
},
"instructions": [
{
"equipment": [
"oven"
],
"step": 1,
"temperature": {
"unit": "F",
"value": 325
},
"text": "Preheat oven to 325°."
},
{
"ingredients": [
"roma-tomato"
],
"step": 2,
"techniques": [
"slicing"
],
"text": "Slice tomatoes in half."
},
{
"ingredients": [
"salt",
"basil",
"oregano",
"thyme"
],
"step": 3,
"techniques": [
"seasoning"
],
"text": "Season with salt, basil, oregano and thyme."
},
{
"equipment": [
"baking-sheet"
],
"ingredients": [
"olive-oil",
"roma-tomato"
],
"step": 4,
"techniques": [
"spraying"
],
"text": "Spray a cookie sheet with olive oil spray and place tomatoes cut side up."
},
{
"duration": {
"seconds": 7200
},
"equipment": [
"oven"
],
"ingredients": [
"roma-tomato"
],
"step": 5,
"techniques": [
"baking"
],
"text": "Bake 2 hrs until skin gets wrinkled and crusty on the bottom and moist in the center."
},
{
"equipment": [
"food-processor"
],
"ingredients": [
"roma-tomato"
],
"step": 6,
"techniques": [
"pureeing"
],
"text": "Puree the tomatoes in a food processor."
},
{
"step": 7,
"text": "If it is too thick, you can thin with pasta water."
},
{
"ingredients": [
"roma-tomato"
],
"step": 8,
"text": "Serve over your favorite high fiber pasta and grated cheese."
}
],
"language": "en",
"media": [
{
"id": "hero",
"role": "hero",
"type": "image",
"url": "https://www.skinnytaste.com/wp-content/uploads/2008/08/roasted-tomatoe-sauce.jpg",
"variants": [
{
"url": "https://www.skinnytaste.com/wp-content/uploads/2008/08/roasted-tomatoe-sauce-425x270.jpg"
}
]
}
],
"nutrition": {
"basis": {
"type": "serving"
},
"calories": {
"unit": "kcal",
"value": 78.1
},
"carbohydrates": {
"unit": "g",
"value": 17.3
},
"fat": {
"unit": "g",
"value": 1.2
},
"fiber": {
"unit": "g",
"value": 4.1
},
"protein": {
"unit": "g",
"value": 3.2
},
"source": "provided"
},
"rating": {
"count": 1,
"reviewCount": 1,
"value": 5
},
"servings": {
"original": "4 servings",
"quantity": 4
},
"times": {},
"title": "Candied Tomato Sauce",
"updatedAt": "2026-09-06T01:39:14.527Z",
"categories": [],
"courses": [],
"cuisines": [
"italian"
],
"groups": [],
"ingredients": [
{
"display": "12 ripe Roma tomatoes",
"localName": "Roma tomatoes",
"ingredientId": "roma-tomato",
"name": "Roma tomato",
"optional": false,
"original": "12 ripe Roma tomatoes",
"quantity": {
"value": 12
},
"size": "ripe"
},
{
"display": "salt",
"localName": "salt",
"ingredientId": "salt",
"name": "salt",
"note": "to taste",
"optional": false,
"original": "salt to taste"
},
{
"display": "1 tsp thyme",
"localName": "thyme",
"ingredientId": "thyme",
"name": "thyme",
"optional": false,
"original": "1 tsp thyme",
"quantity": {
"unit": "tsp",
"value": 1
}
},
{
"display": "1 tsp oregano",
"localName": "oregano",
"ingredientId": "oregano",
"name": "oregano",
"optional": false,
"original": "1 tsp oregano",
"quantity": {
"unit": "tsp",
"value": 1
}
},
{
"display": "olive oil spray",
"localName": "olive oil",
"ingredientId": "olive-oil",
"name": "olive oil",
"optional": false,
"original": "olive oil spray",
"preparation": "spray"
},
{
"display": "2 tbsp basil, chopped",
"localName": "basil",
"ingredientId": "basil",
"name": "basil",
"optional": false,
"original": "2 tbsp basil, chopped",
"preparation": "chopped",
"quantity": {
"unit": "tbsp",
"value": 2
}
}
],
"tags": [
"freezer meals",
"gluten free",
"vegetarian meals"
],
"text": {
"ingredients": [
"12 ripe Roma tomatoes",
"salt",
"1 tsp thyme",
"1 tsp oregano",
"olive oil spray",
"2 tbsp basil, chopped"
],
"instructions": [
"Preheat oven to 325°.",
"Slice tomatoes in half.",
"Season with salt, basil, oregano and thyme.",
"Spray a cookie sheet with olive oil spray and place tomatoes cut side up.",
"Bake 2 hrs until skin gets wrinkled and crusty on the bottom and moist in the center.",
"Puree the tomatoes in a food processor.",
"If it is too thick, you can thin with pasta water.",
"Serve over your favorite high fiber pasta and grated cheese."
]
},
"url": "https://www.skinnytaste.com/candied-tomato-sauce-0-ww-pts/",
"equipment": [
"baking sheet",
"food processor",
"oven"
],
"techniques": [
"baking",
"pureeing",
"seasoning",
"slicing",
"spraying"
],
"score": 0.0333
}
]
}