---
title: "Use from your agent — Tiny Plates recipe API"
description: "Connect Claude Code, Codex, Cursor, VS Code, Gemini CLI or any MCP client to Tiny Plates, sign in with your account, and let your agent search recipes."
url: "https://www.tinyplates.dev/docs/mcp"
---

# Use from your agent

The API is also an MCP server, so an agent such as Claude, ChatGPT, Claude Code or Cursor 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. In Claude on the web or desktop, open Customize → Connectors, choose Add custom connector, and paste the server URL:  
```  
https://api.tinyplates.dev/mcp  
```
2. Choose Connect, then sign in with your Tiny Plates account.

## Signing in

The first time the agent connects, it opens Tiny Plates in your browser. Sign in — or [create an account](https://www.tinyplates.dev/sign-up) — 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](https://www.tinyplates.dev/dashboard/usage), and is subject to the same [rate limits](https://www.tinyplates.dev/docs/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](https://www.tinyplates.dev/docs/authentication) 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](https://www.tinyplates.dev/dashboard/keys).

## 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:

* [cook\_from\_pantry](https://www.tinyplates.dev/docs/mcp#tool-cook%5Ffrom%5Fpantry)
* [find\_recipes](https://www.tinyplates.dev/docs/mcp#tool-find%5Frecipes)
* [popular\_recipes](https://www.tinyplates.dev/docs/mcp#tool-popular%5Frecipes)
* [search\_recipes](https://www.tinyplates.dev/docs/mcp#tool-search%5Frecipes)

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](https://www.tinyplates.dev/docs/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

* `recipes`string\[\]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](https://www.tinyplates.dev/docs/api/shopping-list) endpoint answers with.

`items[]`object\[\]

`category`string

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

`display`string

The line as a reader would write it.

`extras`object\[\]optional

Amounts a recipe asked for in a unit the quantity cannot take, one per unit, such as the 3 tbsp in "1 cup + 3 tbsp". Buy them as well as the quantity.

`name`string

The ingredient name.

`plusMore`booleanoptional

Present when a recipe also asked for this without saying how much — oil for frying, a garnish — so the quantity is a minimum rather than the whole of it.

`quantity`objectoptional

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

`recipeIds`string\[\]

The ids of the recipes that asked for it.

The list, grouped by aisle and then by name.

`recipes[]`object\[\]

`id`string

The recipe id.

`servings`number

The servings the recipe was scaled to.

`title`string

The recipe title.

The recipes the list was built from, in the order they were asked for, with the servings each was scaled to.

Example response

```
{
  "items": [
    {
      "category": "dairy",
      "display": "250 ml double cream",
      "name": "double cream",
      "quantity": {
        "unit": "ml",
        "value": 250
      },
      "recipeIds": [
        "6a9820a88f8122ec891b680b"
      ]
    },
    {
      "category": "dairy",
      "display": "1 cup + 3 tbsp pecorino romano",
      "extras": [
        {
          "unit": "tbsp",
          "value": 3
        }
      ],
      "name": "pecorino romano",
      "quantity": {
        "unit": "cup",
        "value": 1
      },
      "recipeIds": [
        "6a9820e58f8122ec891b68a4"
      ]
    },
    {
      "category": "meat",
      "display": "1.2 kg chicken thighs",
      "name": "chicken thighs",
      "quantity": {
        "unit": "kg",
        "value": 1.2
      },
      "recipeIds": [
        "6a9820a88f8122ec891b680b",
        "6a9820e58f8122ec891b68a4"
      ]
    },
    {
      "category": "produce",
      "display": "5 onion",
      "name": "onion",
      "quantity": {
        "value": 5
      },
      "recipeIds": [
        "6a9820a88f8122ec891b680b",
        "6a9820e58f8122ec891b68a4"
      ]
    },
    {
      "category": "spices",
      "display": "salt",
      "name": "salt",
      "recipeIds": [
        "6a9820e58f8122ec891b68a4"
      ]
    }
  ],
  "recipes": [
    {
      "id": "6a9820a88f8122ec891b680b",
      "servings": 6,
      "title": "Chicken Tikka Masala"
    },
    {
      "id": "6a9820e58f8122ec891b68a4",
      "servings": 4,
      "title": "Slow-Roasted Cherry Tomatoes"
    }
  ]
}
```

### cook\_from\_pantry

Cook from your pantry

Find what you can cook from the ingredients you have, best covered first. Each recipe lists the pantry ingredients it uses and the ones you are missing; maxMissing: 0 returns what you can cook right now. Common staples — salt, pepper, water, oil, sugar, flour — are assumed to be on hand: they are left out of the coverage and of missingIngredients and returned in assumedIngredients instead. Send staples: false to count them as ingredients you need.

Parameters

* `ingredients`string\[\]required  
The ingredients you have. 1 to 20 names or canonical ids from list\_ingredients, such as "chicken" or "chicken-thigh".
* `language`string  
Only recipes written in this language, as a two-letter ISO 639-1 code such as "en" or "sv".
* `limit`integer  
How many recipes to return, 1–5\. Defaults to 5.
* `maxMissing`integer  
Only recipes missing at most this many ingredients, 0–20\. Left out, any number may be missing.
* `offset`integer  
How many recipes to skip, to fetch the next page. The response’s pagination.total says how many match.
* `staples`string  
Whether salt, pepper, water, oil, sugar and flour count as already in the kitchen. Defaults to true; false counts them as ingredients you need.
* `without`string\[\]  
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 [Cook from your pantry](https://www.tinyplates.dev/docs/api/pantry-recipes) endpoint answers with, 5 recipes at a time.

`pagination`object

`limit`integer

How many recipes this response holds. Capped at 100.

`offset`integer

How many were skipped.

`total`integer

How many match the filter in total.

Offset pagination.

`recipes[]`object\[\]

`allergens`objectoptional

`<allergen>`boolean

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

`disclaimer`string

The required informational-use warning.

Whether the recipe contains each EU and US regulated allergen: one true or false for each of the 16 allergen identifiers, keyed by identifier, beside the disclaimer. Informational only; verify product labels before serving someone with an allergy.

`author`objectoptional

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

`categories`string\[\]

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

`courses`string\[\]

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

`createdAt`string

When the recipe first entered the database. ISO 8601.

`cuisines`string\[\]

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

`description`stringoptional

The recipe’s own summary.

`dietary`objectoptional

Dietary flags, declared by the site or inferred from the required ingredients. A declared flag wins; a missing flag is unknown, and false is a known no. An inferred \`glutenFree\` or \`dairyFree\` can disagree with \`allergens\` by design: the diet reads the required ingredients, so a dish is gluten-free once the optional pita is left out, while the allergen block counts every line and stays cautious.

`equipment`string\[\]optional

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

`groups`string\[\]

The section headers of the recipe: the distinct \`group\` values of the ingredients and then the steps, in the order they first appear. Empty when the recipe has no sections.

`id`string

The recipe id.

`ingredients[]`object\[\]

`display`string

The line to render. Equal to the source line until the structure and the source part company — a converted unit, an amount enrichment filled in.

`group`stringoptional

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

`ingredientId`stringoptional

The canonical ingredient id, such as "chicken-thigh". Absent until the recipe has been enriched, or when the name could not be resolved. This is the value the \`ingredient\` filter of GET /recipes takes.

`localName`stringoptional

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

`localPreparation`stringoptional

How the ingredient is prepared, in the recipe’s own words, such as "finhackade" where \`preparation\` says "finely chopped". Absent on an English recipe, where \`preparation\` already is the reader’s, and on a line that says nothing of the kind. \`display\` is written with this one.

`name`string

The canonical English name.

`note`stringoptional

Anything the parser understood but could not place, such as "(400 g)". Kept as the source wrote it, in the recipe’s language, and never translated.

`optional`boolean

Whether the recipe marks this ingredient as optional.

`original`string

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

`preparation`stringoptional

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

`quantity`objectoptional

`max`numberoptional

The top of a range.

`unit`stringoptional

One of the units listed by GET /vocabularies.

`value`number

The amount itself.

The amount. A range such as "2-3 tomatoes" is a value of 2 with a max of 3\. A value with no unit is a count of pieces.

`size`stringoptional

A size qualifier, such as "large".

One ingredient line, parsed. \`original\` is the line the site published; \`display\` is the same line written back from these fields, in the recipe’s own language.

`instructions[]`object\[\]

`duration`objectoptional

`seconds`integer

Seconds.

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

`equipment`string\[\]optional

Equipment slugs the step calls for.

`group`stringoptional

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

`ingredients`string\[\]optional

Canonical ingredient ids the step uses.

`step`integer

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

`techniques`string\[\]optional

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

`temperature`objectoptional

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

`text`string

The step text.

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

`language`string

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

`media[]`object\[\]

`alt`stringoptional

Alternative text.

`caption`stringoptional

A caption published with the item.

`id`string

Unique within the recipe.

`role`string

Where the item sits in the recipe.

`step`integeroptional

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

`type`string

"image" or "video".

`url`string

The file itself.

`variants`object\[\]optional

The same photo in other sizes or crops. Images only.

Images and videos. An image carries a \`role\` of hero, gallery, step or thumbnail; a video carries gallery or step. A recipe has at most one hero image.

`notes`string\[\]optional

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

`nutrition`objectoptional

`basis`object

What the numbers are per. \`type\` is "serving", "recipe" or "100g"; \`servings\` is the serving count the site worked the numbers out on, which is not always the serving count the recipe is written for; \`description\` is the serving size the site named, such as "1 cup".

`calories`objectoptional

Energy, with its unit.

`carbohydrates`objectoptional

Carbohydrates.

`fat`objectoptional

Fat.

`fiber`objectoptional

Fibre.

`micronutrients`objectoptional

Anything else the source declared, keyed by nutrient slug.

`protein`objectoptional

Protein.

`saturatedFat`objectoptional

Saturated fat.

`sodium`objectoptional

Sodium.

`source`string

"provided": the site published these numbers itself, in the structured data the recipe was read from, so they are as current as the last read of that page.

`sugar`objectoptional

Sugar.

Nutrition as the site published it. \`basis\` says whether the numbers are per serving, per recipe or per 100 g. The API does not compute nutrition from the ingredients, so a recipe whose site publishes none has no nutrition object at all.

`rating`objectoptional

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

`servings`objectoptional

How much the recipe makes. "Serves 4-6" is a quantity of 4 with a max of 6; "Makes 24 cookies" is a quantity of 24 with a unit of "cookie".

`tags`string\[\]

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

`techniques`string\[\]optional

Techniques the recipe uses, as words rather than slugs.

`text`object

`ingredients`string\[\]

One line per ingredient.

`instructions`string\[\]

One line per step.

The recipe as plain lines: every ingredient’s \`display\` and every step’s \`text\`, in order. A convenience for rendering; nothing here is missing from the structured fields.

`times`object

`cook`objectoptional

`seconds`integer

Seconds.

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

`inactive`objectoptional

`seconds`integer

Seconds.

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

`prep`objectoptional

`seconds`integer

Seconds.

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

`total`objectoptional

`seconds`integer

Seconds.

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

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

`title`string

The recipe title.

`updatedAt`string

When the recipe was last written. ISO 8601.

`url`string

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

`assumedIngredients`string\[\]

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

`coverage`number

The share of the recipe's ingredients your pantry covers, from 0 to 1, rounded to two decimals. Staples are in neither half of it.

`matchedIngredients`string\[\]

The recipe ingredients your pantry covers.

`missingIngredients`string\[\]

The recipe ingredients your pantry does not cover.

The recipes, best covered first.

Example response

```
{
  "pagination": {
    "limit": 1,
    "offset": 0,
    "total": 112
  },
  "recipes": [
    {
      "allergens": {
        "celery": false,
        "crustaceans": false,
        "eggs": false,
        "fish": false,
        "gluten-cereals": false,
        "lupin": false,
        "milk": true,
        "molluscs": false,
        "mustard": false,
        "nuts-eu": false,
        "peanuts": true,
        "sesame": false,
        "soy": false,
        "sulphites": false,
        "tree-nuts-us": false,
        "wheat": false,
        "disclaimer": "Informational only; not medical advice. Verify ingredients and product labels before serving someone with an allergy."
      },
      "id": "6a9820e58f8122ec891b68a3",
      "author": {
        "name": "Lindsay Ostrom",
        "url": "https://pinchofyum.com/about"
      },
      "description": "This peanut butter dark chocolate hummus is a sweet alternative to traditional hummus. Perfect served on graham crackers as an afternoon snack!",
      "instructions": [
        {
          "group": "Hummus",
          "step": 1,
          "text": "Blend everything through milk in a food processor."
        },
        {
          "group": "Hummus",
          "step": 2,
          "text": "Add flour by the spoonful and blend until desired consistency is reached."
        },
        {
          "step": 3,
          "text": "Stir in dark chocolate."
        },
        {
          "step": 4,
          "text": "Chill before serving."
        }
      ],
      "language": "en",
      "media": [
        {
          "id": "hero",
          "role": "hero",
          "type": "image",
          "url": "https://pinchofyum.com/tachyon/2011/05/Peanut-Butter-Dark-Chocolate-Hummus.jpeg?fit=225%2C225",
          "variants": [
            {
              "url": "https://pinchofyum.com/tachyon/2011/05/Peanut-Butter-Dark-Chocolate-Hummus.jpeg?fit=195%2C195"
            },
            {
              "url": "https://pinchofyum.com/tachyon/2011/05/Peanut-Butter-Dark-Chocolate-Hummus.jpeg?fit=180%2C180"
            },
            {
              "url": "https://pinchofyum.com/tachyon/2011/05/Peanut-Butter-Dark-Chocolate-Hummus.jpeg"
            }
          ]
        }
      ],
      "notes": [
        "Keeps in an airtight container in the fridge for up to five days.",
        "Swap the peanut butter for almond butter to make it peanut free."
      ],
      "nutrition": {
        "basis": {
          "description": "¼ cup",
          "servings": 8,
          "type": "serving"
        },
        "calories": {
          "unit": "kcal",
          "value": 201
        },
        "carbohydrates": {
          "unit": "g",
          "value": 29.4
        },
        "cholesterol": {
          "unit": "mg",
          "value": 0.8
        },
        "fat": {
          "unit": "g",
          "value": 7.4
        },
        "fiber": {
          "unit": "g",
          "value": 3.3
        },
        "micronutrients": {
          "trans-fat": {
            "unit": "g",
            "value": 0
          }
        },
        "protein": {
          "unit": "g",
          "value": 5.6
        },
        "saturatedFat": {
          "unit": "g",
          "value": 2.5
        },
        "sodium": {
          "unit": "mg",
          "value": 76
        },
        "source": "provided",
        "sugar": {
          "unit": "g",
          "value": 16.9
        }
      },
      "rating": {
        "count": 1,
        "reviewCount": 1,
        "value": 5
      },
      "servings": {
        "max": 8,
        "original": "6-8",
        "quantity": 6
      },
      "times": {
        "cook": {
          "seconds": 600
        },
        "prep": {
          "seconds": 300
        },
        "total": {
          "seconds": 900
        }
      },
      "title": "Peanut Butter Dark Chocolate Hummus",
      "categories": [],
      "courses": [
        "dessert"
      ],
      "createdAt": "2026-09-02T13:13:09.089Z",
      "cuisines": [
        "american"
      ],
      "groups": [
        "Hummus"
      ],
      "ingredients": [
        {
          "display": "1 can white beans or chickpeas, rinsed",
          "name": "white beans or chickpeas",
          "optional": false,
          "original": "1 can white beans or chickpeas, rinsed",
          "preparation": "rinsed",
          "quantity": {
            "unit": "can",
            "value": 1
          }
        },
        {
          "display": "¼ cup peanut butter",
          "name": "peanut butter",
          "optional": false,
          "original": "¼ cup peanut butter",
          "quantity": {
            "unit": "cup",
            "value": 0.25
          }
        },
        {
          "display": "2 tbsp caramel sauce",
          "name": "caramel sauce",
          "optional": false,
          "original": "2 tbsp caramel sauce",
          "quantity": {
            "unit": "tbsp",
            "value": 2
          }
        },
        {
          "display": "2 tbsp maple syrup",
          "name": "maple syrup",
          "optional": false,
          "original": "2 tbsp maple syrup",
          "quantity": {
            "unit": "tbsp",
            "value": 2
          }
        },
        {
          "display": "¼ cup brown sugar",
          "name": "brown sugar",
          "optional": false,
          "original": "¼ cup brown sugar",
          "quantity": {
            "unit": "cup",
            "value": 0.25
          }
        },
        {
          "display": "pinch of cinnamon",
          "name": "pinch of cinnamon",
          "optional": false,
          "original": "pinch of cinnamon"
        },
        {
          "display": "¼ cup milk",
          "name": "milk",
          "optional": false,
          "original": "¼ cup milk",
          "quantity": {
            "unit": "cup",
            "value": 0.25
          }
        },
        {
          "display": "¼ cup flour",
          "name": "flour",
          "optional": false,
          "original": "¼ cup flour",
          "quantity": {
            "unit": "cup",
            "value": 0.25
          }
        },
        {
          "display": "chopped dark chocolate",
          "name": "chopped dark chocolate",
          "optional": false,
          "original": "chopped dark chocolate"
        }
      ],
      "tags": [
        "chocolate hummus",
        "peanut butter hummus",
        "peanut butter chocolate",
        "hummus recipe",
        "dessert hummus"
      ],
      "text": {
        "ingredients": [
          "1 can white beans or chickpeas, rinsed",
          "¼ cup peanut butter",
          "2 tbsp caramel sauce",
          "2 tbsp maple syrup",
          "¼ cup brown sugar",
          "pinch of cinnamon",
          "¼ cup milk",
          "¼ cup flour",
          "chopped dark chocolate"
        ],
        "instructions": [
          "Blend everything through milk in a food processor.",
          "Add flour by the spoonful and blend until desired consistency is reached.",
          "Stir in dark chocolate.",
          "Chill before serving."
        ]
      },
      "updatedAt": "2026-09-06T01:11:59.223Z",
      "url": "https://pinchofyum.com/pb-dark-chocolate-hummus",
      "assumedIngredients": [
        "flour"
      ],
      "coverage": 0.75,
      "matchedIngredients": [
        "white beans or chickpeas",
        "peanut butter",
        "maple syrup",
        "brown sugar",
        "pinch of cinnamon",
        "milk"
      ],
      "missingIngredients": [
        "caramel sauce",
        "chopped dark chocolate"
      ]
    }
  ]
}
```

### find\_recipes

Find recipes

List recipes newest first, filtered by any combination of cuisine, course, category, diet, ingredients, allergens, equipment, time and nutrition. Use search\_recipes instead to search by meaning. Allowed cuisines, courses and diets come from list\_vocabularies.

Parameters

* `category`string  
A category slug such as "pasta" or "soup", as a recipe's categories field carries it.
* `course`string  
A course from list\_vocabularies, such as "main-course".
* `cuisine`string  
A cuisine from list\_vocabularies, such as "italian".
* `diet`string  
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.
* `equipment`string\[\]  
Equipment every recipe must use, such as "air fryer" or "slow cooker".
* `excludeIngredients`string\[\]  
Leave out recipes using any of these ingredient names or ids. Not an allergen guarantee.
* `ingredients`string\[\]  
Ingredient names or ids every recipe must use.
* `language`string  
Only recipes written in this language, as a two-letter ISO 639-1 code such as "en" or "sv".
* `limit`integer  
How many recipes to return, 1–5\. Defaults to 5.
* `maxCalories`integer  
Maximum kilocalories per serving.
* `maxCookMinutes`integer  
Maximum cooking time in minutes.
* `maxSodium`integer  
Maximum milligrams of sodium per serving.
* `maxTotalMinutes`integer  
Maximum total time in minutes.
* `minFiber`integer  
Minimum grams of fiber per serving.
* `minProtein`integer  
Minimum grams of protein per serving.
* `nutrition`string\[\]  
Nutrition presets: "high-fiber", "high-protein", "low-calorie", "low-sodium".
* `offset`integer  
How many recipes to skip, to fetch the next page. The response’s pagination.total says how many match.
* `time`string  
A total-time preset: "under-15", "under-30" or "weekend".
* `without`string\[\]  
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 [List recipes](https://www.tinyplates.dev/docs/api/list-recipes) endpoint answers with, 5 recipes at a time.

`pagination`object

`limit`integer

How many recipes this response holds. Capped at 100.

`offset`integer

How many were skipped.

`total`integer

How many match the filter in total.

Offset pagination.

`recipes[]`object\[\]

`allergens`objectoptional

`<allergen>`boolean

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

`disclaimer`string

The required informational-use warning.

Whether the recipe contains each EU and US regulated allergen: one true or false for each of the 16 allergen identifiers, keyed by identifier, beside the disclaimer. Informational only; verify product labels before serving someone with an allergy.

`author`objectoptional

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

`categories`string\[\]

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

`courses`string\[\]

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

`createdAt`string

When the recipe first entered the database. ISO 8601.

`cuisines`string\[\]

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

`description`stringoptional

The recipe’s own summary.

`dietary`objectoptional

Dietary flags, declared by the site or inferred from the required ingredients. A declared flag wins; a missing flag is unknown, and false is a known no. An inferred \`glutenFree\` or \`dairyFree\` can disagree with \`allergens\` by design: the diet reads the required ingredients, so a dish is gluten-free once the optional pita is left out, while the allergen block counts every line and stays cautious.

`equipment`string\[\]optional

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

`groups`string\[\]

The section headers of the recipe: the distinct \`group\` values of the ingredients and then the steps, in the order they first appear. Empty when the recipe has no sections.

`id`string

The recipe id.

`ingredients[]`object\[\]

`display`string

The line to render. Equal to the source line until the structure and the source part company — a converted unit, an amount enrichment filled in.

`group`stringoptional

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

`ingredientId`stringoptional

The canonical ingredient id, such as "chicken-thigh". Absent until the recipe has been enriched, or when the name could not be resolved. This is the value the \`ingredient\` filter of GET /recipes takes.

`localName`stringoptional

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

`localPreparation`stringoptional

How the ingredient is prepared, in the recipe’s own words, such as "finhackade" where \`preparation\` says "finely chopped". Absent on an English recipe, where \`preparation\` already is the reader’s, and on a line that says nothing of the kind. \`display\` is written with this one.

`name`string

The canonical English name.

`note`stringoptional

Anything the parser understood but could not place, such as "(400 g)". Kept as the source wrote it, in the recipe’s language, and never translated.

`optional`boolean

Whether the recipe marks this ingredient as optional.

`original`string

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

`preparation`stringoptional

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

`quantity`objectoptional

`max`numberoptional

The top of a range.

`unit`stringoptional

One of the units listed by GET /vocabularies.

`value`number

The amount itself.

The amount. A range such as "2-3 tomatoes" is a value of 2 with a max of 3\. A value with no unit is a count of pieces.

`size`stringoptional

A size qualifier, such as "large".

One ingredient line, parsed. \`original\` is the line the site published; \`display\` is the same line written back from these fields, in the recipe’s own language.

`instructions[]`object\[\]

`duration`objectoptional

`seconds`integer

Seconds.

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

`equipment`string\[\]optional

Equipment slugs the step calls for.

`group`stringoptional

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

`ingredients`string\[\]optional

Canonical ingredient ids the step uses.

`step`integer

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

`techniques`string\[\]optional

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

`temperature`objectoptional

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

`text`string

The step text.

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

`language`string

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

`media[]`object\[\]

`alt`stringoptional

Alternative text.

`caption`stringoptional

A caption published with the item.

`id`string

Unique within the recipe.

`role`string

Where the item sits in the recipe.

`step`integeroptional

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

`type`string

"image" or "video".

`url`string

The file itself.

`variants`object\[\]optional

The same photo in other sizes or crops. Images only.

Images and videos. An image carries a \`role\` of hero, gallery, step or thumbnail; a video carries gallery or step. A recipe has at most one hero image.

`notes`string\[\]optional

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

`nutrition`objectoptional

`basis`object

What the numbers are per. \`type\` is "serving", "recipe" or "100g"; \`servings\` is the serving count the site worked the numbers out on, which is not always the serving count the recipe is written for; \`description\` is the serving size the site named, such as "1 cup".

`calories`objectoptional

Energy, with its unit.

`carbohydrates`objectoptional

Carbohydrates.

`fat`objectoptional

Fat.

`fiber`objectoptional

Fibre.

`micronutrients`objectoptional

Anything else the source declared, keyed by nutrient slug.

`protein`objectoptional

Protein.

`saturatedFat`objectoptional

Saturated fat.

`sodium`objectoptional

Sodium.

`source`string

"provided": the site published these numbers itself, in the structured data the recipe was read from, so they are as current as the last read of that page.

`sugar`objectoptional

Sugar.

Nutrition as the site published it. \`basis\` says whether the numbers are per serving, per recipe or per 100 g. The API does not compute nutrition from the ingredients, so a recipe whose site publishes none has no nutrition object at all.

`rating`objectoptional

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

`servings`objectoptional

How much the recipe makes. "Serves 4-6" is a quantity of 4 with a max of 6; "Makes 24 cookies" is a quantity of 24 with a unit of "cookie".

`tags`string\[\]

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

`techniques`string\[\]optional

Techniques the recipe uses, as words rather than slugs.

`text`object

`ingredients`string\[\]

One line per ingredient.

`instructions`string\[\]

One line per step.

The recipe as plain lines: every ingredient’s \`display\` and every step’s \`text\`, in order. A convenience for rendering; nothing here is missing from the structured fields.

`times`object

`cook`objectoptional

`seconds`integer

Seconds.

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

`inactive`objectoptional

`seconds`integer

Seconds.

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

`prep`objectoptional

`seconds`integer

Seconds.

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

`total`objectoptional

`seconds`integer

Seconds.

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

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

`title`string

The recipe title.

`updatedAt`string

When the recipe was last written. ISO 8601.

`url`string

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

The matching recipes.

Example response

```
{
  "pagination": {
    "limit": 2,
    "offset": 0,
    "total": 1930
  },
  "recipes": [
    {
      "allergens": {
        "celery": false,
        "crustaceans": false,
        "eggs": false,
        "fish": false,
        "gluten-cereals": false,
        "lupin": false,
        "milk": true,
        "molluscs": false,
        "mustard": false,
        "nuts-eu": false,
        "peanuts": true,
        "sesame": false,
        "soy": false,
        "sulphites": false,
        "tree-nuts-us": false,
        "wheat": false,
        "disclaimer": "Informational only; not medical advice. Verify ingredients and product labels before serving someone with an allergy."
      },
      "id": "6a9820e58f8122ec891b68a3",
      "author": {
        "name": "Lindsay Ostrom",
        "url": "https://pinchofyum.com/about"
      },
      "description": "This peanut butter dark chocolate hummus is a sweet alternative to traditional hummus. Perfect served on graham crackers as an afternoon snack!",
      "instructions": [
        {
          "group": "Hummus",
          "step": 1,
          "text": "Blend everything through milk in a food processor."
        },
        {
          "group": "Hummus",
          "step": 2,
          "text": "Add flour by the spoonful and blend until desired consistency is reached."
        },
        {
          "step": 3,
          "text": "Stir in dark chocolate."
        },
        {
          "step": 4,
          "text": "Chill before serving."
        }
      ],
      "language": "en",
      "media": [
        {
          "id": "hero",
          "role": "hero",
          "type": "image",
          "url": "https://pinchofyum.com/tachyon/2011/05/Peanut-Butter-Dark-Chocolate-Hummus.jpeg?fit=225%2C225",
          "variants": [
            {
              "url": "https://pinchofyum.com/tachyon/2011/05/Peanut-Butter-Dark-Chocolate-Hummus.jpeg?fit=195%2C195"
            },
            {
              "url": "https://pinchofyum.com/tachyon/2011/05/Peanut-Butter-Dark-Chocolate-Hummus.jpeg?fit=180%2C180"
            },
            {
              "url": "https://pinchofyum.com/tachyon/2011/05/Peanut-Butter-Dark-Chocolate-Hummus.jpeg"
            }
          ]
        }
      ],
      "notes": [
        "Keeps in an airtight container in the fridge for up to five days.",
        "Swap the peanut butter for almond butter to make it peanut free."
      ],
      "nutrition": {
        "basis": {
          "description": "¼ cup",
          "servings": 8,
          "type": "serving"
        },
        "calories": {
          "unit": "kcal",
          "value": 201
        },
        "carbohydrates": {
          "unit": "g",
          "value": 29.4
        },
        "cholesterol": {
          "unit": "mg",
          "value": 0.8
        },
        "fat": {
          "unit": "g",
          "value": 7.4
        },
        "fiber": {
          "unit": "g",
          "value": 3.3
        },
        "micronutrients": {
          "trans-fat": {
            "unit": "g",
            "value": 0
          }
        },
        "protein": {
          "unit": "g",
          "value": 5.6
        },
        "saturatedFat": {
          "unit": "g",
          "value": 2.5
        },
        "sodium": {
          "unit": "mg",
          "value": 76
        },
        "source": "provided",
        "sugar": {
          "unit": "g",
          "value": 16.9
        }
      },
      "rating": {
        "count": 1,
        "reviewCount": 1,
        "value": 5
      },
      "servings": {
        "max": 8,
        "original": "6-8",
        "quantity": 6
      },
      "times": {
        "cook": {
          "seconds": 600
        },
        "prep": {
          "seconds": 300
        },
        "total": {
          "seconds": 900
        }
      },
      "title": "Peanut Butter Dark Chocolate Hummus",
      "categories": [],
      "courses": [
        "dessert"
      ],
      "createdAt": "2026-09-02T13:13:09.089Z",
      "cuisines": [
        "american"
      ],
      "groups": [
        "Hummus"
      ],
      "ingredients": [
        {
          "display": "1 can white beans or chickpeas, rinsed",
          "name": "white beans or chickpeas",
          "optional": false,
          "original": "1 can white beans or chickpeas, rinsed",
          "preparation": "rinsed",
          "quantity": {
            "unit": "can",
            "value": 1
          }
        },
        {
          "display": "¼ cup peanut butter",
          "name": "peanut butter",
          "optional": false,
          "original": "¼ cup peanut butter",
          "quantity": {
            "unit": "cup",
            "value": 0.25
          }
        },
        {
          "display": "2 tbsp caramel sauce",
          "name": "caramel sauce",
          "optional": false,
          "original": "2 tbsp caramel sauce",
          "quantity": {
            "unit": "tbsp",
            "value": 2
          }
        },
        {
          "display": "2 tbsp maple syrup",
          "name": "maple syrup",
          "optional": false,
          "original": "2 tbsp maple syrup",
          "quantity": {
            "unit": "tbsp",
            "value": 2
          }
        },
        {
          "display": "¼ cup brown sugar",
          "name": "brown sugar",
          "optional": false,
          "original": "¼ cup brown sugar",
          "quantity": {
            "unit": "cup",
            "value": 0.25
          }
        },
        {
          "display": "pinch of cinnamon",
          "name": "pinch of cinnamon",
          "optional": false,
          "original": "pinch of cinnamon"
        },
        {
          "display": "¼ cup milk",
          "name": "milk",
          "optional": false,
          "original": "¼ cup milk",
          "quantity": {
            "unit": "cup",
            "value": 0.25
          }
        },
        {
          "display": "¼ cup flour",
          "name": "flour",
          "optional": false,
          "original": "¼ cup flour",
          "quantity": {
            "unit": "cup",
            "value": 0.25
          }
        },
        {
          "display": "chopped dark chocolate",
          "name": "chopped dark chocolate",
          "optional": false,
          "original": "chopped dark chocolate"
        }
      ],
      "tags": [
        "chocolate hummus",
        "peanut butter hummus",
        "peanut butter chocolate",
        "hummus recipe",
        "dessert hummus"
      ],
      "text": {
        "ingredients": [
          "1 can white beans or chickpeas, rinsed",
          "¼ cup peanut butter",
          "2 tbsp caramel sauce",
          "2 tbsp maple syrup",
          "¼ cup brown sugar",
          "pinch of cinnamon",
          "¼ cup milk",
          "¼ cup flour",
          "chopped dark chocolate"
        ],
        "instructions": [
          "Blend everything through milk in a food processor.",
          "Add flour by the spoonful and blend until desired consistency is reached.",
          "Stir in dark chocolate.",
          "Chill before serving."
        ]
      },
      "updatedAt": "2026-09-06T01:11:59.223Z",
      "url": "https://pinchofyum.com/pb-dark-chocolate-hummus"
    },
    {
      "id": "6a9820e58f8122ec891b68a4",
      "description": "Slow-roasted cherry tomatoes are intensely sweet and tangy. Add them to salads, pastas, pizza and more.",
      "instructions": [
        {
          "step": 1,
          "text": "Preheat the oven to 275°F (135°C) and set an oven rack in the middle position. Line a baking sheet with wide heavy-duty aluminum foil."
        },
        {
          "step": 2,
          "text": "Directly on the lined baking sheet, using a rubber spatula, toss the tomatoes with the olive oil, vinegar, sugar, salt, pepper, and garlic. Roast for 2 hours, until the tomatoes are soft and beginning to burst. Serve hot or at room temperature."
        }
      ],
      "language": "en",
      "media": [
        {
          "id": "hero",
          "role": "hero",
          "type": "image",
          "url": "https://www.onceuponachef.com/images/2022/07/slow-roasted-cherry-tomatoes.jpg",
          "variants": [
            {
              "url": "https://www.onceuponachef.com/images/2022/07/slow-roasted-cherry-tomatoes-500x500.jpg"
            },
            {
              "url": "https://www.onceuponachef.com/images/2022/07/slow-roasted-cherry-tomatoes-500x375.jpg"
            },
            {
              "url": "https://www.onceuponachef.com/images/2022/07/slow-roasted-cherry-tomatoes-480x270.jpg"
            }
          ]
        }
      ],
      "nutrition": {
        "basis": {
          "type": "serving"
        },
        "calories": {
          "unit": "kcal",
          "value": 117
        },
        "carbohydrates": {
          "unit": "g",
          "value": 8
        },
        "fat": {
          "unit": "g",
          "value": 9
        },
        "fiber": {
          "unit": "g",
          "value": 2
        },
        "protein": {
          "unit": "g",
          "value": 1
        },
        "saturatedFat": {
          "unit": "g",
          "value": 1
        },
        "sodium": {
          "unit": "mg",
          "value": 388
        },
        "source": "provided",
        "sugar": {
          "unit": "g",
          "value": 6
        }
      },
      "rating": {
        "count": 25,
        "reviewCount": 8,
        "value": 4.8
      },
      "servings": {
        "original": "6",
        "quantity": 6
      },
      "times": {
        "cook": {
          "seconds": 7200
        },
        "prep": {
          "seconds": 600
        },
        "total": {
          "seconds": 7800
        }
      },
      "title": "Roasted Cherry Tomatoes",
      "categories": [
        "vegetables-and-sides"
      ],
      "courses": [
        "appetizer",
        "side-dish"
      ],
      "createdAt": "2026-09-02T13:13:09.118Z",
      "cuisines": [
        "italian"
      ],
      "groups": [],
      "ingredients": [
        {
          "display": "2 lb cherry tomatoes (3 pints)",
          "name": "cherry tomatoes",
          "note": "3 pints",
          "optional": false,
          "original": "2 lb cherry tomatoes (3 pints)",
          "quantity": {
            "unit": "lb",
            "value": 2
          }
        },
        {
          "display": "¼ cup extra-virgin olive oil",
          "name": "extra-virgin olive oil",
          "optional": false,
          "original": "¼ cup extra-virgin olive oil",
          "quantity": {
            "unit": "cup",
            "value": 0.25
          }
        },
        {
          "display": "1½ tbsp balsamic vinegar",
          "name": "balsamic vinegar",
          "optional": false,
          "original": "1½ tbsp balsamic vinegar",
          "quantity": {
            "unit": "tbsp",
            "value": 1.5
          }
        },
        {
          "display": "2 tsp sugar",
          "name": "sugar",
          "optional": false,
          "original": "2 tsp sugar",
          "quantity": {
            "unit": "tsp",
            "value": 2
          }
        },
        {
          "display": "1 tsp salt",
          "name": "salt",
          "optional": false,
          "original": "1 tsp salt",
          "quantity": {
            "unit": "tsp",
            "value": 1
          }
        },
        {
          "display": "½ tsp freshly ground black pepper",
          "name": "freshly ground black pepper",
          "optional": false,
          "original": "½ tsp freshly ground black pepper",
          "quantity": {
            "unit": "tsp",
            "value": 0.5
          }
        },
        {
          "display": "2 clove garlic (minced)",
          "name": "garlic",
          "note": "minced",
          "optional": false,
          "original": "2 clove garlic (minced)",
          "quantity": {
            "unit": "clove",
            "value": 2
          }
        }
      ],
      "tags": [
        "roasted cherry tomatoes"
      ],
      "text": {
        "ingredients": [
          "2 lb cherry tomatoes (3 pints)",
          "¼ cup extra-virgin olive oil",
          "1½ tbsp balsamic vinegar",
          "2 tsp sugar",
          "1 tsp salt",
          "½ tsp freshly ground black pepper",
          "2 clove garlic (minced)"
        ],
        "instructions": [
          "Preheat the oven to 275°F (135°C) and set an oven rack in the middle position. Line a baking sheet with wide heavy-duty aluminum foil.",
          "Directly on the lined baking sheet, using a rubber spatula, toss the tomatoes with the olive oil, vinegar, sugar, salt, pepper, and garlic. Roast for 2 hours, until the tomatoes are soft and beginning to burst. Serve hot or at room temperature."
        ]
      },
      "updatedAt": "2026-09-06T01:11:59.224Z",
      "url": "https://www.onceuponachef.com/recipes/slow-roasted-cherry-tomatoes.html"
    }
  ]
}
```

### find\_substitutions

Find substitutions

What to use instead of an ingredient: how much of each substitute to use for one unit of the original, how to handle it, and what it cannot be used for. Ingredients nothing is known to replace come back in unknown.

Parameters

* `ingredients`string\[\]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](https://www.tinyplates.dev/docs/api/substitutions) endpoint answers with.

`substitutions[]`object\[\]

`ingredient`string

The ingredient asked about, normalized.

`options`object\[\]

The substitutes, each with \`ingredient\`, \`ratio\` (how much to use for one unit of the original), an optional \`note\` on handling it, and an optional \`caution\` saying what it cannot be used for.

One entry per ingredient that has substitutions.

`unknown`string\[\]

The ingredients nothing is known to substitute for. Nothing is suggested for them.

Example response

```
{
  "substitutions": [
    {
      "ingredient": "butter",
      "options": [
        {
          "caution": "Not for creaming into a batter or for pastry, where solid fat is what makes the texture.",
          "ingredient": "olive oil",
          "note": "Use three quarters as much. The result is softer and does not brown the same way.",
          "ratio": 0.75
        },
        {
          "ingredient": "margarine",
          "note": "Use a block, not a spread: spreads carry more water.",
          "ratio": 1
        }
      ]
    }
  ],
  "unknown": [
    "saffron"
  ]
}
```

### get\_recipe

Get a recipe

Fetch one recipe in full — structured ingredients, numbered steps, times and nutrition — optionally scaled to a number of servings or converted to metric or imperial units.

Parameters

* `id`stringrequired  
The recipe id, from a search or list result.
* `servings`integer  
Rewrite every quantity for this many servings, 1–100.
* `units`string  
Convert the recipe to these units. One of: metric, imperial.

Returns

The JSON the [Get a recipe](https://www.tinyplates.dev/docs/api/get-recipe) endpoint answers with.

`conversion`objectoptional

`system`string

The system the recipe was rewritten in.

`unweighed`string\[\]

Ingredients measured by volume that could not be weighed, because no density is known for them. Their lines keep the unit the source wrote them in.

What the unit conversion did. Present only when \`units\` was given.

`nutritionTotals`objectoptional

`basisServings`number

The serving count perRecipe was multiplied up from: the label's own basis when the recipe declares one — a recipe stored as serving 8 to 10 can carry a label worked out on 10, not the stored 8 — otherwise the serving count the recipe had before any scaling.

`perRecipe`object

Nutrition for the whole recipe.

`perServing`object

Nutrition for one serving.

`servings`number

The serving count both figures were worked out from.

The same nutrition told twice: for one serving, which is what recipes are compared on, and for the whole recipe, which is what the cook is making. Present only when the recipe carries nutrition and says how many servings it makes; figures published per 100 g cannot be split this way and are left out. Scaling with \`servings\` changes the whole-recipe figures and leaves the per-serving ones alone.

`recipe`object

`allergens`objectoptional

`<allergen>`boolean

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

`disclaimer`string

The required informational-use warning.

Whether the recipe contains each EU and US regulated allergen: one true or false for each of the 16 allergen identifiers, keyed by identifier, beside the disclaimer. Informational only; verify product labels before serving someone with an allergy.

`author`objectoptional

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

`categories`string\[\]

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

`courses`string\[\]

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

`createdAt`string

When the recipe first entered the database. ISO 8601.

`cuisines`string\[\]

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

`description`stringoptional

The recipe’s own summary.

`dietary`objectoptional

Dietary flags, declared by the site or inferred from the required ingredients. A declared flag wins; a missing flag is unknown, and false is a known no. An inferred \`glutenFree\` or \`dairyFree\` can disagree with \`allergens\` by design: the diet reads the required ingredients, so a dish is gluten-free once the optional pita is left out, while the allergen block counts every line and stays cautious.

`equipment`string\[\]optional

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

`groups`string\[\]

The section headers of the recipe: the distinct \`group\` values of the ingredients and then the steps, in the order they first appear. Empty when the recipe has no sections.

`id`string

The recipe id.

`ingredients[]`object\[\]

`display`string

The line to render. Equal to the source line until the structure and the source part company — a converted unit, an amount enrichment filled in.

`group`stringoptional

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

`ingredientId`stringoptional

The canonical ingredient id, such as "chicken-thigh". Absent until the recipe has been enriched, or when the name could not be resolved. This is the value the \`ingredient\` filter of GET /recipes takes.

`localName`stringoptional

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

`localPreparation`stringoptional

How the ingredient is prepared, in the recipe’s own words, such as "finhackade" where \`preparation\` says "finely chopped". Absent on an English recipe, where \`preparation\` already is the reader’s, and on a line that says nothing of the kind. \`display\` is written with this one.

`name`string

The canonical English name.

`note`stringoptional

Anything the parser understood but could not place, such as "(400 g)". Kept as the source wrote it, in the recipe’s language, and never translated.

`optional`boolean

Whether the recipe marks this ingredient as optional.

`original`string

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

`preparation`stringoptional

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

`quantity`objectoptional

`max`numberoptional

The top of a range.

`unit`stringoptional

One of the units listed by GET /vocabularies.

`value`number

The amount itself.

The amount. A range such as "2-3 tomatoes" is a value of 2 with a max of 3\. A value with no unit is a count of pieces.

`size`stringoptional

A size qualifier, such as "large".

One ingredient line, parsed. \`original\` is the line the site published; \`display\` is the same line written back from these fields, in the recipe’s own language.

`instructions[]`object\[\]

`duration`objectoptional

`seconds`integer

Seconds.

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

`equipment`string\[\]optional

Equipment slugs the step calls for.

`group`stringoptional

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

`ingredients`string\[\]optional

Canonical ingredient ids the step uses.

`step`integer

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

`techniques`string\[\]optional

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

`temperature`objectoptional

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

`text`string

The step text.

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

`language`string

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

`media[]`object\[\]

`alt`stringoptional

Alternative text.

`caption`stringoptional

A caption published with the item.

`id`string

Unique within the recipe.

`role`string

Where the item sits in the recipe.

`step`integeroptional

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

`type`string

"image" or "video".

`url`string

The file itself.

`variants`object\[\]optional

The same photo in other sizes or crops. Images only.

Images and videos. An image carries a \`role\` of hero, gallery, step or thumbnail; a video carries gallery or step. A recipe has at most one hero image.

`notes`string\[\]optional

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

`nutrition`objectoptional

`basis`object

What the numbers are per. \`type\` is "serving", "recipe" or "100g"; \`servings\` is the serving count the site worked the numbers out on, which is not always the serving count the recipe is written for; \`description\` is the serving size the site named, such as "1 cup".

`calories`objectoptional

Energy, with its unit.

`carbohydrates`objectoptional

Carbohydrates.

`fat`objectoptional

Fat.

`fiber`objectoptional

Fibre.

`micronutrients`objectoptional

Anything else the source declared, keyed by nutrient slug.

`protein`objectoptional

Protein.

`saturatedFat`objectoptional

Saturated fat.

`sodium`objectoptional

Sodium.

`source`string

"provided": the site published these numbers itself, in the structured data the recipe was read from, so they are as current as the last read of that page.

`sugar`objectoptional

Sugar.

Nutrition as the site published it. \`basis\` says whether the numbers are per serving, per recipe or per 100 g. The API does not compute nutrition from the ingredients, so a recipe whose site publishes none has no nutrition object at all.

`rating`objectoptional

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

`servings`objectoptional

How much the recipe makes. "Serves 4-6" is a quantity of 4 with a max of 6; "Makes 24 cookies" is a quantity of 24 with a unit of "cookie".

`tags`string\[\]

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

`techniques`string\[\]optional

Techniques the recipe uses, as words rather than slugs.

`text`object

`ingredients`string\[\]

One line per ingredient.

`instructions`string\[\]

One line per step.

The recipe as plain lines: every ingredient’s \`display\` and every step’s \`text\`, in order. A convenience for rendering; nothing here is missing from the structured fields.

`times`object

`cook`objectoptional

`seconds`integer

Seconds.

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

`inactive`objectoptional

`seconds`integer

Seconds.

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

`prep`objectoptional

`seconds`integer

Seconds.

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

`total`objectoptional

`seconds`integer

Seconds.

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

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

`title`string

The recipe title.

`updatedAt`string

When the recipe was last written. ISO 8601.

`url`string

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

The recipe.

Example response

```
{
  "recipe": {
    "allergens": {
      "celery": false,
      "crustaceans": false,
      "eggs": false,
      "fish": false,
      "gluten-cereals": false,
      "lupin": false,
      "milk": true,
      "molluscs": false,
      "mustard": false,
      "nuts-eu": false,
      "peanuts": true,
      "sesame": false,
      "soy": false,
      "sulphites": false,
      "tree-nuts-us": false,
      "wheat": false,
      "disclaimer": "Informational only; not medical advice. Verify ingredients and product labels before serving someone with an allergy."
    },
    "id": "6a9820e58f8122ec891b68a3",
    "author": {
      "name": "Lindsay Ostrom",
      "url": "https://pinchofyum.com/about"
    },
    "description": "This peanut butter dark chocolate hummus is a sweet alternative to traditional hummus. Perfect served on graham crackers as an afternoon snack!",
    "instructions": [
      {
        "group": "Hummus",
        "step": 1,
        "text": "Blend everything through milk in a food processor."
      },
      {
        "group": "Hummus",
        "step": 2,
        "text": "Add flour by the spoonful and blend until desired consistency is reached."
      },
      {
        "step": 3,
        "text": "Stir in dark chocolate."
      },
      {
        "step": 4,
        "text": "Chill before serving."
      }
    ],
    "language": "en",
    "media": [
      {
        "id": "hero",
        "role": "hero",
        "type": "image",
        "url": "https://pinchofyum.com/tachyon/2011/05/Peanut-Butter-Dark-Chocolate-Hummus.jpeg?fit=225%2C225",
        "variants": [
          {
            "url": "https://pinchofyum.com/tachyon/2011/05/Peanut-Butter-Dark-Chocolate-Hummus.jpeg?fit=195%2C195"
          },
          {
            "url": "https://pinchofyum.com/tachyon/2011/05/Peanut-Butter-Dark-Chocolate-Hummus.jpeg?fit=180%2C180"
          },
          {
            "url": "https://pinchofyum.com/tachyon/2011/05/Peanut-Butter-Dark-Chocolate-Hummus.jpeg"
          }
        ]
      }
    ],
    "notes": [
      "Keeps in an airtight container in the fridge for up to five days.",
      "Swap the peanut butter for almond butter to make it peanut free."
    ],
    "nutrition": {
      "basis": {
        "description": "¼ cup",
        "servings": 8,
        "type": "serving"
      },
      "calories": {
        "unit": "kcal",
        "value": 201
      },
      "carbohydrates": {
        "unit": "g",
        "value": 29.4
      },
      "cholesterol": {
        "unit": "mg",
        "value": 0.8
      },
      "fat": {
        "unit": "g",
        "value": 7.4
      },
      "fiber": {
        "unit": "g",
        "value": 3.3
      },
      "micronutrients": {
        "trans-fat": {
          "unit": "g",
          "value": 0
        }
      },
      "protein": {
        "unit": "g",
        "value": 5.6
      },
      "saturatedFat": {
        "unit": "g",
        "value": 2.5
      },
      "sodium": {
        "unit": "mg",
        "value": 76
      },
      "source": "provided",
      "sugar": {
        "unit": "g",
        "value": 16.9
      }
    },
    "rating": {
      "count": 1,
      "reviewCount": 1,
      "value": 5
    },
    "servings": {
      "max": 8,
      "original": "6-8",
      "quantity": 6
    },
    "times": {
      "cook": {
        "seconds": 600
      },
      "prep": {
        "seconds": 300
      },
      "total": {
        "seconds": 900
      }
    },
    "title": "Peanut Butter Dark Chocolate Hummus",
    "categories": [],
    "courses": [
      "dessert"
    ],
    "createdAt": "2026-09-02T13:13:09.089Z",
    "cuisines": [
      "american"
    ],
    "groups": [
      "Hummus"
    ],
    "ingredients": [
      {
        "display": "1 can white beans or chickpeas, rinsed",
        "name": "white beans or chickpeas",
        "optional": false,
        "original": "1 can white beans or chickpeas, rinsed",
        "preparation": "rinsed",
        "quantity": {
          "unit": "can",
          "value": 1
        }
      },
      {
        "display": "¼ cup peanut butter",
        "name": "peanut butter",
        "optional": false,
        "original": "¼ cup peanut butter",
        "quantity": {
          "unit": "cup",
          "value": 0.25
        }
      },
      {
        "display": "2 tbsp caramel sauce",
        "name": "caramel sauce",
        "optional": false,
        "original": "2 tbsp caramel sauce",
        "quantity": {
          "unit": "tbsp",
          "value": 2
        }
      },
      {
        "display": "2 tbsp maple syrup",
        "name": "maple syrup",
        "optional": false,
        "original": "2 tbsp maple syrup",
        "quantity": {
          "unit": "tbsp",
          "value": 2
        }
      },
      {
        "display": "¼ cup brown sugar",
        "name": "brown sugar",
        "optional": false,
        "original": "¼ cup brown sugar",
        "quantity": {
          "unit": "cup",
          "value": 0.25
        }
      },
      {
        "display": "pinch of cinnamon",
        "name": "pinch of cinnamon",
        "optional": false,
        "original": "pinch of cinnamon"
      },
      {
        "display": "¼ cup milk",
        "name": "milk",
        "optional": false,
        "original": "¼ cup milk",
        "quantity": {
          "unit": "cup",
          "value": 0.25
        }
      },
      {
        "display": "¼ cup flour",
        "name": "flour",
        "optional": false,
        "original": "¼ cup flour",
        "quantity": {
          "unit": "cup",
          "value": 0.25
        }
      },
      {
        "display": "chopped dark chocolate",
        "name": "chopped dark chocolate",
        "optional": false,
        "original": "chopped dark chocolate"
      }
    ],
    "tags": [
      "chocolate hummus",
      "peanut butter hummus",
      "peanut butter chocolate",
      "hummus recipe",
      "dessert hummus"
    ],
    "text": {
      "ingredients": [
        "1 can white beans or chickpeas, rinsed",
        "¼ cup peanut butter",
        "2 tbsp caramel sauce",
        "2 tbsp maple syrup",
        "¼ cup brown sugar",
        "pinch of cinnamon",
        "¼ cup milk",
        "¼ cup flour",
        "chopped dark chocolate"
      ],
      "instructions": [
        "Blend everything through milk in a food processor.",
        "Add flour by the spoonful and blend until desired consistency is reached.",
        "Stir in dark chocolate.",
        "Chill before serving."
      ]
    },
    "updatedAt": "2026-09-06T01:11:59.223Z",
    "url": "https://pinchofyum.com/pb-dark-chocolate-hummus"
  }
}
```

### list\_ingredients

List ingredients

The canonical ingredient vocabulary, most used first. Its ids are what the ingredient filters take, and every spelling seen per language resolves to one of them.

Parameters

* `limit`integer  
How many results to return, 1–500\. Defaults to 100.

Returns

The JSON the [List ingredients](https://www.tinyplates.dev/docs/api/list-ingredients) endpoint answers with.

`ingredients[]`object\[\]

`aliases`object

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

`id`string

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

`names`object

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

`recipeCount`integer

How many recipes use this ingredient.

The ingredients, most used first.

Example response

```
{
  "ingredients": [
    {
      "aliases": {
        "en": [
          "salt",
          "sea salt",
          "kosher salt",
          "salt and black pepper",
          "salt and pepper"
        ],
        "de": [
          "Salz",
          "Jodsalz",
          "Bad Reichenhaller MarkenJodSalz mit Fluorid und Folsäure"
        ],
        "sv": [
          "salt",
          "salt och svartpeppar",
          "salt och peppar",
          "flingsalt"
        ],
        "es": [
          "sal",
          "Sal"
        ]
      },
      "id": "salt",
      "names": {
        "en": "salt"
      },
      "recipeCount": 783
    },
    {
      "aliases": {
        "en": [
          "black pepper",
          "freshly ground black pepper"
        ],
        "de": [
          "Pfeffer",
          "schwarzer Pfeffer",
          "frisch gemahlener Pfeffer",
          "gemahlener Pfeffer",
          "grober schwarzer Pfeffer"
        ],
        "sv": [
          "peppar",
          "svartpeppar",
          "nymalen svartpeppar",
          "malen vitpeppar",
          "svartpepparkorn"
        ],
        "es": [
          "pimienta",
          "pimienta negra molida",
          "Pimienta negra molida"
        ]
      },
      "id": "black-pepper",
      "names": {
        "en": "black pepper"
      },
      "recipeCount": 451
    },
    {
      "aliases": {
        "en": [
          "garlic",
          "garlic clove",
          "garlic cloves"
        ],
        "de": [
          "Knoblauchzehe",
          "Knoblauchzehen"
        ],
        "sv": [
          "vitlöksklyfta",
          "vitlöksklyftor",
          "vitlök"
        ],
        "es": [
          "Dientes de ajo",
          "ajo"
        ]
      },
      "id": "garlic",
      "names": {
        "en": "garlic"
      },
      "recipeCount": 411
    }
  ]
}
```

### list\_vocabularies

List vocabularies

The closed lists recipes are classified with: the cuisines, courses and diets find\_recipes accepts, EU and US regulated allergen features with their jurisdictions, and the units a quantity can carry.

Parameters

This tool takes no parameters.

Returns

The JSON the [Vocabularies](https://www.tinyplates.dev/docs/api/vocabularies) endpoint answers with.

`allergens`object\[\]

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

`courses`string\[\]

The values the \`course\` filter accepts.

`cuisines`string\[\]

The values the \`cuisine\` filter accepts.

`diets`string\[\]

The values the \`diet\` filter accepts.

`units`string\[\]

The units a quantity can carry.

Example response

```
{
  "allergens": [
    {
      "feature": "celery",
      "jurisdictions": [
        "eu"
      ]
    },
    {
      "feature": "crustaceans",
      "jurisdictions": [
        "eu",
        "us"
      ]
    },
    {
      "feature": "eggs",
      "jurisdictions": [
        "eu",
        "us"
      ]
    },
    {
      "feature": "fish",
      "jurisdictions": [
        "eu",
        "us"
      ]
    },
    {
      "feature": "gluten-cereals",
      "jurisdictions": [
        "eu"
      ]
    },
    {
      "feature": "lupin",
      "jurisdictions": [
        "eu"
      ]
    },
    {
      "feature": "milk",
      "jurisdictions": [
        "eu",
        "us"
      ]
    },
    {
      "feature": "molluscs",
      "jurisdictions": [
        "eu"
      ]
    },
    {
      "feature": "mustard",
      "jurisdictions": [
        "eu"
      ]
    },
    {
      "feature": "nuts-eu",
      "jurisdictions": [
        "eu"
      ]
    },
    {
      "feature": "peanuts",
      "jurisdictions": [
        "eu",
        "us"
      ]
    },
    {
      "feature": "sesame",
      "jurisdictions": [
        "eu",
        "us"
      ]
    },
    {
      "feature": "soy",
      "jurisdictions": [
        "eu",
        "us"
      ]
    },
    {
      "feature": "sulphites",
      "jurisdictions": [
        "eu"
      ]
    },
    {
      "feature": "tree-nuts-us",
      "jurisdictions": [
        "us"
      ]
    },
    {
      "feature": "wheat",
      "jurisdictions": [
        "us"
      ]
    }
  ],
  "courses": [
    "appetizer",
    "breakfast",
    "brunch",
    "dessert",
    "dinner",
    "drink",
    "lunch",
    "main-course",
    "side-dish",
    "snack"
  ],
  "cuisines": [
    "african",
    "american",
    "argentinian",
    "asian",
    "australian",
    "austrian",
    "belgian",
    "brazilian",
    "british",
    "cajun",
    "caribbean",
    "chinese",
    "cuban",
    "danish",
    "dutch",
    "eastern-european",
    "egyptian",
    "ethiopian",
    "filipino",
    "finnish",
    "french",
    "german",
    "greek",
    "hungarian",
    "indian",
    "indonesian",
    "iranian",
    "irish",
    "israeli",
    "italian",
    "jamaican",
    "japanese",
    "korean",
    "latin-american",
    "lebanese",
    "malaysian",
    "mediterranean",
    "mexican",
    "middle-eastern",
    "moroccan",
    "norwegian",
    "pakistani",
    "peruvian",
    "polish",
    "portuguese",
    "russian",
    "scandinavian",
    "southern-us",
    "spanish",
    "swedish",
    "swiss",
    "tex-mex",
    "thai",
    "turkish",
    "vietnamese"
  ],
  "diets": [
    "dairy-free",
    "gluten-free",
    "pescatarian",
    "vegan",
    "vegetarian"
  ],
  "units": [
    "g",
    "kg",
    "lb",
    "oz",
    "cl",
    "cup",
    "dl",
    "fl-oz",
    "gallon",
    "l",
    "ml",
    "pint",
    "quart",
    "tbsp",
    "tsp",
    "bag",
    "bottle",
    "box",
    "bunch",
    "can",
    "clove",
    "cube",
    "dash",
    "drop",
    "ear",
    "handful",
    "head",
    "jar",
    "knob",
    "leaf",
    "package",
    "packet",
    "piece",
    "pinch",
    "portion",
    "pot",
    "scoop",
    "sheet",
    "shot",
    "slice",
    "sprig",
    "stalk",
    "stick",
    "tub",
    "cm",
    "inch"
  ]
}
```

### popular\_recipes

Popular recipes

The best-loved recipes, ranked by rating and by how many people rated them.

Parameters

* `language`string  
Only recipes written in this language, as a two-letter ISO 639-1 code such as "en" or "sv".
* `limit`integer  
How many recipes to return, 1–5\. Defaults to 5.
* `offset`integer  
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](https://www.tinyplates.dev/docs/api/popular-recipes) endpoint answers with, 5 recipes at a time.

`pagination`object

`limit`integer

How many recipes this response holds. Capped at 100.

`offset`integer

How many were skipped.

`total`integer

How many match the filter in total.

Offset pagination.

`recipes[]`object\[\]

`allergens`objectoptional

`<allergen>`boolean

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

`disclaimer`string

The required informational-use warning.

Whether the recipe contains each EU and US regulated allergen: one true or false for each of the 16 allergen identifiers, keyed by identifier, beside the disclaimer. Informational only; verify product labels before serving someone with an allergy.

`author`objectoptional

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

`categories`string\[\]

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

`courses`string\[\]

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

`createdAt`string

When the recipe first entered the database. ISO 8601.

`cuisines`string\[\]

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

`description`stringoptional

The recipe’s own summary.

`dietary`objectoptional

Dietary flags, declared by the site or inferred from the required ingredients. A declared flag wins; a missing flag is unknown, and false is a known no. An inferred \`glutenFree\` or \`dairyFree\` can disagree with \`allergens\` by design: the diet reads the required ingredients, so a dish is gluten-free once the optional pita is left out, while the allergen block counts every line and stays cautious.

`equipment`string\[\]optional

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

`groups`string\[\]

The section headers of the recipe: the distinct \`group\` values of the ingredients and then the steps, in the order they first appear. Empty when the recipe has no sections.

`id`string

The recipe id.

`ingredients[]`object\[\]

`display`string

The line to render. Equal to the source line until the structure and the source part company — a converted unit, an amount enrichment filled in.

`group`stringoptional

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

`ingredientId`stringoptional

The canonical ingredient id, such as "chicken-thigh". Absent until the recipe has been enriched, or when the name could not be resolved. This is the value the \`ingredient\` filter of GET /recipes takes.

`localName`stringoptional

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

`localPreparation`stringoptional

How the ingredient is prepared, in the recipe’s own words, such as "finhackade" where \`preparation\` says "finely chopped". Absent on an English recipe, where \`preparation\` already is the reader’s, and on a line that says nothing of the kind. \`display\` is written with this one.

`name`string

The canonical English name.

`note`stringoptional

Anything the parser understood but could not place, such as "(400 g)". Kept as the source wrote it, in the recipe’s language, and never translated.

`optional`boolean

Whether the recipe marks this ingredient as optional.

`original`string

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

`preparation`stringoptional

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

`quantity`objectoptional

`max`numberoptional

The top of a range.

`unit`stringoptional

One of the units listed by GET /vocabularies.

`value`number

The amount itself.

The amount. A range such as "2-3 tomatoes" is a value of 2 with a max of 3\. A value with no unit is a count of pieces.

`size`stringoptional

A size qualifier, such as "large".

One ingredient line, parsed. \`original\` is the line the site published; \`display\` is the same line written back from these fields, in the recipe’s own language.

`instructions[]`object\[\]

`duration`objectoptional

`seconds`integer

Seconds.

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

`equipment`string\[\]optional

Equipment slugs the step calls for.

`group`stringoptional

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

`ingredients`string\[\]optional

Canonical ingredient ids the step uses.

`step`integer

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

`techniques`string\[\]optional

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

`temperature`objectoptional

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

`text`string

The step text.

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

`language`string

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

`media[]`object\[\]

`alt`stringoptional

Alternative text.

`caption`stringoptional

A caption published with the item.

`id`string

Unique within the recipe.

`role`string

Where the item sits in the recipe.

`step`integeroptional

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

`type`string

"image" or "video".

`url`string

The file itself.

`variants`object\[\]optional

The same photo in other sizes or crops. Images only.

Images and videos. An image carries a \`role\` of hero, gallery, step or thumbnail; a video carries gallery or step. A recipe has at most one hero image.

`notes`string\[\]optional

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

`nutrition`objectoptional

`basis`object

What the numbers are per. \`type\` is "serving", "recipe" or "100g"; \`servings\` is the serving count the site worked the numbers out on, which is not always the serving count the recipe is written for; \`description\` is the serving size the site named, such as "1 cup".

`calories`objectoptional

Energy, with its unit.

`carbohydrates`objectoptional

Carbohydrates.

`fat`objectoptional

Fat.

`fiber`objectoptional

Fibre.

`micronutrients`objectoptional

Anything else the source declared, keyed by nutrient slug.

`protein`objectoptional

Protein.

`saturatedFat`objectoptional

Saturated fat.

`sodium`objectoptional

Sodium.

`source`string

"provided": the site published these numbers itself, in the structured data the recipe was read from, so they are as current as the last read of that page.

`sugar`objectoptional

Sugar.

Nutrition as the site published it. \`basis\` says whether the numbers are per serving, per recipe or per 100 g. The API does not compute nutrition from the ingredients, so a recipe whose site publishes none has no nutrition object at all.

`rating`objectoptional

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

`servings`objectoptional

How much the recipe makes. "Serves 4-6" is a quantity of 4 with a max of 6; "Makes 24 cookies" is a quantity of 24 with a unit of "cookie".

`tags`string\[\]

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

`techniques`string\[\]optional

Techniques the recipe uses, as words rather than slugs.

`text`object

`ingredients`string\[\]

One line per ingredient.

`instructions`string\[\]

One line per step.

The recipe as plain lines: every ingredient’s \`display\` and every step’s \`text\`, in order. A convenience for rendering; nothing here is missing from the structured fields.

`times`object

`cook`objectoptional

`seconds`integer

Seconds.

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

`inactive`objectoptional

`seconds`integer

Seconds.

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

`prep`objectoptional

`seconds`integer

Seconds.

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

`total`objectoptional

`seconds`integer

Seconds.

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

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

`title`string

The recipe title.

`updatedAt`string

When the recipe was last written. ISO 8601.

`url`string

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

`popularityScore`number

How popular this recipe is relative to the others in this response. Higher comes first.

The recipes, most popular first.

Example response

```
{
  "pagination": {
    "limit": 1,
    "offset": 0,
    "total": 1848
  },
  "recipes": [
    {
      "id": "6a9820a88f8122ec891b680b",
      "description": "No canning, no fuss—just crisp, tangy pickles you’ll want to eat with everything!",
      "instructions": [
        {
          "step": 1,
          "text": "Combine the vinegar, salt and sugar in a small non-reactive saucepan (such as stainless steel, glass, ceramic or teflon) over high heat. Whisk until the salt and sugar are dissolved. Transfer the liquid into a bowl and whisk in the cold water. Refrigerate brine until ready to use."
        },
        {
          "step": 2,
          "text": "Stuff the cucumbers into two clean 1 qt (1L) jars. Add the coriander seeds, garlic cloves, mustard seeds, red pepper flakes, dill sprigs, and chilled brine into jars, dividing evenly. If necessary, add a bit of cold water to the jars until the brine covers the cucumbers. Cover and refrigerate about 24 hours, then serve. The pickles will keep in the refrigerator for up to one month."
        }
      ],
      "language": "en",
      "media": [
        {
          "id": "hero",
          "role": "hero",
          "type": "image",
          "url": "https://www.onceuponachef.com/images/2012/04/pickles.jpg",
          "variants": [
            {
              "url": "https://www.onceuponachef.com/images/2012/04/pickles-500x500.jpg"
            },
            {
              "url": "https://www.onceuponachef.com/images/2012/04/pickles-500x375.jpg"
            },
            {
              "url": "https://www.onceuponachef.com/images/2012/04/pickles-480x270.jpg"
            }
          ]
        }
      ],
      "rating": {
        "count": 517,
        "reviewCount": 11,
        "value": 4.93
      },
      "servings": {
        "original": "2 (1-qt) jars (about 24 spears)",
        "quantity": 2
      },
      "times": {
        "cook": {
          "seconds": 300
        },
        "prep": {
          "seconds": 900
        },
        "total": {
          "seconds": 1200
        }
      },
      "title": "Quick & Easy Refrigerator Pickles",
      "categories": [],
      "courses": [
        "snack"
      ],
      "createdAt": "2026-09-02T13:12:08.379Z",
      "cuisines": [
        "american"
      ],
      "groups": [],
      "ingredients": [
        {
          "display": "1¼ cup distilled white vinegar (5% acidity)",
          "name": "distilled white vinegar",
          "note": "5% acidity",
          "optional": false,
          "original": "1¼ cup distilled white vinegar (5% acidity)",
          "quantity": {
            "unit": "cup",
            "value": 1.25
          }
        },
        {
          "display": "3 tbsp kosher salt",
          "name": "kosher salt",
          "optional": false,
          "original": "3 tbsp kosher salt",
          "quantity": {
            "unit": "tbsp",
            "value": 3
          }
        },
        {
          "display": "2 tbsp sugar",
          "name": "sugar",
          "optional": false,
          "original": "2 tbsp sugar",
          "quantity": {
            "unit": "tbsp",
            "value": 2
          }
        },
        {
          "display": "2 cup cold water",
          "name": "cold water",
          "optional": false,
          "original": "2 cup cold water",
          "quantity": {
            "unit": "cup",
            "value": 2
          }
        },
        {
          "display": "1¾-2 lb Kirby cucumbers, cut into halves or spears (about 6)",
          "name": "Kirby cucumbers",
          "note": "about 6",
          "optional": false,
          "original": "1¾-2 lb Kirby cucumbers, cut into halves or spears (about 6)",
          "preparation": "cut into halves or spears",
          "quantity": {
            "max": 2,
            "unit": "lb",
            "value": 1.75
          }
        },
        {
          "display": "2 tbsp coriander seeds",
          "name": "coriander seeds",
          "optional": false,
          "original": "2 tbsp coriander seeds",
          "quantity": {
            "unit": "tbsp",
            "value": 2
          }
        },
        {
          "display": "6 large garlic cloves (peeled and halved)",
          "name": "garlic cloves",
          "note": "peeled and halved",
          "optional": false,
          "original": "6 large garlic cloves (peeled and halved)",
          "quantity": {
            "value": 6
          },
          "size": "large"
        },
        {
          "display": "1 tsp mustard seeds",
          "name": "mustard seeds",
          "optional": false,
          "original": "1 tsp mustard seeds",
          "quantity": {
            "unit": "tsp",
            "value": 1
          }
        },
        {
          "display": "¼ tsp crushed red pepper flakes",
          "name": "crushed red pepper flakes",
          "optional": false,
          "original": "¼ tsp crushed red pepper flakes",
          "quantity": {
            "unit": "tsp",
            "value": 0.25
          }
        },
        {
          "display": "16 dill sprigs",
          "name": "dill sprigs",
          "optional": false,
          "original": "16 dill sprigs",
          "quantity": {
            "value": 16
          }
        }
      ],
      "tags": [
        "pickles"
      ],
      "text": {
        "ingredients": [
          "1¼ cup distilled white vinegar (5% acidity)",
          "3 tbsp kosher salt",
          "2 tbsp sugar",
          "2 cup cold water",
          "1¾-2 lb Kirby cucumbers, cut into halves or spears (about 6)",
          "2 tbsp coriander seeds",
          "6 large garlic cloves (peeled and halved)",
          "1 tsp mustard seeds",
          "¼ tsp crushed red pepper flakes",
          "16 dill sprigs"
        ],
        "instructions": [
          "Combine the vinegar, salt and sugar in a small non-reactive saucepan (such as stainless steel, glass, ceramic or teflon) over high heat. Whisk until the salt and sugar are dissolved. Transfer the liquid into a bowl and whisk in the cold water. Refrigerate brine until ready to use.",
          "Stuff the cucumbers into two clean 1 qt (1L) jars. Add the coriander seeds, garlic cloves, mustard seeds, red pepper flakes, dill sprigs, and chilled brine into jars, dividing evenly. If necessary, add a bit of cold water to the jars until the brine covers the cucumbers. Cover and refrigerate about 24 hours, then serve. The pickles will keep in the refrigerator for up to one month."
        ]
      },
      "updatedAt": "2026-09-06T01:11:59.030Z",
      "url": "https://www.onceuponachef.com/recipes/quick-and-easy-dill-pickles.html",
      "popularityScore": 4.89536312849162
    }
  ]
}
```

### search\_recipes

Search recipes

Search recipes by meaning as well as wording across names, ingredients and descriptions, so "creamy pasta" also finds carbonara. Best matches first.

Parameters

* `fields`string\[\]  
Only return these recipe fields, such as "title", "url" and "times", to keep results small. id and score are always included.
* `language`string  
Only recipes written in this language, as a two-letter ISO 639-1 code such as "en" or "sv".
* `limit`integer  
How many recipes to return, 1–5\. Defaults to 5.
* `query`stringrequired  
What to search for.
* `without`string\[\]  
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](https://www.tinyplates.dev/docs/api/search-recipes) endpoint answers with, 5 recipes at a time.

`results[]`object\[\]

`allergens`objectoptional

`<allergen>`boolean

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

`disclaimer`string

The required informational-use warning.

Whether the recipe contains each EU and US regulated allergen: one true or false for each of the 16 allergen identifiers, keyed by identifier, beside the disclaimer. Informational only; verify product labels before serving someone with an allergy.

`author`objectoptional

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

`categories`string\[\]

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

`courses`string\[\]

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

`createdAt`string

When the recipe first entered the database. ISO 8601.

`cuisines`string\[\]

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

`description`stringoptional

The recipe’s own summary.

`dietary`objectoptional

Dietary flags, declared by the site or inferred from the required ingredients. A declared flag wins; a missing flag is unknown, and false is a known no. An inferred \`glutenFree\` or \`dairyFree\` can disagree with \`allergens\` by design: the diet reads the required ingredients, so a dish is gluten-free once the optional pita is left out, while the allergen block counts every line and stays cautious.

`equipment`string\[\]optional

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

`groups`string\[\]

The section headers of the recipe: the distinct \`group\` values of the ingredients and then the steps, in the order they first appear. Empty when the recipe has no sections.

`id`string

The recipe id.

`ingredients[]`object\[\]

`display`string

The line to render. Equal to the source line until the structure and the source part company — a converted unit, an amount enrichment filled in.

`group`stringoptional

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

`ingredientId`stringoptional

The canonical ingredient id, such as "chicken-thigh". Absent until the recipe has been enriched, or when the name could not be resolved. This is the value the \`ingredient\` filter of GET /recipes takes.

`localName`stringoptional

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

`localPreparation`stringoptional

How the ingredient is prepared, in the recipe’s own words, such as "finhackade" where \`preparation\` says "finely chopped". Absent on an English recipe, where \`preparation\` already is the reader’s, and on a line that says nothing of the kind. \`display\` is written with this one.

`name`string

The canonical English name.

`note`stringoptional

Anything the parser understood but could not place, such as "(400 g)". Kept as the source wrote it, in the recipe’s language, and never translated.

`optional`boolean

Whether the recipe marks this ingredient as optional.

`original`string

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

`preparation`stringoptional

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

`quantity`objectoptional

`max`numberoptional

The top of a range.

`unit`stringoptional

One of the units listed by GET /vocabularies.

`value`number

The amount itself.

The amount. A range such as "2-3 tomatoes" is a value of 2 with a max of 3\. A value with no unit is a count of pieces.

`size`stringoptional

A size qualifier, such as "large".

One ingredient line, parsed. \`original\` is the line the site published; \`display\` is the same line written back from these fields, in the recipe’s own language.

`instructions[]`object\[\]

`duration`objectoptional

`seconds`integer

Seconds.

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

`equipment`string\[\]optional

Equipment slugs the step calls for.

`group`stringoptional

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

`ingredients`string\[\]optional

Canonical ingredient ids the step uses.

`step`integer

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

`techniques`string\[\]optional

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

`temperature`objectoptional

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

`text`string

The step text.

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

`language`string

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

`media[]`object\[\]

`alt`stringoptional

Alternative text.

`caption`stringoptional

A caption published with the item.

`id`string

Unique within the recipe.

`role`string

Where the item sits in the recipe.

`step`integeroptional

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

`type`string

"image" or "video".

`url`string

The file itself.

`variants`object\[\]optional

The same photo in other sizes or crops. Images only.

Images and videos. An image carries a \`role\` of hero, gallery, step or thumbnail; a video carries gallery or step. A recipe has at most one hero image.

`notes`string\[\]optional

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

`nutrition`objectoptional

`basis`object

What the numbers are per. \`type\` is "serving", "recipe" or "100g"; \`servings\` is the serving count the site worked the numbers out on, which is not always the serving count the recipe is written for; \`description\` is the serving size the site named, such as "1 cup".

`calories`objectoptional

Energy, with its unit.

`carbohydrates`objectoptional

Carbohydrates.

`fat`objectoptional

Fat.

`fiber`objectoptional

Fibre.

`micronutrients`objectoptional

Anything else the source declared, keyed by nutrient slug.

`protein`objectoptional

Protein.

`saturatedFat`objectoptional

Saturated fat.

`sodium`objectoptional

Sodium.

`source`string

"provided": the site published these numbers itself, in the structured data the recipe was read from, so they are as current as the last read of that page.

`sugar`objectoptional

Sugar.

Nutrition as the site published it. \`basis\` says whether the numbers are per serving, per recipe or per 100 g. The API does not compute nutrition from the ingredients, so a recipe whose site publishes none has no nutrition object at all.

`rating`objectoptional

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

`servings`objectoptional

How much the recipe makes. "Serves 4-6" is a quantity of 4 with a max of 6; "Makes 24 cookies" is a quantity of 24 with a unit of "cookie".

`tags`string\[\]

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

`techniques`string\[\]optional

Techniques the recipe uses, as words rather than slugs.

`text`object

`ingredients`string\[\]

One line per ingredient.

`instructions`string\[\]

One line per step.

The recipe as plain lines: every ingredient’s \`display\` and every step’s \`text\`, in order. A convenience for rendering; nothing here is missing from the structured fields.

`times`object

`cook`objectoptional

`seconds`integer

Seconds.

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

`inactive`objectoptional

`seconds`integer

Seconds.

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

`prep`objectoptional

`seconds`integer

Seconds.

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

`total`objectoptional

`seconds`integer

Seconds.

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

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

`title`string

The recipe title.

`updatedAt`string

When the recipe was last written. ISO 8601.

`url`string

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

`score`number

A rank fusion of the meaning and the wording legs of the search, plus a bonus for a title that contains the query. Higher comes first. It is a rank, not a confidence: scores are comparable only within one response.

The matching recipes, best first. When \`fields\` is set, only the requested fields plus \`id\` and \`score\` are present.

Example response

```
{
  "results": [
    {
      "id": "6a980d75ea7517554c2894b1",
      "allergens": {
        "celery": false,
        "crustaceans": false,
        "eggs": false,
        "fish": false,
        "gluten-cereals": false,
        "lupin": false,
        "milk": true,
        "molluscs": false,
        "mustard": false,
        "nuts-eu": false,
        "peanuts": true,
        "sesame": false,
        "soy": false,
        "sulphites": false,
        "tree-nuts-us": false,
        "wheat": false,
        "disclaimer": "Informational only; not medical advice. Verify ingredients and product labels before serving someone with an allergy."
      },
      "createdAt": "2026-09-02T11:50:13.886Z",
      "dietary": {
        "glutenFree": true,
        "vegetarian": true
      },
      "instructions": [
        {
          "equipment": [
            "oven"
          ],
          "step": 1,
          "temperature": {
            "unit": "F",
            "value": 325
          },
          "text": "Preheat oven to 325°."
        },
        {
          "ingredients": [
            "roma-tomato"
          ],
          "step": 2,
          "techniques": [
            "slicing"
          ],
          "text": "Slice tomatoes in half."
        },
        {
          "ingredients": [
            "salt",
            "basil",
            "oregano",
            "thyme"
          ],
          "step": 3,
          "techniques": [
            "seasoning"
          ],
          "text": "Season with salt, basil, oregano and thyme."
        },
        {
          "equipment": [
            "baking-sheet"
          ],
          "ingredients": [
            "olive-oil",
            "roma-tomato"
          ],
          "step": 4,
          "techniques": [
            "spraying"
          ],
          "text": "Spray a cookie sheet with olive oil spray and place tomatoes cut side up."
        },
        {
          "duration": {
            "seconds": 7200
          },
          "equipment": [
            "oven"
          ],
          "ingredients": [
            "roma-tomato"
          ],
          "step": 5,
          "techniques": [
            "baking"
          ],
          "text": "Bake 2 hrs until skin gets wrinkled and crusty on the bottom and moist in the center."
        },
        {
          "equipment": [
            "food-processor"
          ],
          "ingredients": [
            "roma-tomato"
          ],
          "step": 6,
          "techniques": [
            "pureeing"
          ],
          "text": "Puree the tomatoes in a food processor."
        },
        {
          "step": 7,
          "text": "If it is too thick, you can thin with pasta water."
        },
        {
          "ingredients": [
            "roma-tomato"
          ],
          "step": 8,
          "text": "Serve over your favorite high fiber pasta and grated cheese."
        }
      ],
      "language": "en",
      "media": [
        {
          "id": "hero",
          "role": "hero",
          "type": "image",
          "url": "https://www.skinnytaste.com/wp-content/uploads/2008/08/roasted-tomatoe-sauce.jpg",
          "variants": [
            {
              "url": "https://www.skinnytaste.com/wp-content/uploads/2008/08/roasted-tomatoe-sauce-425x270.jpg"
            }
          ]
        }
      ],
      "nutrition": {
        "basis": {
          "type": "serving"
        },
        "calories": {
          "unit": "kcal",
          "value": 78.1
        },
        "carbohydrates": {
          "unit": "g",
          "value": 17.3
        },
        "fat": {
          "unit": "g",
          "value": 1.2
        },
        "fiber": {
          "unit": "g",
          "value": 4.1
        },
        "protein": {
          "unit": "g",
          "value": 3.2
        },
        "source": "provided"
      },
      "rating": {
        "count": 1,
        "reviewCount": 1,
        "value": 5
      },
      "servings": {
        "original": "4 servings",
        "quantity": 4
      },
      "times": {},
      "title": "Candied Tomato Sauce",
      "updatedAt": "2026-09-06T01:39:14.527Z",
      "categories": [],
      "courses": [],
      "cuisines": [
        "italian"
      ],
      "groups": [],
      "ingredients": [
        {
          "display": "12 ripe Roma tomatoes",
          "localName": "Roma tomatoes",
          "ingredientId": "roma-tomato",
          "name": "Roma tomato",
          "optional": false,
          "original": "12 ripe Roma tomatoes",
          "quantity": {
            "value": 12
          },
          "size": "ripe"
        },
        {
          "display": "salt",
          "localName": "salt",
          "ingredientId": "salt",
          "name": "salt",
          "note": "to taste",
          "optional": false,
          "original": "salt to taste"
        },
        {
          "display": "1 tsp thyme",
          "localName": "thyme",
          "ingredientId": "thyme",
          "name": "thyme",
          "optional": false,
          "original": "1 tsp thyme",
          "quantity": {
            "unit": "tsp",
            "value": 1
          }
        },
        {
          "display": "1 tsp oregano",
          "localName": "oregano",
          "ingredientId": "oregano",
          "name": "oregano",
          "optional": false,
          "original": "1 tsp oregano",
          "quantity": {
            "unit": "tsp",
            "value": 1
          }
        },
        {
          "display": "olive oil spray",
          "localName": "olive oil",
          "ingredientId": "olive-oil",
          "name": "olive oil",
          "optional": false,
          "original": "olive oil spray",
          "preparation": "spray"
        },
        {
          "display": "2 tbsp basil, chopped",
          "localName": "basil",
          "ingredientId": "basil",
          "name": "basil",
          "optional": false,
          "original": "2 tbsp basil, chopped",
          "preparation": "chopped",
          "quantity": {
            "unit": "tbsp",
            "value": 2
          }
        }
      ],
      "tags": [
        "freezer meals",
        "gluten free",
        "vegetarian meals"
      ],
      "text": {
        "ingredients": [
          "12 ripe Roma tomatoes",
          "salt",
          "1 tsp thyme",
          "1 tsp oregano",
          "olive oil spray",
          "2 tbsp basil, chopped"
        ],
        "instructions": [
          "Preheat oven to 325°.",
          "Slice tomatoes in half.",
          "Season with salt, basil, oregano and thyme.",
          "Spray a cookie sheet with olive oil spray and place tomatoes cut side up.",
          "Bake 2 hrs until skin gets wrinkled and crusty on the bottom and moist in the center.",
          "Puree the tomatoes in a food processor.",
          "If it is too thick, you can thin with pasta water.",
          "Serve over your favorite high fiber pasta and grated cheese."
        ]
      },
      "url": "https://www.skinnytaste.com/candied-tomato-sauce-0-ww-pts/",
      "equipment": [
        "baking sheet",
        "food processor",
        "oven"
      ],
      "techniques": [
        "baking",
        "pureeing",
        "seasoning",
        "slicing",
        "spraying"
      ],
      "score": 0.0333
    }
  ]
}
```