The recipe object

Recipes are scraped from sites that publish them however they like, then normalized into one object. This is that object.

One shape, everywhere

GET /recipes, GET /recipes/{id}, GET /search and GET /popular all return it. Search adds a score, popular adds a popularityScore; nothing else differs.

Reading a recipe

There are two ways in, and they hold the same content.

Structured. ingredients is parsed into quantities, units, names and preparation; instructions is numbered steps. Use this to compute with — scaling, shopping lists, filtering.
Flat. text.ingredients and text.instructions are plain lines, in order, ready to render. Use this to display.

An ingredient's display is the line to show. It is written back from the structured fields in the recipe's own language, so a Swedish recipe stays Swedish even though name and ingredientId are canonical English. That is what makes “tomat”, “Tomate” and “tomato” groupable without translating anyone's recipe.

Every duration is { seconds } — never “1 hr 20 mins”. Format it yourself and you can format it in any language.

Absent means unknown

An optional field that is missing means the source did not say, not that the answer is zero or false. This matters most for dietary: vegan: false is a known no, while no vegan key at all means nobody has established it. Its source tells you whether the site declared the flags or the pipeline inferred them from the ingredients.

The same is true of nutrition, whose source is provided or calculated, and whose basis says whether the numbers are per serving, per recipe or per 100 g. Do not compare two recipes' nutrition without checking both.

Every field

allergensstring[]optional

EU-declarable allergens found in the recipe, from the list served by GET /vocabularies.

authorobjectoptional

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

categoriesstring[]

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

coursesstring[]

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

createdAtstring

When the recipe first entered the database. ISO 8601.

cuisinesstring[]

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

descriptionstringoptional

The recipe’s own summary.

dietaryobjectoptional

Dietary flags. A missing flag is unknown; false is a known no. `source` says whether the site declared them or the pipeline inferred them from the ingredients.

equipmentstring[]optional

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

idstring

The recipe id.

One ingredient line, parsed. The source line is not returned; `display` is the line written back from these fields, in the recipe’s own language.

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

languagestring

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

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.

Nutrition, either as the site published it or calculated from the ingredients — `source` says which. `basis` says whether the numbers are per serving, per recipe or per 100 g.

ratingobjectoptional

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

servingsobjectoptional

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

tagsstring[]

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

techniquesstring[]optional

Techniques the recipe uses, as words rather than slugs.

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.

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

titlestring

The recipe title.

updatedAtstring

When the recipe was last written. ISO 8601.

urlstring

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

A whole recipe

A real response from GET /recipes/{id}.

{
  "recipe": {
    "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": [
      {
        "step": 1,
        "text": "Blend everything through milk in a food processor."
      },
      {
        "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"
          }
        ]
      }
    ],
    "nutrition": {
      "basis": {
        "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"
    ],
    "ingredients": [
      {
        "display": "1 can white beans or chickpeas, rinsed",
        "name": "white beans or chickpeas",
        "optional": false,
        "preparation": "rinsed",
        "quantity": {
          "unit": "can",
          "value": 1
        }
      },
      {
        "display": "¼ cup peanut butter",
        "name": "peanut butter",
        "optional": false,
        "quantity": {
          "unit": "cup",
          "value": 0.25
        }
      },
      {
        "display": "2 tbsp caramel sauce",
        "name": "caramel sauce",
        "optional": false,
        "quantity": {
          "unit": "tbsp",
          "value": 2
        }
      },
      {
        "display": "2 tbsp maple syrup",
        "name": "maple syrup",
        "optional": false,
        "quantity": {
          "unit": "tbsp",
          "value": 2
        }
      },
      {
        "display": "¼ cup brown sugar",
        "name": "brown sugar",
        "optional": false,
        "quantity": {
          "unit": "cup",
          "value": 0.25
        }
      },
      {
        "display": "pinch of cinnamon",
        "name": "pinch of cinnamon",
        "optional": false
      },
      {
        "display": "¼ cup milk",
        "name": "milk",
        "optional": false,
        "quantity": {
          "unit": "cup",
          "value": 0.25
        }
      },
      {
        "display": "¼ cup flour",
        "name": "flour",
        "optional": false,
        "quantity": {
          "unit": "cup",
          "value": 0.25
        }
      },
      {
        "display": "chopped dark chocolate",
        "name": "chopped dark chocolate",
        "optional": false
      }
    ],
    "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"
  }
}