Foodashi API

The complete recipe API for modern food applications. Search by flavor, nutrient, or ingredient with vector-powered semantic search.

# Get your first recipes
curl -X GET "https://api.foodashi.com/api/recipes?cuisine=italian&limit=5" \
  -H "X-Api-Key: YOUR_API_KEY"

const response = await fetch('https://api.foodashi.com/api/recipes?cuisine=italian', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY'
  }
});
const data = await response.json();

import requests

response = requests.get(
    "https://api.foodashi.com/api/recipes",
    headers={"X-Api-Key": "YOUR_API_KEY"}
)
data = response.json()

Authentication

All API requests require authentication via the X-Api-Key header. You can register a new API key at our developer portal.

X-Api-Key: rcpt_indie_xK9d8sL2mN...

Tier Access

Endpoints are gated by your subscription tier. If you call an endpoint above your plan, you'll receive a 403 response with upgrade details.

{
  "error": "Upgrade required",
  "message": "This endpoint requires the pro plan or higher. Your current plan: hobby.",
  "current_tier": "hobby",
  "required_tier": "pro",
  "upgrade_url": "https://foodashi.com/pricing"
}

Plans & Rate Limits

Rate limits and endpoint access are tiered by subscription plan. Monthly quotas reset on your billing anchor date.

Yearly billing = 10× monthly (two months free). Overage: $0.50/1K on Indie, $0.30/1K on Pro.

What each tier unlocks

Error Handling

{
  "error": "Monthly Quota Exceeded.
Upgrade your plan."
}

Get Recipes

Retrieve a list of recipes with powerful filtering options. Supports pagination, dietary filters, cuisine selection, and detailed metadata filtering.

Query Parameters

curl -X GET "https://api.foodashi.com/api/recipes?cuisine=Mexican&exclude_alg=Peanuts&limit=2" \
  -H "X-Api-Key: YOUR_API_KEY"

const res = await fetch('https://api.foodashi.com/api/recipes?cuisine=Mexican&exclude_alg=Peanuts', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' }
});

import requests

response = requests.get(
    "https://api.foodashi.com/api/recipes",
    headers={"X-Api-Key": "YOUR_API_KEY"}
)
data = response.json()

Example Response

{
  "data": [
    {
      "id": "a1b2c3d4-...",
      "title": "Spaghetti Carbonara",
      "cuisine": "Italian",
      "meal_types": ["Dinner", "Main Course"],
      "dish_types": ["Pasta"],
      "difficulty": "Medium",
      "total_time_minutes": 30,
      "servings": 4,
      "image_url": "https://...",
      "dietary_tags": ["Nut-Free"],
      "tags": ["pasta", "comfort-food"]
    }
  ],
  "pagination": { "page": 0, "limit": 10, "total": 86 }
}

Recipe Details

Get complete details for a single recipe including full ingredients, step-by-step instructions, nutrition info, taste profile, and storage metadata.

Query Parameters

curl -X GET "https://api.foodashi.com/api/recipes/details?id=5423" \
  -H "X-Api-Key: YOUR_API_KEY"

const res = await fetch('https://api.foodashi.com/api/recipes/details?id=5423', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' }
});

import requests

response = requests.get(
    "https://api.foodashi.com/api/recipes",
    headers={"X-Api-Key": "YOUR_API_KEY"}
)
data = response.json()

Example Response

{
  "id": "a1b2c3d4-...",
  "title": "Truffle Risotto",
  "description": "Creamy arborio rice with...",
  "cuisine": "Italian",
  "ingredients": [
    { "name": "Arborio Rice", "amount": "300g" },
    { "name": "Truffle Oil", "amount": "2 tbsp" }
  ],
  "instructions": ["Toast rice in butter...", "Add broth gradually..."],
  "nutrition": {
    "calories": 420,
    "protein_g": 12,
    "fat_g": 18,
    "carbs_g": 52
  },
  "nutrimetric": {
    "grade": "B",
    "score": 72,
    "label": "Good",
    "version": "nutrimetric-1.0"
  }
}

Random Recipe

Returns a single random recipe, great for "Surprise Me" features.

curl -X GET "https://api.foodashi.com/api/random?tags=dinner" \
  -H "X-Api-Key: YOUR_API_KEY"

Browse conventions (read once, applies everywhere)

Every /api/recipes/by-* endpoint — plus /api/recipes, /api/recipes/filter, /api/ingredients/by-food-group, and /api/ingredients/:id/recipes — supports the same set of query conventions. Learn these once, use them everywhere.

Pagination (default behaviour)

Default ordering: newest-published first. Every response includes a pagination object with page, limit, total, and total_pages.

Random mode — new 2026-05-10

When you want a fresh sample on every request (e.g. "surprise me" / "explore" UI), pass any of:

All three forms are accepted — pick whichever fits your code style. Under the hood we fetch a wider window (up to 10× the limit, capped at 500) of matching recipes, Fisher-Yates shuffle in memory, and return the first limit. Pagination is meaningless in random mode — each request is its own independent shuffle.

curl -X GET "https://api.foodashi.com/api/recipes/by-cuisine?cuisine=Italian&random=true&limit=5" \
  -H "X-Api-Key: YOUR_API_KEY"

# Same call again returns 5 DIFFERENT Italian recipes
curl -X GET "https://api.foodashi.com/api/recipes/by-cuisine?cuisine=Italian&random=true&limit=5" \
  -H "X-Api-Key: YOUR_API_KEY"

Year-Round is a wildcard for season queries

A recipe explicitly tagged Year-Round is good in every season — so it surfaces in any specific-season query (Spring/Summer/Fall/Winter). The recipe’s seasons array doesn’t need to contain "Spring" for it to appear when you query ?season=Spring; if it contains Year-Round, it qualifies.

• • ?season=Spring → matches recipes whose seasons[] overlaps [Spring, Year-Round]
• • ?season=Summer → matches [Summer, Year-Round]
• • ?season=Fall → matches [Fall, Year-Round] — alias: ?season=Autumn
• • ?season=Winter → matches [Winter, Year-Round]
• • ?season=Year-Round → strict: only recipes explicitly tagged Year-Round

This semantic applies to both /api/recipes/by-season and /api/recipes/filter?season=….

String matching — case & plural tolerance

Ingredient-based endpoints (/api/recipes/by-ingredients, /api/ingredients/:id/recipes text fallback) normalise input before matching:

• • Case-insensitive: red onion = Red Onion = RED ONION
• • Whitespace collapsed: red  onion (double space) = red onion
• • Plural-tolerant: onion = onions, tomato = tomatoes, cherry = cherries
• • Substring match: chicken matches "chicken breast", "ground chicken", etc. Use longer phrases for specificity.
• • Typo-intolerant: red onon returns 0 — call /api/ingredients/autocomplete first if you need fuzzy/typo handling.

Browse by Cuisine

Browse recipes filtered by cuisine type. Returns lightweight recipe cards with pagination.

curl -X GET "https://api.foodashi.com/api/recipes/by-cuisine?cuisine=Italian&limit=10" \
  -H "X-Api-Key: YOUR_API_KEY"

const res = await fetch('https://api.foodashi.com/api/recipes/by-cuisine?cuisine=Italian', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' }
});

import requests

response = requests.get(
    "https://api.foodashi.com/api/recipes",
    headers={"X-Api-Key": "YOUR_API_KEY"}
)
data = response.json()

Browse by Region

Group recipes by sub-continental region (e.g. Southeast Asia covers Thai + Vietnamese + Malaysian + Indonesian + Filipino in one call). Perfect for regional food landing pages.

curl -X GET "https://api.foodashi.com/api/recipes/by-region?region=Southeast%20Asia&limit=20" \
  -H "X-Api-Key: YOUR_API_KEY"

const res = await fetch(
  'https://api.foodashi.com/api/recipes/by-region?' +
    new URLSearchParams({ region: 'Southeast Asia', limit: '20' }),
  { headers: { 'X-Api-Key': 'YOUR_API_KEY' } }
);
const { recipes, pagination } = await res.json();

import requests

res = requests.get(
    "https://api.foodashi.com/api/recipes/by-region",
    params={"region": "Southeast Asia", "limit": 20},
    headers={"X-Api-Key": "YOUR_API_KEY"},
)
data = res.json()

Response shape: { recipes: [...], filter: { region }, pagination: { page, limit, total } }

Browse by Continent

Broadest geographic filter. Useful for top-level navigation like “Asian cuisine” or “European cuisine”.

curl -X GET "https://api.foodashi.com/api/recipes/by-continent?continent=Asia&limit=30" \
  -H "X-Api-Key: YOUR_API_KEY"

const res = await fetch(
  'https://api.foodashi.com/api/recipes/by-continent?continent=Asia&limit=30',
  { headers: { 'X-Api-Key': 'YOUR_API_KEY' } }
);

import requests

res = requests.get(
    "https://api.foodashi.com/api/recipes/by-continent",
    params={"continent": "Asia", "limit": 30},
    headers={"X-Api-Key": "YOUR_API_KEY"},
)

Browse by Country

Filter recipes by a specific country using its ISO-3166-1 alpha-2 code (e.g. JP for Japan, IT for Italy, MX for Mexico). Perfect for country-flag navigation UIs.

curl -X GET "https://api.foodashi.com/api/recipes/by-country?country=JP&limit=25" \
  -H "X-Api-Key: YOUR_API_KEY"

const res = await fetch(
  'https://api.foodashi.com/api/recipes/by-country?country=JP&limit=25',
  { headers: { 'X-Api-Key': 'YOUR_API_KEY' } }
);
const { recipes, filter } = await res.json();
// filter.cuisines_in_country → ["Japanese"]

import requests

res = requests.get(
    "https://api.foodashi.com/api/recipes/by-country",
    params={"country": "JP", "limit": 25},
    headers={"X-Api-Key": "YOUR_API_KEY"},
)

Response includes filter.cuisines_in_country — the list of cuisines mapped to that country, so you can display them as sub-filters in your UI.

Multi-Filter Search

The power user’s endpoint. Combine any subset of the 28 filters below in a single call — location, diet, time, cost, equipment, tags, nutrition, sort. All filters are optional and AND-combined. Empty filter values are ignored.

For valid values of each param, jump to the Reference: Valid values section.

Filters — Location

Filters — Type, Style & Difficulty

Filters — Diet, Tags & Allergens

Filters — Time, Servings & Cost

Filters — Technique & Context

Filters — Nutrition & Quality

Sort & Pagination

Examples

Quick weeknight dinners (under 30 min, max difficulty medium)

curl -X GET "https://api.foodashi.com/api/recipes/filter?meal_type=Dinner&max_time_minutes=30&difficulty=Easy&sort=time_asc&limit=50" \
  -H "X-Api-Key: YOUR_API_KEY"

const params = new URLSearchParams({
  meal_type: 'Dinner',
  max_time_minutes: '30',
  difficulty: 'Easy',
  sort: 'time_asc',
  limit: '50',
});
const res = await fetch(`https://api.foodashi.com/api/recipes/filter?${params}`, {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
});
const { recipes } = await res.json();

import requests

res = requests.get(
    "https://api.foodashi.com/api/recipes/filter",
    params={
        "meal_type": "Dinner",
        "max_time_minutes": 30,
        "difficulty": "Easy",
        "sort": "time_asc",
        "limit": 50,
    },
    headers={"X-Api-Key": "YOUR_API_KEY"},
)

Healthy high-protein vegan meals (Grade B+, min 25g protein)

curl -X GET "https://api.foodashi.com/api/recipes/filter?diet=Vegan&min_protein_g=25&nutrimetric_min_grade=B&sort=nutrimetric&limit=30" \
  -H "X-Api-Key: YOUR_API_KEY"

const res = await fetch(
  'https://api.foodashi.com/api/recipes/filter?' +
    'diet=Vegan&min_protein_g=25&nutrimetric_min_grade=B&sort=nutrimetric&limit=30',
  { headers: { 'X-Api-Key': 'YOUR_API_KEY' } }
);

Mediterranean cuisine, no eggs or nuts, with image, Grade A nutrition

curl -X GET "https://api.foodashi.com/api/recipes/filter?region=Southern%20Europe&exclude_allergens=Eggs,Nuts&has_image=true&nutrimetric_min_grade=A&limit=100" \
  -H "X-Api-Key: YOUR_API_KEY"

Response Shape

{
  "recipes": [
    { "id", "title", "cuisine", "region", "country_code",
      "image_url", "total_time_minutes", "difficulty",
      "dietary_tags", "servings", "tags", ... }
  ],
  "filters_applied": { // Echoed back so you can verify your query was parsed correctly
    "cuisine": "Italian",
    "max_time_minutes": 30,
    "sort": "time_asc"
  },
  "pagination": { "page": 1, "limit": 50, "total": 342, "has_more": true }
}

Reference: Valid values

Every filter param above expects an exact value from one of the catalogues below. Case-sensitive unless noted. Copy-paste straight into your query string.

dish_type — 107 valid values

Pass to dish_type=. Describes what the dish structurally is — different from meal_type (when it's eaten). A "Salad" can be a Lunch, a Side, or a Main.

meal_type — 16 valid values

Pass to meal_type=. Describes WHEN it's eaten or its role at the table. Different recipes can share a dish_type but have different meal_types (a Salad can be Lunch, Side, or Main).

cuisine — 73 valid values

Pass to cuisine=. Case-sensitive exact match.

region — 14 valid values

Pass to region=. Sub-continental grouping.

continent — 5 valid values

diet — 11 dietary tags

Pass to diet=. Recipe must satisfy this dietary constraint. Note: include_tags / exclude_tags use a different (free-form) tag namespace; this diet param is the curated dietary-restriction list.

exclude_allergens — EU-14 list

Pass a CSV like exclude_allergens=Eggs,Dairy,Nuts. Mapped to EU Regulation 1169/2011 — recipes containing any listed allergen are filtered out.

cooking_method — 59 valid values

Pass to cooking_method=. Lowercase. Single value (intersect with other filters for AND).

occasion — 7 valid values

Pass to occasion=. Title-case.

season — 5 valid values

Pass to season=. Case-insensitive. Autumn is accepted as an alias for Fall. Year-Round acts as a wildcard — year-round recipes appear in every specific-season query.

equipment — 300+ values (free-form)

Pass to equipment=. The catalog has 300+ distinct equipment names — pass any specific one for an exact match. Common values:

country — ISO 3166-1 alpha-2 codes

Pass an ISO country code to country=. Foodashi maps it to all cuisines with that flag (e.g. US covers American, Hawaiian, Cajun, Creole). Common examples:

Browse by Diet

Filter recipes by dietary tag. Searches within the recipe's dietary_tags array.

curl -X GET "https://api.foodashi.com/api/recipes/by-diet?diet=Vegan&limit=10" \
  -H "X-Api-Key: YOUR_API_KEY"

Browse by Meal Type

Filter recipes by meal type such as Breakfast, Lunch, Dinner, Snack, or Dessert.

curl -X GET "https://api.foodashi.com/api/recipes/by-meal-type?type=Breakfast" \
  -H "X-Api-Key: YOUR_API_KEY"

Browse by Time

Find quick recipes by specifying a maximum total cook time in minutes.

curl -X GET "https://api.foodashi.com/api/recipes/by-time?maxMinutes=30" \
  -H "X-Api-Key: YOUR_API_KEY"

Browse by Difficulty

Filter recipes by difficulty level: Easy, Medium, or Hard.

curl -X GET "https://api.foodashi.com/api/recipes/by-difficulty?difficulty=Easy" \
  -H "X-Api-Key: YOUR_API_KEY"

Recipe Count

Get the total number of published recipes. Supports optional filters to count subsets.

curl -X GET "https://api.foodashi.com/api/recipes/count?cuisine=Italian" \
  -H "X-Api-Key: YOUR_API_KEY"

List Cuisines

Get all cuisines that have published recipes, with recipe counts for each.

curl -X GET "https://api.foodashi.com/api/recipes/cuisines" \
  -H "X-Api-Key: YOUR_API_KEY"

List Tags

Get all recipe tags with counts. Useful for building tag clouds or filter UIs.

curl -X GET "https://api.foodashi.com/api/recipes/tags" \
  -H "X-Api-Key: YOUR_API_KEY"

List Dietary Tags

Get all dietary tags with recipe counts. Useful for dietary filter UIs.

curl -X GET "https://api.foodashi.com/api/recipes/diets" \
  -H "X-Api-Key: YOUR_API_KEY"

Autocomplete

Extremely fast search for UI search bars. Returns lightweight titles matching the query.

curl -X GET "https://api.foodashi.com/api/autocomplete?query=chick" \
  -H "X-Api-Key: YOUR_API_KEY"

Bulk Lookup

Fetch details for multiple recipes in a single API call. Essential for "Favorites" lists.

curl -X GET "https://api.foodashi.com/api/bulk-lookup?ids=501,892,120" \
  -H "X-Api-Key: YOUR_API_KEY"

Similar Recipes

Uses Vector embeddings to find recipes that are semantically similar to the provided ID. Perfect for "You might also like" features.

curl -X GET "https://api.foodashi.com/api/similar?id=5291" \
  -H "X-Api-Key: YOUR_API_KEY"

Browse by Cooking Method

Find recipes by cooking technique such as grilling, baking, stir-frying, or slow cooking.

curl -X GET "https://api.foodashi.com/api/recipes/by-cooking-method?method=grilling" \
  -H "X-Api-Key: YOUR_API_KEY"

Browse by Equipment

Find recipes that use specific kitchen equipment like air fryer, slow cooker, or wok.

curl -X GET "https://api.foodashi.com/api/recipes/by-equipment?equipment=air+fryer" \
  -H "X-Api-Key: YOUR_API_KEY"

Browse by Occasion

Find recipes perfect for holidays and events like Christmas, Thanksgiving, BBQ parties, or date night.

curl -X GET "https://api.foodashi.com/api/recipes/by-occasion?occasion=Christmas" \
  -H "X-Api-Key: YOUR_API_KEY"

Browse by Season

Find seasonal recipes for a given time of year. Returns recipes whose seasons array contains the requested season OR Year-Round — so year-round dishes surface in every season filter. See browse conventions for full details.

curl -X GET "https://api.foodashi.com/api/recipes/by-season?season=Spring&limit=20" \
  -H "X-Api-Key: YOUR_API_KEY"

curl -X GET "https://api.foodashi.com/api/recipes/by-season?season=Spring&random=true&limit=10" \
  -H "X-Api-Key: YOUR_API_KEY"

# Each request returns a different 10 — fresh shuffle every time.

Smart Search

Vector-powered semantic search. Find recipes by describing what you want in natural language — e.g. "spicy dinner under 500 cals", "comfort food for winter", "easy weeknight pasta".

Query Parameters

curl -X GET "https://api.foodashi.com/api/search?q=comfort+food+for+winter&limit=5" \
  -H "X-Api-Key: YOUR_API_KEY"

const res = await fetch('https://api.foodashi.com/api/search?q=comfort+food', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' }
});

import requests

response = requests.get(
    "https://api.foodashi.com/api/recipes",
    headers={"X-Api-Key": "YOUR_API_KEY"}
)
data = response.json()

Browse by Nutrients

Filter recipes by nutrient ranges. Find high-protein, low-calorie, or custom macro recipes.

curl -X GET "https://api.foodashi.com/api/recipes/by-nutrients?minProtein=25&maxCalories=500" \
  -H "X-Api-Key: YOUR_API_KEY"

Browse by Ingredients

Find recipes that contain (or avoid) specific ingredients. Just send ingredient names — no need to look up UUIDs first. Powers "what’s in my fridge", allergen-avoidance, and pantry-based recipe discovery.

Matching rules — no surprises

• • Case-insensitive: Red Onion, red onion, RED ONION all match identically.
• • Whitespace-normalized: red  onion (extra spaces) matches the same as red onion.
• • Plural-tolerant: onion = onions, tomato = tomatoes, cherry = cherries. No need to guess what form the catalogue uses.
• • Substring match: chicken matches "chicken breast", "ground chicken", "chicken thigh", etc. To be more specific, use a longer phrase like chicken breast.
• • Typo-intolerant: red onon returns 0. For fuzzy/typo matching, hit /api/ingredients/autocomplete first and pass the corrected name.
• • Resolver-aware: even when the catalogue stores a recipe’s ingredient as generic ("Onions, raw") rather than the specific variant ("Red Onions"), this endpoint still finds recipes that mention red onion in their original ingredient text. You get the result you expect without having to know about internal canonical IDs.

curl -X GET "https://api.foodashi.com/api/recipes/by-ingredients?include=red%20onion&limit=10" \
  -H "X-Api-Key: YOUR_API_KEY"

curl -X GET "https://api.foodashi.com/api/recipes/by-ingredients?include=chicken,rice&limit=20" \
  -H "X-Api-Key: YOUR_API_KEY"

curl -X GET "https://api.foodashi.com/api/recipes/by-ingredients?include=chicken,rice&exclude=nuts,dairy" \
  -H "X-Api-Key: YOUR_API_KEY"

{
  "recipes": [
    {
      "id": "03905874-4035-4754-9418-13c687d7f429",
      "title": "আলু ভর্তা",
      "title_english": "Mashed Potato Bhorta",
      "image_url": "https://.../recipe-...-1776634763681.png",
      "cuisine": "Bangladeshi",
      "cuisine_code": "BD",
      "total_time_minutes": 22,
      "difficulty": "Easy",
      "servings": 4,
      "dietary_tags": ["Vegan", "Gluten-Free", "Nut-Free", "Soy-Free"],
      "tags": ["comfort-food", "dinner", "side-dish"],
      "published_at": "2026-05-06T11:33:35.731+00:00"
    }
  ],
  "filter": {
    "include": ["red onion"],
    "exclude": []
  },
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 10,
    "total_pages": 1
  }
}

Error responses

Recipe Nutrition

Get a full nutrition breakdown for a recipe, computed live from its ingredients. Includes macros, vitamins, and minerals per serving.

curl -X GET "https://api.foodashi.com/api/recipes/{id}/nutrition" \
  -H "X-Api-Key: YOUR_API_KEY"

Recipe Allergens

EU-compliant allergen declaration with all 14 regulated allergens, hidden allergen sources, and cross-contamination warnings.

curl -X GET "https://api.foodashi.com/api/recipes/{id}/allergens" \
  -H "X-Api-Key: YOUR_API_KEY"

Beverage Pairing

AI-generated beverage pairing suggestions including wine, beer, cocktails, and non-alcoholic options.

curl -X GET "https://api.foodashi.com/api/recipes/{id}/beverages" \
  -H "X-Api-Key: YOUR_API_KEY"

Scale Servings

Recalculate all ingredient quantities for a different number of servings.

curl -X GET "https://api.foodashi.com/api/recipes/{id}/scale?servings=8" \
  -H "X-Api-Key: YOUR_API_KEY"

Taste Profile

6-axis taste profile rated 0-10: sweetness, saltiness, sourness, bitterness, savoriness, and spiciness.

curl -X GET "https://api.foodashi.com/api/recipes/{id}/taste" \
  -H "X-Api-Key: YOUR_API_KEY"

Sustainability

Environmental impact data including Eco-Score (A-E), carbon footprint estimate, and sustainability tips.

curl -X GET "https://api.foodashi.com/api/recipes/{id}/sustainability" \
  -H "X-Api-Key: YOUR_API_KEY"

Medical Cautions

Medical caution flags for conditions like diabetes, hypertension, gout, and kidney disease.

curl -X GET "https://api.foodashi.com/api/recipes/{id}/medical" \
  -H "X-Api-Key: YOUR_API_KEY"

Compare Recipes

Side-by-side nutritional comparison of 2-5 recipes.

curl -X GET "https://api.foodashi.com/api/recipes/compare?ids=uuid1,uuid2" \
  -H "X-Api-Key: YOUR_API_KEY"

Ingredients API — which endpoint do I use?

Foodashi exposes several ingredient endpoints. Pick by use case:

curl "https://api.foodashi.com/api/recipes/by-ingredients?include=red%20onion&limit=10" \
  -H "X-Api-Key: YOUR_API_KEY"

Search Ingredients

Search through 340,000+ ingredients from our curated ingredient database. Supports filtering by type (ingredients vs branded products).

curl -X GET "https://api.foodashi.com/api/ingredients/search?q=chicken&limit=5" \
  -H "X-Api-Key: YOUR_API_KEY"

Ingredient Autocomplete

Fast prefix & substring autocomplete for ingredient search bars. Returns canonical name, UUID, food group, category, and type. Quality-ranked so the most authoritative match comes first.

curl -X GET "https://api.foodashi.com/api/ingredients/autocomplete?q=red%20onion" \
  -H "X-Api-Key: YOUR_API_KEY"

{
  "results": [
    {
      "id": "d642a69d-3c98-4c55-83a5-f231cde9eebd",
      "name": "Red Onion",
      "food_group": "11",
      "category": "Produce",
      "ingredient_type": "raw"
    },
    {
      "id": "f67dbb93-479b-4ea1-8a50-d6dc2cc33771",
      "name": "Red Onions",
      "food_group": "11",
      "category": "Produce",
      "ingredient_type": "raw"
    }
  ],
  "query": "red onion",
  "count": 2
}

List Food Groups

Get all food groups with ingredient counts. Useful for building category navigation.

curl -X GET "https://api.foodashi.com/api/ingredients/food-groups" \
  -H "X-Api-Key: YOUR_API_KEY"

Ingredient Details

Get detailed nutrition information for a specific ingredient including macros, vitamins, minerals, and available portion sizes.

{
  "id": "abc123-def456...",
  "name": "Chicken breast, raw",
  "food_group": "Poultry Products",
  "nutrition_per_100g": {
    "calories": 165,
    "protein": 31,
    "fat": 3.6,
    "carbohydrates": 0
  },
  "portions": [
    { "unit": "breast", "grams": 174 }
  ]
}

Unit Conversion

Convert between different units for a specific ingredient using real portion data.

curl -X GET "https://api.foodashi.com/api/ingredients/{id}/convert?amount=2&from_unit=cup&to_unit=g" \
  -H "X-Api-Key: YOUR_API_KEY"

Ingredient Substitutes

Find nutritionally similar substitutes for an ingredient based on food group and macro profile.

curl -X GET "https://api.foodashi.com/api/ingredients/{id}/substitutes" \
  -H "X-Api-Key: YOUR_API_KEY"

const res = await fetch('https://api.foodashi.com/api/ingredients/{id}/substitutes', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' }
});
const data = await res.json();

import requests

response = requests.get(
    "https://api.foodashi.com/api/ingredients/{id}/substitutes",
    headers={"X-Api-Key": "YOUR_API_KEY"}
)
data = response.json()

Recipes Using Ingredient (by UUID)

Find all published recipes that use the canonical ingredient identified by UUID. The UUID typically comes from /api/ingredients/autocomplete or /api/ingredients/search.

curl -X GET "https://api.foodashi.com/api/ingredients/d642a69d-3c98-4c55-83a5-f231cde9eebd/recipes?limit=10" \
  -H "X-Api-Key: YOUR_API_KEY"

{
  "ingredient_id": "d642a69d-3c98-4c55-83a5-f231cde9eebd",
  "recipes": [
    {
      "id": "eb0b3a12-8394-45ac-aa4c-d42f13e09ce5",
      "title": "වම්බටු මෝජු",
      "title_english": "Sri Lankan Eggplant Moju",
      "image_url": "https://.../recipe-...-1776635175073.png",
      "cuisine": "Sri Lankan",
      "total_time_minutes": 66,
      "difficulty": "Medium",
      "servings": 6,
      "dietary_tags": ["Vegan", "Gluten-Free"]
    }
  ],
  "pagination": { "page": 1, "limit": 10, "total": 10, "total_pages": 1 }
}

Behavior notes

• • If 0 direct matches exist on the canonical link, the endpoint falls back to a text search using the canonical’s display name. You don’t need to know whether the recipe linked to the generic or specific variant — the result set is consistent.
• • Returns 400 if :id is not a valid UUID.
• • Returns 200 with empty recipes array when no matches (not a 404).

Ingredient Allergen Check

Check which EU-14 allergens an ingredient contains or may contain.

curl -X GET "https://api.foodashi.com/api/ingredients/{id}/allergens" \
  -H "X-Api-Key: YOUR_API_KEY"

Browse by Food Group

Browse ingredients within a food group. Accepts either a friendly category name ("Produce", "Dairy", "Bakery", "Pantry") or a USDA numeric food-group code ("11" for Vegetables). Case-insensitive for names.

curl -X GET "https://api.foodashi.com/api/ingredients/by-food-group?group=Produce&limit=20" \
  -H "X-Api-Key: YOUR_API_KEY"

curl -X GET "https://api.foodashi.com/api/ingredients/by-food-group?group=11&limit=20" \
  -H "X-Api-Key: YOUR_API_KEY"

Ingredient Portions

Get all available portion sizes for an ingredient with gram weight equivalents.

curl -X GET "https://api.foodashi.com/api/ingredients/{id}/portions" \
  -H "X-Api-Key: YOUR_API_KEY"

Quick Ingredient Substitute

Lightweight ingredient-name substitute lookup (no UUID needed). Pass an ingredient name as a query parameter; receive common substitutes from a curated lookup table. For nutritionally-accurate substitutes use /api/ingredients/:id/substitutes instead.

curl -X GET "https://api.foodashi.com/api/ingredient-substitute?ingredient=butter" -H "X-Api-Key: KEY"
curl -X GET "https://api.foodashi.com/api/ingredient-substitute?name=butter"       -H "X-Api-Key: KEY"
curl -X GET "https://api.foodashi.com/api/ingredient-substitute?q=butter"          -H "X-Api-Key: KEY"

Semantic Ingredient Search

Find ingredients by meaning, not just keywords. Powered by vector embeddings — handles synonyms, regional spellings, and culinary equivalents. Searching "cilantro" finds "coriander leaf"; "shrimp" finds "prawn". Useful for cross-locale recipe matching.

curl -X GET "https://api.foodashi.com/api/ingredients/semantic-search?q=fish%20sauce%20alternative&limit=5" \
  -H "X-Api-Key: YOUR_API_KEY"

Analyze Existing Recipe (by ID)

Run deep analysis on a specific recipe in our database — returns its full classification (meal_types, dish_types, occasions), nutrition breakdown, allergen detection, dietary tag confidence, and NutriMetric score. Use this to enrich recipe metadata in your app without re-running the full /api/analyze/text endpoint.

curl -X POST "https://api.foodashi.com/api/recipes/analyze" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"recipe_id": "a1b2c3d4-e5f6-..."}'

Batch Ingredient Lookup

Look up multiple ingredients at once. Much faster than individual searches for recipes.

{
  "ingredients": ["chicken", "rice", "tomato"]
}

curl -X POST "https://api.foodashi.com/api/ingredients/batch" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ingredients": ["chicken", "rice", "tomato"]}'

Ingredients by Nutrient

Find ingredients high or low in a specific nutrient. Great for meal planning and dietary goals.

curl -X GET "https://api.foodashi.com/api/ingredients/by-nutrient?nutrient=protein&min=20" \
  -H "X-Api-Key: YOUR_API_KEY"

Compare Ingredients

Side-by-side nutritional comparison of 2-5 ingredients per 100g.

curl -X GET "https://api.foodashi.com/api/ingredients/compare?ids=uuid1,uuid2" \
  -H "X-Api-Key: YOUR_API_KEY"

Nutrient List

Get all tracked nutrients with their units and categories (macros, vitamins, minerals, etc.).

curl -X GET "https://api.foodashi.com/api/nutrition/nutrients" \
  -H "X-Api-Key: YOUR_API_KEY"

Daily Reference Values

FDA and EU daily reference intakes (DRI/RDI) for 30+ nutrients based on a 2,000 calorie diet.

curl -X GET "https://api.foodashi.com/api/nutrition/daily-values" \
  -H "X-Api-Key: YOUR_API_KEY"

Nutrition Label

Generate FDA or EU format nutrition label data from custom ingredient lists. Returns structured label data with %DV calculations.

curl -X POST "https://api.foodashi.com/api/nutrition/label" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"nutrition_per_serving":{"calories":250,"total_fat_g":12,"saturated_fat_g":3,"cholesterol_mg":30,"sodium_mg":470,"total_carbohydrate_g":31,"dietary_fiber_g":2,"total_sugars_g":5,"added_sugars_g":2,"protein_g":18},"serving_size":"2/3 cup (55g)","servings_per_container":8,"format":"fda"}'

NutriMetric Calculator

Calculate NutriMetric nutrition quality score (A–F grade, 0-100 scale) for custom nutrition data. Uses 4 scoring pillars: protein density, calorie density, fat balance, and sodium. Category-aware for beverages, soups, desserts, and more.

curl -X POST "https://api.foodashi.com/api/nutrition/nutrimetric" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"nutrition_per_100g":{"energy_kcal":190,"protein_g":12,"fat_g":8,"carbohydrate_g":15,"sodium_mg":400,"fiber_g":2,"saturated_fat_g":3,"sugars_total_g":5},"category":"main"}'

Unit Converter

General-purpose unit conversion with ingredient-specific density adjustments. Supports 30+ units including cups, tablespoons, ounces, and more.

curl -X GET "https://api.foodashi.com/api/convert?amount=1&from=cup&to=g&ingredient=flour" \
  -H "X-Api-Key: YOUR_API_KEY"

Allergen List

Complete list of EU 14 regulated allergens plus extended allergens, with EU regulation metadata.

curl -X GET "https://api.foodashi.com/api/allergens" \
  -H "X-Api-Key: YOUR_API_KEY"

Diet List

All 50+ canonical dietary tags grouped by category: lifestyle, low-carb, allergen-free, religious, nutritional, and regional.

curl -X GET "https://api.foodashi.com/api/diets" \
  -H "X-Api-Key: YOUR_API_KEY"

Cuisine List

All 77 world cuisines grouped by region: East/Southeast Asia, South & Central Asia, Middle East, North Africa, Europe, Nordic, North America, South America, Caribbean, Pacific, and Sub-Saharan Africa.

curl -X GET "https://api.foodashi.com/api/cuisines" \
  -H "X-Api-Key: YOUR_API_KEY"

Analyze Recipe Text

Extract a recipe from raw text using AI, then run the full nutrition pipeline: 8 nutrients with %DV, EU 14 allergens, dietary tags, and NutriMetric scoring.

Request Body

Response Highlights

• recipe — Extracted title, servings, ingredients with amounts/units/preparation
• nutrition — per_serving, per_100g, per_recipe with 8 nutrients + %DV
• allergens / may_contain — EU 14 allergen detection with sources
• dietary_tags — 50+ tags (Vegan, Keto, Halal, etc.)
• nutrimetric — Proprietary nutrition grade (A–F, A best)

curl -X POST "https://api.foodashi.com/api/analyze/text" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Chicken Parmesan\n\n2 chicken breasts\n1 cup breadcrumbs\n1 cup marinara\n1 cup mozzarella\n\n1. Bread chicken. 2. Fry. 3. Top with sauce and cheese. 4. Bake 375F 20 min."}'

Analyze Recipe URL

Fetch a recipe from any URL, extract it with AI, then run the full nutrition + allergen + NutriMetric pipeline. Works with most recipe blogs and cooking sites.

Request Body

curl -X POST "https://api.foodashi.com/api/analyze/url" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://cooking.nytimes.com/recipes/1015819-chocolate-chip-cookies"}'

Recognize Dish from Photo

Upload a food photo (base64 or URL) and get dish identification with confidence score, estimated ingredients with gram weights, estimated nutrition, and matching recipes from our database.

Request Body

curl -X POST "https://api.foodashi.com/api/recognize/image" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image_url": "https://example.com/pizza-photo.jpg", "max_results": 3}'

Recognize Ingredients from Photo

Snap a photo of your fridge, pantry, or counter and get every ingredient identified with estimated quantities, canonical DB matches (for precise nutrition lookup), storage suggestions, and recipe ideas.

Request Body

curl -X POST "https://api.foodashi.com/api/recognize/ingredients" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image_url": "https://example.com/fridge-contents.jpg"}'

AI Sommelier — Beverage Pairing

Get expert beverage pairings from an AI Master Sommelier. Supports wine, beer, cocktails, spirits, and culturally-specific non-alcoholic beverages. Accepts dish names, ingredient lists, food photos, or recipe IDs.

Request Body (provide exactly one)

Optional Preferences

Response

Returns 5 beverage categories with specific names, reasoning, and serving details.

curl -X POST "https://api.foodashi.com/api/pairing/beverages" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dish": "Feijoada"}'

curl -X POST "https://api.foodashi.com/api/pairing/beverages" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dish": "Biryani", "preferences": {"no_alcohol": true, "style": "fine-dining"}}'

Generate Meal Plan

AI-powered meal plan generator. Specify calorie targets, macro ratios, dietary restrictions, allergen exclusions, and cuisine preferences. Returns a day-by-day plan with real DB recipes (full nutrition) plus AI-generated suggestions where needed. Includes daily/weekly nutrition totals and a shopping-list-compatible format.

Request Body

curl -X POST "https://api.foodashi.com/api/meal-plan/generate" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "days": 7,
    "goal": "lose_weight",
    "calories_per_day": 1600,
    "dietary_restrictions": ["Dairy-Free"],
    "meals_per_day": ["breakfast", "lunch", "dinner"],
    "servings": 2
  }'

Customize Meal Plan

Modify an existing meal plan: swap a specific meal with a chosen recipe, regenerate all meals for a day, or regenerate a single meal. Pass the plan object from the generate endpoint.

Request Body

curl -X POST "https://api.foodashi.com/api/meal-plan/customize" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"plan": {...}, "action": "swap", "day_index": 0, "meal_index": 2, "swap_recipe_id": "uuid"}'

Meal Plan Templates

Browse 8 pre-built meal plan templates covering common goals: Balanced Weight Loss, Muscle Building, Mediterranean Heart Health, Plant-Based Week, Keto, Family Friendly, Quick Meals, and Clean Bulk.

Query Parameters

curl -X GET "https://api.foodashi.com/api/meal-plan/templates?goal=lose_weight" \
  -H "X-Api-Key: YOUR_API_KEY"

Shopping List from Recipes

Generate a consolidated shopping list from multiple recipe IDs. Ingredients are merged, de-duplicated, and organized by USDA food groups (Produce, Protein, Dairy, Grains, Pantry, Beverages, Other).

curl -X POST "https://api.foodashi.com/api/shopping-list/from-recipes" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"recipe_ids": ["uuid-1", "uuid-2"], "unit_system": "metric"}'

Shopping List from Meal Plan

Generate a shopping list directly from a meal plan (the shopping_list_compatible field from /api/meal-plan/generate). Automatically extracts all recipe IDs and applies per-meal servings overrides.

curl -X POST "https://api.foodashi.com/api/shopping-list/from-meal-plan" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"meal_plan": {"days": [{"meals": [{"recipe_id": "uuid", "servings": 2}]}]}}'

Optimize Shopping List

AI-powered shopping list optimization. Groups items by store aisle, suggests cheaper substitutions, estimates total cost, and provides storage tips.

curl -X POST "https://api.foodashi.com/api/shopping-list/optimize" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"shopping_list": {"categories": [...]}, "preferences": {"budget": "medium"}}'

Cooking & Prep Tips

AI-powered cooking and preparation tips for any ingredient or recipe name. Supports any language. Choose between cooking tips, prepping tips, or both. When a match is found in the database, tips are enriched with allergen, cuisine, and nutritional context for more specific advice.

Parameters

curl -X POST "https://api.foodashi.com/api/tips" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "chicken thigh", "type": "ingredient", "tip_type": "cooking"}'

{
  "success": true,
  "data": {
    "name": "chicken thigh",
    "name_english": "Chicken Thigh",
    "type": "ingredient",
    "tip_type": "cooking",
    "tips": [
      {
        "category": "temperature",
        "title": "Optimal Internal Temperature",
        "tip": "Cook to 74°C (165°F) internal..."
      }
    ],
    "tip_count": 5,
    "db_enriched": true
  }
}

API Stats

Get aggregated statistics about the recipe database including counts by cuisine, dietary tags, allergens, equipment, and NutriMetric grades.

{
  "total_recipes": 12847,
  "total_ingredients": 340000,
  "api_version": "3.0-pipeline",
  "status": "operational"
}

Response Schema

Example response from /api/recipes/details. Fields like nutrimetric, wine_pairing, eco_score, and medical_cautions are Pro+ only (null on Hobby).

{
  "id": "a1b2c3d4-e5f6-...",
  "title": "Caldo de Res",
  "title_english": "Mexican Beef Soup",
  "description": "A hearty Mexican beef soup...",
  "image_url": "https://...",
  "prep_time_minutes": 25,
  "cook_time_minutes": 90,
  "rest_time_minutes": 0,
  "total_time_minutes": 115,
  "servings": 4,
  "cuisine": "Mexican",
  "cuisine_code": "MX",
  "meal_types": ["Dinner", "Main Course"],
  "dish_types": ["Stew"],
  "difficulty": "Medium",
  "cost_level": 2,
  "protein_source": ["Beef"],
  "tags": ["authentic", "comfort-food"],
  "cooking_methods": ["Braising", "Simmering"],
  "occasions": ["Weeknight Dinner"],
  "seasons": ["Winter", "Fall"],
  "equipment": ["Dutch Oven", "Knife"],
  "dietary_tags": ["Gluten-Free"],
  "allergens": ["Celery"],
  "allergen_declaration": { "compliance": "EU-1169", "declaration": "Contains celery." },

  "nutrition": {
    "calories": 455,
    "protein_g": 35.2,
    "fat_g": 18.1,
    "saturated_fat_g": 5.2,
    "carbohydrate_g": 43.0,
    "fiber_g": 8.3,
    "sugars_total_g": 6.1,
    "sodium_mg": 850,
    "per_100g": { "calories": 98, "protein_g": 7.6, "fat_g": 3.9, "carbohydrate_g": 9.3, "sodium_mg": 183 }
  },

  "nutrimetric": {
    "grade": "B",
    "score": 68,
    "label": "Good",
    "version": "nutrimetric-1.0"
  },

  "taste_profile": {
    "spicy": 3,
    "salty": 5,
    "sweet": 2,
    "umami": 7,
    "bitter": 1,
    "sour": 2
  },

  "storage": {
    "refrigerator_days": 3,
    "freezer_friendly": true,
    "reheating_instructions": "Reheat on stovetop..."
  },

  "beverage_pairing": { "pairings": [ { "name": "Malbec", "category": "Red Wine", "alcoholic": true, "why": "Bold tannins stand up to the rich braise" } ] },

  "ingredients": [
    {
      "text": "450 g Beef chuck",
      "name": "Beef chuck",
      "quantity": "450",
      "unit": "g",
      "is_main": true,
      "preparation": "cubed",
      "optional": false,
      "gram_weight": 450
    }
  ],

  "steps": [
    {
      "step": 1,
      "text": "Sear the beef...",
      "duration_minutes": 8,
      "temperature": null,
      "tip": "Pat dry for better sear"
    }
  ]
}

Available Cuisines (78)

East Asia

Southeast Asia

South & Central Asia

Middle East

North Africa

Europe

Nordic

North America

South America

Caribbean

Pacific

Sub-Saharan Africa

Meal Types

Dietary Tags (55)

Lifestyle

Low-Carb

Nutritional

Allergen-Free

Medical

Other

Common Allergens (EU 14)

Track and filter recipes based on the 14 EU-regulated food allergens. Each recipe includes both confirmed allergens (detectedAllergens) and uncertain traces (mayContainAllergens).

Kitchen Equipment (125)

Filter recipes by required kitchen equipment. Equipment is auto-detected from recipe instructions across all 78 world cuisines.

Pots & Pans

Bakeware

Appliances

Knives & Cutting

Prep Tools

Measuring

World Cuisine Specialty

Changelog

What's new in the Foodashi API. We ship data-quality and capability improvements continuously.