Recipes

List Recipes

GET /api/v1/recipes

Returns a paginated list of recipes. Supports search, filtering, sorting, and ingredient search.

Query Parameters

Parameter	Type	Description
`lang`	string	PaidResponse language (`en`, `fr`, `es`). Defaults to `en`.
`servings`	integer	PaidScale ingredient quantities to this number of servings (1 to 100). See Servings & Units.
`units`	string	PaidUnit system for ingredient quantities: `metric` (default) or `imperial`.
`search`	string	Search recipes by name (case-insensitive). Searches in the requested language with English fallback.
`search_in`	string	Where to search: `name` (default), `description`, or `both`
`ingredients`	string	Filter by ingredients: comma-separated names (case-insensitive partial match). When set without an explicit `sort`, results are ordered by the number of matching ingredients (most matches first).
`cuisine`	string	Filter by cuisine (e.g. `italian`, `french`, `asian`)
`meal_type`	string	Filter by meal type (e.g. `main`, `dessert`, `starter`)
`difficulty`	string	Filter by difficulty (`easy`, `medium`, `hard`)
`dietary_tags`	string	Filter by dietary tags (e.g. `vegetarian`, `vegan`, `gluten_free`). Currently supports a single value only; multiple values coming soon.
`prep_time_min`	integer	Minimum preparation time (minutes)
`prep_time_max`	integer	Maximum preparation time (minutes)
`cook_time_min`	integer	Minimum cooking time (minutes)
`cook_time_max`	integer	Maximum cooking time (minutes)
`calories_per_serving_min`	integer	Minimum calories per serving
`calories_per_serving_max`	integer	Maximum calories per serving
`protein_min`	integer	Minimum protein (grams)
`protein_max`	integer	Maximum protein (grams)
`sort`	string	Sort field: `name`, `prep_time`, `cook_time`, `calories_per_serving`, `protein` (default: `name`)
`order`	string	Sort order: `asc` or `desc` (default: `asc`)
`per_page`	integer	Items per page (default: 10, max depends on your plan)
`page`	integer	Page number (default: 1)

Enum Values

Cuisine

american, chinese, french, greek, italian, japanese, mexican, portuguese, spanish, thai, turkish

Meal Type

starter, main, dessert, appetizer, breakfast, brunch, snack, side_dish, soup, drink, sauce

Difficulty

easy, medium, hard

Dietary Tags

vegetarian, vegan, gluten_free, dairy_free, nut_free, halal, kosher

note

The dietary_tags filter currently accepts a single value only (e.g. dietary_tags=vegan). Support for filtering by multiple values is coming soon.

Example Request

curl "https://recipeapi.io/api/v1/recipes?cuisine=italian&difficulty=easy&per_page=5" \
  -H "Authorization: Bearer sk_live_..."

const API_KEY = "sk_live_...";

const response = await fetch(
    "https://recipeapi.io/api/v1/recipes?cuisine=italian&difficulty=easy&per_page=5",
    {headers: {"Authorization": `Bearer ${API_KEY}`}}
);

const data = await response.json();
console.log(data);

import requests

API_KEY = "sk_live_..."

response = requests.get(
    "https://recipeapi.io/api/v1/recipes",
    params={"cuisine": "italian", "difficulty": "easy", "per_page": 5},
    headers={"Authorization": f"Bearer {API_KEY}"}
)

data = response.json()
print(data)

// composer require guzzlehttp/guzzle

const API_KEY = 'sk_live_...';

$client = new GuzzleHttp\Client();
$response = $client->get('https://recipeapi.io/api/v1/recipes', [
    'query'   => ['cuisine' => 'italian', 'difficulty' => 'easy', 'per_page' => 5],
    'headers' => ['Authorization' => 'Bearer ' . API_KEY],
]);

$data = json_decode($response->getBody(), true);

require "net/http"
require "json"

API_KEY = "sk_live_..."

uri = URI("https://recipeapi.io/api/v1/recipes?cuisine=italian&difficulty=easy&per_page=5")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer #{API_KEY}"

res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http|
  http.request(req)
}

data = JSON.parse(res.body)
puts data

package main

import (
    "fmt"
    "io"
    "net/http"
)

const apiKey = "sk_live_..."

func main() {
    req, _ := http.NewRequest("GET",
        "https://recipeapi.io/api/v1/recipes?cuisine=italian&difficulty=easy&per_page=5", nil)
    req.Header.Set("Authorization", "Bearer "+apiKey)

    resp, _ := http.DefaultClient.Do(req)
    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}

Search by Ingredients

Use the ingredients parameter to find recipes that contain specific ingredients. By default, results are sorted by the number of matching ingredients (recipes matching the most ingredients appear first). Pass an explicit sort parameter to override this behavior.

curl "https://recipeapi.io/api/v1/recipes?ingredients=tomato,basil" \
  -H "Authorization: Bearer sk_live_..."

const API_KEY = "sk_live_...";

const response = await fetch(
    "https://recipeapi.io/api/v1/recipes?ingredients=tomato,basil",
    {headers: {"Authorization": `Bearer ${API_KEY}`}}
);

const data = await response.json();
console.log(data);

import requests

API_KEY = "sk_live_..."

response = requests.get(
    "https://recipeapi.io/api/v1/recipes",
    params={"ingredients": "tomato,basil"},
    headers={"Authorization": f"Bearer {API_KEY}"}
)

data = response.json()
print(data)

// composer require guzzlehttp/guzzle

const API_KEY = 'sk_live_...';

$client = new GuzzleHttp\Client();
$response = $client->get('https://recipeapi.io/api/v1/recipes', [
    'query'   => ['ingredients' => 'tomato,basil'],
    'headers' => ['Authorization' => 'Bearer ' . API_KEY],
]);

$data = json_decode($response->getBody(), true);

require "net/http"
require "json"

API_KEY = "sk_live_..."

uri = URI("https://recipeapi.io/api/v1/recipes?ingredients=tomato,basil")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer #{API_KEY}"

res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http|
  http.request(req)
}

data = JSON.parse(res.body)
puts data

package main

import (
    "fmt"
    "io"
    "net/http"
)

const apiKey = "sk_live_..."

func main() {
    req, _ := http.NewRequest("GET",
        "https://recipeapi.io/api/v1/recipes?ingredients=tomato,basil", nil)
    req.Header.Set("Authorization", "Bearer "+apiKey)

    resp, _ := http.DefaultClient.Do(req)
    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}

This returns recipes where at least one ingredient matches (case-insensitive partial match). You can combine it with any other filter.

Example Response

{
    "data": [
        {
            "id": 449,
            "name": "Beef Tostadas",
            "description": "Beef tostadas are a popular Mexican dish featuring crispy fried tortillas topped with seasoned ground beef and fresh toppings for a delicious and satisfying meal.",
            "difficulty": "easy",
            "meal_type": "main",
            "cuisine": "american",
            "dietary_tags": [
                "nut_free"
            ],
            "servings": 6,
            "prep_time": 15,
            "cook_time": 15,
            "calories_per_serving": 450,
            "protein": 25,
            "instructions": [
                "Heat the vegetable oil in a frying pan over medium heat until hot.",
                "Add the beef and cook, stirring occasionally, until browned and cooked through.",
                "Add chopped onion and minced garlic to the beef, cook until the onion is translucent.",
                "..."
            ],
            "ingredients": [
                {
                    "id": 58,
                    "name": "Chili powder",
                    "category": "spice",
                    "quantity": 1,
                    "unit": "tsp",
                    "optional": false
                },
                {
                    "id": 37,
                    "name": "Garlic",
                    "category": "vegetable",
                    "quantity": 2,
                    "unit": "clove",
                    "optional": false
                },
                "..."
            ]
        },
        {
            "..."
        },
        {
            "..."
        }
    ],
    "links": {
        "first": "https://recipeapi.io/api/v1/recipes?page=1&per_page=3",
        "last": "https://recipeapi.io/api/v1/recipes?page=10&per_page=3",
        "prev": null,
        "next": "https://recipeapi.io/api/v1/recipes?page=2&per_page=3"
    },
    "meta": {
        "current_page": 1,
        "last_page": 10,
        "path": "https://recipeapi.io/api/v1/recipes",
        "per_page": 3,
        "total": 30,
        "language": "en"
    }
}

Localization

All text fields (name, description, instructions) are translatable. Use the lang parameter to get content in a specific language:

GET /api/v1/recipes?lang=fr&search=poulet

Supported languages: en, fr, es
The meta.language field in every response indicates the requested language
Passing an unsupported language returns a 422 error with the list of supported languages
Free plan users passing lang (other than en) receive a 402 error with code PLAN_FEATURE_UNAVAILABLE

Servings & Units

Ingredient quantities are returned in metric units by default. Use servings to scale every quantity to the number of servings you need, and units=imperial to get imperial units. Both work on all recipe endpoints and can be combined:

GET /api/v1/recipes/42?servings=6&units=imperial

servings in the response reflects the requested value. calories_per_serving and protein stay per serving.
pinch and dash are never scaled.
Countable units (piece, slice, clove, bunch, sprig, leaf, can, packet) are never converted.
imperial: g/kg become oz (under 1 lb) or lb, ml/l become tsp (under 15 ml), tbsp (under 60 ml) or cup.
metric (default): quantities use g, kg, ml and l. tsp and tbsp are kept, as they are used in both systems.
Scaled or converted quantities are rounded to amounts you can measure: from 1 upwards, cup, tbsp, tsp and lb go to the nearest quarter, from 2 upwards oz and countable units go to the nearest half, and from 10 upwards g, ml and oz go to whole numbers. Smaller quantities keep 2 decimals, or 2 significant digits below 1 (1 g is 0.035 oz). Converted units can include oz, lb and l.
An invalid value returns a 422 error with code INVALID_PARAMETER.
Free plan users passing servings or units=imperial receive a 402 error with code PLAN_FEATURE_UNAVAILABLE.

Search Scope

By default, search only searches recipe names. Use search_in to expand the search scope:

GET /api/v1/recipes?search=spicy&search_in=description
GET /api/v1/recipes?search=chicken&search_in=both

`search_in` value	Searches in
`name` (default)	Recipe name only
`description`	Recipe description only
`both`	Recipe name and description

Get Recipe

GET /api/v1/recipes/{id}

Returns a single recipe with its full details, including instructions and ingredients.

Path Parameters

Parameter	Type	Description
`id`	integer	Recipe ID

Query Parameters

Parameter	Type	Description
`lang`	string	PaidResponse language (`en`, `fr`, `es`). Defaults to `en`.
`servings`	integer	PaidScale ingredient quantities to this number of servings (1 to 100).
`units`	string	`metric` (default) or `imperial` (Paid).

Example Request

curl "https://recipeapi.io/api/v1/recipes/449" \
  -H "Authorization: Bearer sk_live_..."

const API_KEY = "sk_live_...";

const response = await fetch(
    "https://recipeapi.io/api/v1/recipes/449",
    {headers: {"Authorization": `Bearer ${API_KEY}`}}
);

const data = await response.json();
console.log(data);

import requests

API_KEY = "sk_live_..."

response = requests.get(
    "https://recipeapi.io/api/v1/recipes/449",
    headers={"Authorization": f"Bearer {API_KEY}"}
)

data = response.json()
print(data)

// composer require guzzlehttp/guzzle

const API_KEY = 'sk_live_...';

$client = new GuzzleHttp\Client();
$response = $client->get('https://recipeapi.io/api/v1/recipes/449', [
    'headers' => ['Authorization' => 'Bearer ' . API_KEY],
]);

$data = json_decode($response->getBody(), true);

require "net/http"
require "json"

API_KEY = "sk_live_..."

uri = URI("https://recipeapi.io/api/v1/recipes/449")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer #{API_KEY}"

res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http|
  http.request(req)
}

data = JSON.parse(res.body)
puts data

package main

import (
    "fmt"
    "io"
    "net/http"
)

const apiKey = "sk_live_..."

func main() {
    req, _ := http.NewRequest("GET",
        "https://recipeapi.io/api/v1/recipes/449", nil)
    req.Header.Set("Authorization", "Bearer "+apiKey)

    resp, _ := http.DefaultClient.Do(req)
    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}

Example Response

{
    "data": {
        "id": 449,
        "name": "Beef Tostadas",
        "description": "Beef tostadas are a popular Mexican dish featuring crispy fried tortillas topped with seasoned ground beef and fresh toppings for a delicious and satisfying meal.",
        "difficulty": "easy",
        "meal_type": "main",
        "cuisine": "american",
        "dietary_tags": [
            "nut_free"
        ],
        "servings": 6,
        "prep_time": 15,
        "cook_time": 15,
        "calories_per_serving": 450,
        "protein": 25,
        "instructions": [
            "Heat the vegetable oil in a frying pan over medium heat until hot.",
            "Add the beef and cook, stirring occasionally, until browned and cooked through.",
            "Add chopped onion and minced garlic to the beef, cook until the onion is translucent.",
            "Stir in tomato paste, cumin, chili powder, salt, and pepper, cooking for a few minutes until well combined.",
            "Warm the tostada shells in a separate pan or oven until crisp.",
            "Place a generous spoonful of the beef mixture onto each tostada shell.",
            "Top the beef with shredded lettuce, diced tomato, sliced avocado, shredded cheese, and a dollop of sour cream.",
            "Garnish with chopped cilantro and serve immediately."
        ],
        "ingredients": [
            {
                "id": 58,
                "name": "Chili powder",
                "category": "spice",
                "quantity": 1,
                "unit": "tsp",
                "optional": false
            },
            {
                "id": 37,
                "name": "Garlic",
                "category": "vegetable",
                "quantity": 2,
                "unit": "clove",
                "optional": false
            },
            {
                "id": 8,
                "name": "Cheddar cheese",
                "category": "dairy",
                "quantity": 100,
                "unit": "g",
                "optional": false
            },
            "..."
        ]
    },
    "meta": {
        "language": "en"
    }
}

Error Response (404)

{
    "error": {
        "code": "NOT_FOUND",
        "message": "The requested resource was not found."
    }
}

Random Recipe

GET /api/v1/recipes/random

Returns a single random recipe with full details (instructions + ingredients). Supports the same filters as the List Recipes endpoint to narrow down the random selection, except pagination (page, per_page) and sorting (sort, order) parameters, which are not applicable.

Example Request

curl "https://recipeapi.io/api/v1/recipes/random?cuisine=italian&difficulty=easy" \
  -H "Authorization: Bearer sk_live_..."

const API_KEY = "sk_live_...";

const response = await fetch(
    "https://recipeapi.io/api/v1/recipes/random?cuisine=italian&difficulty=easy",
    {headers: {"Authorization": `Bearer ${API_KEY}`}}
);

const data = await response.json();
console.log(data);

import requests

API_KEY = "sk_live_..."

response = requests.get(
    "https://recipeapi.io/api/v1/recipes/random",
    params={"cuisine": "italian", "difficulty": "easy"},
    headers={"Authorization": f"Bearer {API_KEY}"}
)

data = response.json()
print(data)

// composer require guzzlehttp/guzzle

const API_KEY = 'sk_live_...';

$client = new GuzzleHttp\Client();
$response = $client->get('https://recipeapi.io/api/v1/recipes/random', [
    'query'   => ['cuisine' => 'italian', 'difficulty' => 'easy'],
    'headers' => ['Authorization' => 'Bearer ' . API_KEY],
]);

$data = json_decode($response->getBody(), true);

require "net/http"
require "json"

API_KEY = "sk_live_..."

uri = URI("https://recipeapi.io/api/v1/recipes/random?cuisine=italian&difficulty=easy")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer #{API_KEY}"

res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http|
  http.request(req)
}

data = JSON.parse(res.body)
puts data

package main

import (
    "fmt"
    "io"
    "net/http"
)

const apiKey = "sk_live_..."

func main() {
    req, _ := http.NewRequest("GET",
        "https://recipeapi.io/api/v1/recipes/random?cuisine=italian&difficulty=easy", nil)
    req.Header.Set("Authorization", "Bearer "+apiKey)

    resp, _ := http.DefaultClient.Do(req)
    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}

Example Response

Same structure as Get Recipe response.

Error Response (422)

If no recipe matches the applied filters:

{
    "error": {
        "code": "NO_RECIPE_FOUND",
        "message": "No recipe found matching your filters."
    }
}

List Recipes​

Query Parameters​

Enum Values​

Cuisine​

Meal Type​

Difficulty​

Dietary Tags​

Example Request​

Search by Ingredients​

Example Response​

Localization​

Servings & Units​

Search Scope​

Get Recipe​

Path Parameters​

Query Parameters​

Example Request​

Example Response​

Error Response (404)​

Random Recipe​

Example Request​

Example Response​

Error Response (422)​

List Recipes

Query Parameters

Enum Values

Cuisine

Meal Type

Difficulty

Dietary Tags

Example Request

Search by Ingredients

Example Response

Localization

Servings & Units

Search Scope

Get Recipe

Path Parameters

Query Parameters

Example Request

Example Response

Error Response (404)

Random Recipe

Example Request

Example Response

Error Response (422)