Skip to main content
POST
/
api
/
parseRecipe
Parse Recipe from URL
curl --request POST \
  --url https://api.example.com/api/parseRecipe \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "<string>"
}
'
{
  "success": true,
  "title": "<string>",
  "ingredients": [
    {
      "groupName": "<string>",
      "ingredients": [
        {
          "amount": "<string>",
          "units": "<string>",
          "ingredient": "<string>"
        }
      ]
    }
  ],
  "instructions": [
    {}
  ],
  "author": "<string>",
  "sourceUrl": "<string>",
  "summary": "<string>",
  "cuisine": [
    {}
  ],
  "servings": "<string>",
  "prepTimeMinutes": 123,
  "cookTimeMinutes": 123,
  "totalTimeMinutes": 123,
  "storageGuide": "<string>",
  "shelfLife": {
    "fridge": 123,
    "freezer": 123
  },
  "platingNotes": "<string>",
  "servingVessel": "<string>",
  "servingTemp": "<string>",
  "method": "<string>",
  "error": {
    "code": "<string>",
    "message": "<string>",
    "retryAfter": 123
  }
}

​
Overview

The /api/parseRecipe endpoint provides a unified interface for parsing recipes from any website. It uses a two-layer approach:
  1. JSON-LD structured data extraction (fast, reliable, no AI tokens used)
  2. AI-based parsing of cleaned HTML (fallback when structured data is not available)
This endpoint works with any recipe website and eliminates the need for site-specific HTML selectors.

​
Request

​
url
string
required
The full URL of the recipe page to parse. Must be a valid HTTP/HTTPS URL.Example: https://example.com/recipe/chocolate-cake

​
Response

​
Success Response

​
success
boolean
required
Always true for successful responses
​
title
string
required
The recipe title
​
ingredients
array
required
Array of ingredient groups. Each group contains a groupName and an array of ingredients.
​
instructions
array
required
Array of cooking instruction steps as strings
​
author
string
Recipe author name (if available)
​
sourceUrl
string
Original source URL of the recipe
​
summary
string
AI-generated recipe summary (if available)
​
cuisine
array
Array of cuisine tags (e.g., ["Italian", "Mediterranean"])
​
servings
string
Number of servings or yield (e.g., “4 servings”, “12 cookies”)
​
prepTimeMinutes
number
Preparation time in minutes
​
cookTimeMinutes
number
Cooking time in minutes
​
totalTimeMinutes
number
Total time in minutes (prep + cook)
​
storageGuide
string
Storage instructions for leftovers
​
shelfLife
object
Shelf life information
​
platingNotes
string
Plating and presentation suggestions
​
servingVessel
string
Recommended serving vessel (e.g., “shallow bowl”, “dinner plate”)
​
servingTemp
string
Ideal serving temperature (e.g., “hot”, “warm”, “chilled”)
​
method
string
required
Parsing method used: "json-ld" (structured data) or "ai" (AI extraction)

​
Error Response

​
success
boolean
Always false for error responses
​
error
object
Error details

​
Error Codes

​
ERR_INVALID_URL
The provided URL is invalid or malformed
​
ERR_FETCH_FAILED
Could not connect to the recipe website
​
ERR_NO_RECIPE_FOUND
No recipe content found on the page
​
ERR_RATE_LIMIT
Too many requests - rate limit exceeded
​
ERR_API_UNAVAILABLE
Service temporarily unavailable
​
ERR_TIMEOUT
Request timed out
​
ERR_UNKNOWN
An unexpected error occurred

​
Examples

curl -X POST https://your-domain.com/api/parseRecipe \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.allrecipes.com/recipe/10813/best-chocolate-chip-cookies/"
  }'

​
Success Response Example

{
  "success": true,
  "title": "Best Chocolate Chip Cookies",
  "ingredients": [
    {
      "groupName": "Main ingredients",
      "ingredients": [
        {
          "amount": "2 1/4",
          "units": "cups",
          "ingredient": "all-purpose flour"
        },
        {
          "amount": "1",
          "units": "cup",
          "ingredient": "unsalted butter, softened"
        },
        {
          "amount": "2",
          "units": "large",
          "ingredient": "eggs"
        }
      ]
    }
  ],
  "instructions": [
    "Preheat oven to 375°F (190°C).",
    "In a large bowl, cream together butter and sugars until light and fluffy.",
    "Beat in eggs one at a time, then stir in vanilla."
  ],
  "author": "Chef John",
  "servings": "48 cookies",
  "prepTimeMinutes": 15,
  "cookTimeMinutes": 10,
  "totalTimeMinutes": 25,
  "cuisine": ["American"],
  "method": "json-ld"
}

​
Error Response Example

{
  "success": false,
  "error": {
    "code": "ERR_NO_RECIPE_FOUND",
    "message": "No complete recipe content found on this page"
  }
}
Rate limits may apply to this endpoint. If you receive an ERR_RATE_LIMIT error, check the retryAfter timestamp to know when you can retry.

Build docs developers (and LLMs) love

Get started for freeTalk to us