Skip to content

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

The server speaks streamable HTTP at one URL:

https://api.tinyplates.dev/mcp

Pick your agent:

  1. Add the server for every project:

    claude mcp add --transport http --scope user \
  tinyplates https://api.tinyplates.dev/mcp

  2. 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

Signing in

The first time the agent connects, it opens Tiny Plates in your browser. Sign in — or create an account — and allow the agent access. It keeps the sign-in and renews it on its own; you are asked again only if you remove the server.

Every tool call is one API request. It counts toward your usage alongside your API keys, shows up in your usage on the dashboard, and is subject to the same rate limits.

With an API key

Where a browser sign-in is not possible, such as a CI job or a shared machine, send an API key as a bearer token instead. Each agent above shows how under Use an API key instead. Keys start with rd_ and are created on your dashboard.

Pagination

A whole recipe is thousands of characters, and an agent reads every result into its context. So the tools that return recipes answer at most 5 at a time, however large a limit the agent sends:

A list response carries pagination.total, the number of recipes that match; the agent asks for the next page by passing offset. search_recipes ranks by relevance and has no offset: a sharper query is the way to more results.

Errors

A call the API refuses — a parameter out of range, a recipe id that does not exist, an allowance spent — comes back as a tool error carrying the API’s own message, which says what to change. The agent reads it and tries again. Each tool below links to its endpoint, where the errors are listed; the errors page explains them all.

A missing or expired sign-in is answered before any tool runs, with a 401 that tells the agent to sign in again.

Tools

Every tool reads; none of them changes anything. Each one calls one endpoint of the API and answers with that endpoint’s response, so the REST reference and this one describe the same data.

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

The JSON the Build a shopping list endpoint answers with.

items[]object[]
categorystring

The aisle: bakery, dairy, drinks, frozen, meat, other, pantry, produce, seafood or spices.

displaystring

The line as a reader would write it.

extrasobject[]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.

namestring

The ingredient name.

plusMorebooleanoptional

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.

quantityobjectoptional

The amount to buy. Absent when no recipe gave one, such as "salt to taste".

recipeIdsstring[]

The ids of the recipes that asked for it.

The list, grouped by aisle and then by name.

recipes[]object[]
idstring

The recipe id.

servingsnumber

The servings the recipe was scaled to.

titlestring

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

The JSON the Cook from your pantry endpoint answers with, 5 recipes at a time.

paginationobject
limitinteger

How many recipes this response holds. Capped at 100.

offsetinteger

How many were skipped.

totalinteger

How many match the filter in total.

Offset pagination.

recipes[]object[]
allergensobjectoptional
<allergen>boolean

One key per allergen identifier from GET /vocabularies, such as "milk" or "gluten-cereals": true when the recipe contains it.

disclaimerstring

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.

authorobjectoptional

Who wrote the recipe, and a link to them when the site published one.

categoriesstring[]

Normalized category slugs from an open set, such as "pasta" or "soup". The value the `category` filter takes.

coursesstring[]

Course slugs from the closed list. The value the `course` filter takes.

createdAtstring

When the recipe first entered the database. ISO 8601.

cuisinesstring[]

Cuisine slugs from the closed list. The value the `cuisine` filter takes.

descriptionstringoptional

The recipe’s own summary.

dietaryobjectoptional

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.

equipmentstring[]optional

Equipment the recipe calls for, as words rather than slugs.

groupsstring[]

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.

idstring

The recipe id.

ingredients[]object[]
displaystring

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.

groupstringoptional

The section header the line sat under, such as "For the sauce".

ingredientIdstringoptional

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.

localNamestringoptional

The ingredient as this recipe’s own language names it, when that differs from `name`.

localPreparationstringoptional

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.

namestring

The canonical English name.

notestringoptional

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.

optionalboolean

Whether the recipe marks this ingredient as optional.

originalstring

The source line, verbatim. Rewriting a recipe — scaling it, converting its units — leaves this alone.

preparationstringoptional

How the ingredient is prepared, in English, such as "finely chopped". Read `localPreparation` for the words the recipe itself uses.

quantityobjectoptional
maxnumberoptional

The top of a range.

unitstringoptional

One of the units listed by GET /vocabularies.

valuenumber

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.

sizestringoptional

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[]
durationobjectoptional
secondsinteger

Seconds.

A length of time. Always seconds, never a formatted string.

equipmentstring[]optional

Equipment slugs the step calls for.

groupstringoptional

The section the step sat under or, where the page named no section, the heading the step carried of its own.

ingredientsstring[]optional

Canonical ingredient ids the step uses.

stepinteger

The step number. Steps always run 1, 2, 3… in order.

techniquesstring[]optional

Technique slugs the step uses, such as "saute".

temperatureobjectoptional

An oven or pan temperature, with its unit as "C" or "F".

textstring

The step text.

One step. The text is authoritative; everything else on a step comes from enrichment and may be absent.

languagestring

The language the recipe is written in, as a two-letter ISO 639-1 code.

media[]object[]
altstringoptional

Alternative text.

captionstringoptional

A caption published with the item.

idstring

Unique within the recipe.

rolestring

Where the item sits in the recipe.

stepintegeroptional

For role "step", the step number the item illustrates.

typestring

"image" or "video".

urlstring

The file itself.

variantsobject[]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.

notesstring[]optional

What the writer added beside the method: storage, make-ahead, substitutions. One entry per note, in the order the page wrote them.

nutritionobjectoptional
basisobject

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".

caloriesobjectoptional

Energy, with its unit.

carbohydratesobjectoptional

Carbohydrates.

fatobjectoptional

Fat.

fiberobjectoptional

Fibre.

micronutrientsobjectoptional

Anything else the source declared, keyed by nutrient slug.

proteinobjectoptional

Protein.

saturatedFatobjectoptional

Saturated fat.

sodiumobjectoptional

Sodium.

sourcestring

"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.

sugarobjectoptional

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.

ratingobjectoptional

The rating the source published, with how many people rated it.

servingsobjectoptional

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".

tagsstring[]

The source site’s own keywords, cleaned but not mapped to any vocabulary.

techniquesstring[]optional

Techniques the recipe uses, as words rather than slugs.

textobject
ingredientsstring[]

One line per ingredient.

instructionsstring[]

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.

timesobject
cookobjectoptional
secondsinteger

Seconds.

A length of time. Always seconds, never a formatted string.

inactiveobjectoptional
secondsinteger

Seconds.

A length of time. Always seconds, never a formatted string.

prepobjectoptional
secondsinteger

Seconds.

A length of time. Always seconds, never a formatted string.

totalobjectoptional
secondsinteger

Seconds.

A length of time. Always seconds, never a formatted string.

Preparation, cooking, inactive and total time, each in seconds.

titlestring

The recipe title.

updatedAtstring

When the recipe was last written. ISO 8601.

urlstring

The page the recipe was read from. One source URL is one recipe.

assumedIngredientsstring[]

The staples the recipe uses, taken as already in your kitchen. Empty when "staples=false".

coveragenumber

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.

matchedIngredientsstring[]

The recipe ingredients your pantry covers.

missingIngredientsstring[]

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

The JSON the List recipes endpoint answers with, 5 recipes at a time.

paginationobject
limitinteger

How many recipes this response holds. Capped at 100.

offsetinteger

How many were skipped.

totalinteger

How many match the filter in total.

Offset pagination.

recipes[]object[]
allergensobjectoptional
<allergen>boolean

One key per allergen identifier from GET /vocabularies, such as "milk" or "gluten-cereals": true when the recipe contains it.

disclaimerstring

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.

authorobjectoptional

Who wrote the recipe, and a link to them when the site published one.

categoriesstring[]

Normalized category slugs from an open set, such as "pasta" or "soup". The value the `category` filter takes.

coursesstring[]

Course slugs from the closed list. The value the `course` filter takes.

createdAtstring

When the recipe first entered the database. ISO 8601.

cuisinesstring[]

Cuisine slugs from the closed list. The value the `cuisine` filter takes.

descriptionstringoptional

The recipe’s own summary.

dietaryobjectoptional

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.

equipmentstring[]optional

Equipment the recipe calls for, as words rather than slugs.

groupsstring[]

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.

idstring

The recipe id.

ingredients[]object[]
displaystring

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.

groupstringoptional

The section header the line sat under, such as "For the sauce".

ingredientIdstringoptional

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.

localNamestringoptional

The ingredient as this recipe’s own language names it, when that differs from `name`.

localPreparationstringoptional

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.

namestring

The canonical English name.

notestringoptional

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.

optionalboolean

Whether the recipe marks this ingredient as optional.

originalstring

The source line, verbatim. Rewriting a recipe — scaling it, converting its units — leaves this alone.

preparationstringoptional

How the ingredient is prepared, in English, such as "finely chopped". Read `localPreparation` for the words the recipe itself uses.

quantityobjectoptional
maxnumberoptional

The top of a range.

unitstringoptional

One of the units listed by GET /vocabularies.

valuenumber

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.

sizestringoptional

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[]
durationobjectoptional
secondsinteger

Seconds.

A length of time. Always seconds, never a formatted string.

equipmentstring[]optional

Equipment slugs the step calls for.

groupstringoptional

The section the step sat under or, where the page named no section, the heading the step carried of its own.

ingredientsstring[]optional

Canonical ingredient ids the step uses.

stepinteger

The step number. Steps always run 1, 2, 3… in order.

techniquesstring[]optional

Technique slugs the step uses, such as "saute".

temperatureobjectoptional

An oven or pan temperature, with its unit as "C" or "F".

textstring

The step text.

One step. The text is authoritative; everything else on a step comes from enrichment and may be absent.

languagestring

The language the recipe is written in, as a two-letter ISO 639-1 code.

media[]object[]
altstringoptional

Alternative text.

captionstringoptional

A caption published with the item.

idstring

Unique within the recipe.

rolestring

Where the item sits in the recipe.

stepintegeroptional

For role "step", the step number the item illustrates.

typestring

"image" or "video".

urlstring

The file itself.

variantsobject[]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.

notesstring[]optional

What the writer added beside the method: storage, make-ahead, substitutions. One entry per note, in the order the page wrote them.

nutritionobjectoptional
basisobject

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".

caloriesobjectoptional

Energy, with its unit.

carbohydratesobjectoptional

Carbohydrates.

fatobjectoptional

Fat.

fiberobjectoptional

Fibre.

micronutrientsobjectoptional

Anything else the source declared, keyed by nutrient slug.

proteinobjectoptional

Protein.

saturatedFatobjectoptional

Saturated fat.

sodiumobjectoptional

Sodium.

sourcestring

"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.

sugarobjectoptional

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.

ratingobjectoptional

The rating the source published, with how many people rated it.

servingsobjectoptional

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".

tagsstring[]

The source site’s own keywords, cleaned but not mapped to any vocabulary.

techniquesstring[]optional

Techniques the recipe uses, as words rather than slugs.

textobject
ingredientsstring[]

One line per ingredient.

instructionsstring[]

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.

timesobject
cookobjectoptional
secondsinteger

Seconds.

A length of time. Always seconds, never a formatted string.

inactiveobjectoptional
secondsinteger

Seconds.

A length of time. Always seconds, never a formatted string.

prepobjectoptional
secondsinteger

Seconds.

A length of time. Always seconds, never a formatted string.

totalobjectoptional
secondsinteger

Seconds.

A length of time. Always seconds, never a formatted string.

Preparation, cooking, inactive and total time, each in seconds.

titlestring

The recipe title.

updatedAtstring

When the recipe was last written. ISO 8601.

urlstring

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

The JSON the Ingredient substitutions endpoint answers with.

substitutions[]object[]
ingredientstring

The ingredient asked about, normalized.

optionsobject[]

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.

unknownstring[]

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

The JSON the Get a recipe endpoint answers with.

conversionobjectoptional
systemstring

The system the recipe was rewritten in.

unweighedstring[]

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.

nutritionTotalsobjectoptional
basisServingsnumber

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.

perRecipeobject

Nutrition for the whole recipe.

perServingobject

Nutrition for one serving.

servingsnumber

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.

recipeobject
allergensobjectoptional
<allergen>boolean

One key per allergen identifier from GET /vocabularies, such as "milk" or "gluten-cereals": true when the recipe contains it.

disclaimerstring

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.

authorobjectoptional

Who wrote the recipe, and a link to them when the site published one.

categoriesstring[]

Normalized category slugs from an open set, such as "pasta" or "soup". The value the `category` filter takes.

coursesstring[]

Course slugs from the closed list. The value the `course` filter takes.

createdAtstring

When the recipe first entered the database. ISO 8601.

cuisinesstring[]

Cuisine slugs from the closed list. The value the `cuisine` filter takes.

descriptionstringoptional

The recipe’s own summary.

dietaryobjectoptional

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.

equipmentstring[]optional

Equipment the recipe calls for, as words rather than slugs.

groupsstring[]

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.

idstring

The recipe id.

ingredients[]object[]
displaystring

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.

groupstringoptional

The section header the line sat under, such as "For the sauce".

ingredientIdstringoptional

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.

localNamestringoptional

The ingredient as this recipe’s own language names it, when that differs from `name`.

localPreparationstringoptional

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.

namestring

The canonical English name.

notestringoptional

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.

optionalboolean

Whether the recipe marks this ingredient as optional.

originalstring

The source line, verbatim. Rewriting a recipe — scaling it, converting its units — leaves this alone.

preparationstringoptional

How the ingredient is prepared, in English, such as "finely chopped". Read `localPreparation` for the words the recipe itself uses.

quantityobjectoptional
maxnumberoptional

The top of a range.

unitstringoptional

One of the units listed by GET /vocabularies.

valuenumber

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.

sizestringoptional

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[]
durationobjectoptional
secondsinteger

Seconds.

A length of time. Always seconds, never a formatted string.

equipmentstring[]optional

Equipment slugs the step calls for.

groupstringoptional

The section the step sat under or, where the page named no section, the heading the step carried of its own.

ingredientsstring[]optional

Canonical ingredient ids the step uses.

stepinteger

The step number. Steps always run 1, 2, 3… in order.

techniquesstring[]optional

Technique slugs the step uses, such as "saute".

temperatureobjectoptional

An oven or pan temperature, with its unit as "C" or "F".

textstring

The step text.

One step. The text is authoritative; everything else on a step comes from enrichment and may be absent.

languagestring

The language the recipe is written in, as a two-letter ISO 639-1 code.

media[]object[]
altstringoptional

Alternative text.

captionstringoptional

A caption published with the item.

idstring

Unique within the recipe.

rolestring

Where the item sits in the recipe.

stepintegeroptional

For role "step", the step number the item illustrates.

typestring

"image" or "video".

urlstring

The file itself.

variantsobject[]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.

notesstring[]optional

What the writer added beside the method: storage, make-ahead, substitutions. One entry per note, in the order the page wrote them.

nutritionobjectoptional
basisobject

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".

caloriesobjectoptional

Energy, with its unit.

carbohydratesobjectoptional

Carbohydrates.

fatobjectoptional

Fat.

fiberobjectoptional

Fibre.

micronutrientsobjectoptional

Anything else the source declared, keyed by nutrient slug.

proteinobjectoptional

Protein.

saturatedFatobjectoptional

Saturated fat.

sodiumobjectoptional

Sodium.

sourcestring

"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.

sugarobjectoptional

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.

ratingobjectoptional

The rating the source published, with how many people rated it.

servingsobjectoptional

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".

tagsstring[]

The source site’s own keywords, cleaned but not mapped to any vocabulary.

techniquesstring[]optional

Techniques the recipe uses, as words rather than slugs.

textobject
ingredientsstring[]

One line per ingredient.

instructionsstring[]

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.

timesobject
cookobjectoptional
secondsinteger

Seconds.

A length of time. Always seconds, never a formatted string.

inactiveobjectoptional
secondsinteger

Seconds.

A length of time. Always seconds, never a formatted string.

prepobjectoptional
secondsinteger

Seconds.

A length of time. Always seconds, never a formatted string.

totalobjectoptional
secondsinteger

Seconds.

A length of time. Always seconds, never a formatted string.

Preparation, cooking, inactive and total time, each in seconds.

titlestring

The recipe title.

updatedAtstring

When the recipe was last written. ISO 8601.

urlstring

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

The JSON the List ingredients endpoint answers with.

ingredients[]object[]
aliasesobject

Every spelling seen, keyed by two-letter language code.

idstring

The canonical id, such as "chicken-thigh".

namesobject

The canonical name, keyed by two-letter language code.

recipeCountinteger

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

The JSON the Vocabularies endpoint answers with.

allergensobject[]

The 16 EU and US regulated allergen features and their applicable jurisdictions.

coursesstring[]

The values the `course` filter accepts.

cuisinesstring[]

The values the `cuisine` filter accepts.

dietsstring[]

The values the `diet` filter accepts.

unitsstring[]

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

The JSON the Popular recipes endpoint answers with, 5 recipes at a time.

paginationobject
limitinteger

How many recipes this response holds. Capped at 100.

offsetinteger

How many were skipped.

totalinteger

How many match the filter in total.

Offset pagination.

recipes[]object[]
allergensobjectoptional
<allergen>boolean

One key per allergen identifier from GET /vocabularies, such as "milk" or "gluten-cereals": true when the recipe contains it.

disclaimerstring

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.

authorobjectoptional

Who wrote the recipe, and a link to them when the site published one.

categoriesstring[]

Normalized category slugs from an open set, such as "pasta" or "soup". The value the `category` filter takes.

coursesstring[]

Course slugs from the closed list. The value the `course` filter takes.

createdAtstring

When the recipe first entered the database. ISO 8601.

cuisinesstring[]

Cuisine slugs from the closed list. The value the `cuisine` filter takes.

descriptionstringoptional

The recipe’s own summary.

dietaryobjectoptional

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.

equipmentstring[]optional

Equipment the recipe calls for, as words rather than slugs.

groupsstring[]

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.

idstring

The recipe id.

ingredients[]object[]
displaystring

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.

groupstringoptional

The section header the line sat under, such as "For the sauce".

ingredientIdstringoptional

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.

localNamestringoptional

The ingredient as this recipe’s own language names it, when that differs from `name`.

localPreparationstringoptional

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.

namestring

The canonical English name.

notestringoptional

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.

optionalboolean

Whether the recipe marks this ingredient as optional.

originalstring

The source line, verbatim. Rewriting a recipe — scaling it, converting its units — leaves this alone.

preparationstringoptional

How the ingredient is prepared, in English, such as "finely chopped". Read `localPreparation` for the words the recipe itself uses.

quantityobjectoptional
maxnumberoptional

The top of a range.

unitstringoptional

One of the units listed by GET /vocabularies.

valuenumber

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.

sizestringoptional

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[]
durationobjectoptional
secondsinteger

Seconds.

A length of time. Always seconds, never a formatted string.

equipmentstring[]optional

Equipment slugs the step calls for.

groupstringoptional

The section the step sat under or, where the page named no section, the heading the step carried of its own.

ingredientsstring[]optional

Canonical ingredient ids the step uses.

stepinteger

The step number. Steps always run 1, 2, 3… in order.

techniquesstring[]optional

Technique slugs the step uses, such as "saute".

temperatureobjectoptional

An oven or pan temperature, with its unit as "C" or "F".

textstring

The step text.

One step. The text is authoritative; everything else on a step comes from enrichment and may be absent.

languagestring

The language the recipe is written in, as a two-letter ISO 639-1 code.

media[]object[]
altstringoptional

Alternative text.

captionstringoptional

A caption published with the item.

idstring

Unique within the recipe.

rolestring

Where the item sits in the recipe.

stepintegeroptional

For role "step", the step number the item illustrates.

typestring

"image" or "video".

urlstring

The file itself.

variantsobject[]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.

notesstring[]optional

What the writer added beside the method: storage, make-ahead, substitutions. One entry per note, in the order the page wrote them.

nutritionobjectoptional
basisobject

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".

caloriesobjectoptional

Energy, with its unit.

carbohydratesobjectoptional

Carbohydrates.

fatobjectoptional

Fat.

fiberobjectoptional

Fibre.

micronutrientsobjectoptional

Anything else the source declared, keyed by nutrient slug.

proteinobjectoptional

Protein.

saturatedFatobjectoptional

Saturated fat.

sodiumobjectoptional

Sodium.

sourcestring

"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.

sugarobjectoptional

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.

ratingobjectoptional

The rating the source published, with how many people rated it.

servingsobjectoptional

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".

tagsstring[]

The source site’s own keywords, cleaned but not mapped to any vocabulary.

techniquesstring[]optional

Techniques the recipe uses, as words rather than slugs.

textobject
ingredientsstring[]

One line per ingredient.

instructionsstring[]

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.

timesobject
cookobjectoptional
secondsinteger

Seconds.

A length of time. Always seconds, never a formatted string.

inactiveobjectoptional
secondsinteger

Seconds.

A length of time. Always seconds, never a formatted string.

prepobjectoptional
secondsinteger

Seconds.

A length of time. Always seconds, never a formatted string.

totalobjectoptional
secondsinteger

Seconds.

A length of time. Always seconds, never a formatted string.

Preparation, cooking, inactive and total time, each in seconds.

titlestring

The recipe title.

updatedAtstring

When the recipe was last written. ISO 8601.

urlstring

The page the recipe was read from. One source URL is one recipe.

popularityScorenumber

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

The JSON the Search recipes endpoint answers with, 5 recipes at a time.

results[]object[]
allergensobjectoptional
<allergen>boolean

One key per allergen identifier from GET /vocabularies, such as "milk" or "gluten-cereals": true when the recipe contains it.

disclaimerstring

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.

authorobjectoptional

Who wrote the recipe, and a link to them when the site published one.

categoriesstring[]

Normalized category slugs from an open set, such as "pasta" or "soup". The value the `category` filter takes.

coursesstring[]

Course slugs from the closed list. The value the `course` filter takes.

createdAtstring

When the recipe first entered the database. ISO 8601.

cuisinesstring[]

Cuisine slugs from the closed list. The value the `cuisine` filter takes.

descriptionstringoptional

The recipe’s own summary.

dietaryobjectoptional

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.

equipmentstring[]optional

Equipment the recipe calls for, as words rather than slugs.

groupsstring[]

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.

idstring

The recipe id.

ingredients[]object[]
displaystring

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.

groupstringoptional

The section header the line sat under, such as "For the sauce".

ingredientIdstringoptional

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.

localNamestringoptional

The ingredient as this recipe’s own language names it, when that differs from `name`.

localPreparationstringoptional

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.

namestring

The canonical English name.

notestringoptional

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.

optionalboolean

Whether the recipe marks this ingredient as optional.

originalstring

The source line, verbatim. Rewriting a recipe — scaling it, converting its units — leaves this alone.

preparationstringoptional

How the ingredient is prepared, in English, such as "finely chopped". Read `localPreparation` for the words the recipe itself uses.

quantityobjectoptional
maxnumberoptional

The top of a range.

unitstringoptional

One of the units listed by GET /vocabularies.

valuenumber

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.

sizestringoptional

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[]
durationobjectoptional
secondsinteger

Seconds.

A length of time. Always seconds, never a formatted string.

equipmentstring[]optional

Equipment slugs the step calls for.

groupstringoptional

The section the step sat under or, where the page named no section, the heading the step carried of its own.

ingredientsstring[]optional

Canonical ingredient ids the step uses.

stepinteger

The step number. Steps always run 1, 2, 3… in order.

techniquesstring[]optional

Technique slugs the step uses, such as "saute".

temperatureobjectoptional

An oven or pan temperature, with its unit as "C" or "F".

textstring

The step text.

One step. The text is authoritative; everything else on a step comes from enrichment and may be absent.

languagestring

The language the recipe is written in, as a two-letter ISO 639-1 code.

media[]object[]
altstringoptional

Alternative text.

captionstringoptional

A caption published with the item.

idstring

Unique within the recipe.

rolestring

Where the item sits in the recipe.

stepintegeroptional

For role "step", the step number the item illustrates.

typestring

"image" or "video".

urlstring

The file itself.

variantsobject[]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.

notesstring[]optional

What the writer added beside the method: storage, make-ahead, substitutions. One entry per note, in the order the page wrote them.

nutritionobjectoptional
basisobject

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".

caloriesobjectoptional

Energy, with its unit.

carbohydratesobjectoptional

Carbohydrates.

fatobjectoptional

Fat.

fiberobjectoptional

Fibre.

micronutrientsobjectoptional

Anything else the source declared, keyed by nutrient slug.

proteinobjectoptional

Protein.

saturatedFatobjectoptional

Saturated fat.

sodiumobjectoptional

Sodium.

sourcestring

"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.

sugarobjectoptional

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.

ratingobjectoptional

The rating the source published, with how many people rated it.

servingsobjectoptional

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".

tagsstring[]

The source site’s own keywords, cleaned but not mapped to any vocabulary.

techniquesstring[]optional

Techniques the recipe uses, as words rather than slugs.

textobject
ingredientsstring[]

One line per ingredient.

instructionsstring[]

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.

timesobject
cookobjectoptional
secondsinteger

Seconds.

A length of time. Always seconds, never a formatted string.

inactiveobjectoptional
secondsinteger

Seconds.

A length of time. Always seconds, never a formatted string.

prepobjectoptional
secondsinteger

Seconds.

A length of time. Always seconds, never a formatted string.

totalobjectoptional
secondsinteger

Seconds.

A length of time. Always seconds, never a formatted string.

Preparation, cooking, inactive and total time, each in seconds.

titlestring

The recipe title.

updatedAtstring

When the recipe was last written. ISO 8601.

urlstring

The page the recipe was read from. One source URL is one recipe.

scorenumber

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
    }
  ]
}