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...

Authorization: Bearer <your API key> is accepted as an alternative to X-Api-Key, for clients and agent frameworks that can only send a Bearer token. Both headers pass the API's CORS preflight from an allowed origin.

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",
  "code": "tier_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. Usage is counted in credits: most calls cost 1 credit, AI calls cost more (up to 400); every endpoint below shows its cost. Included credits reset on the 1st of each month at 00:00 UTC; the extra usage balance is prepaid and does not reset.

Yearly billing = 10× monthly (two months free). Extra usage: $0.50 per 1,000 credits on Indie and $0.30 on Pro, from a prepaid balance; Hobby has none. RPM counts requests, whatever each one costs.

Key lookups. Apart from your plan’s RPM, one client address can make 120 API key lookups per minute. A key used in the last few seconds is not looked up again, so a working integration rarely meets this limit; unknown or invalid keys do count. Over it the answer is 429 rate_limited with "limit": 120, retry_after and a Retry-After header in seconds, and without the X-RateLimit-* headers.

What each tier unlocks

Attribution

On the Hobby plan, wherever your app or site shows Foodashi data, it must show a visible “Powered by Foodashi” credit that links to https://foodashi.com. Indie, Pro and Enterprise plans need no Foodashi credit: you can present the data entirely under your own brand.

Visible means a reader can see and follow it without opening a menu: next to the data, or in the footer of the same page or screen. In a native app, a text button that opens https://foodashi.com in the browser does the same job. Copy this snippet:

<p class="foodashi-credit"><a href="https://foodashi.com">Powered by Foodashi</a></p>

Style it to fit your design, as long as the text stays readable and the link works. This credit is separate from the open-database credits that apply on every plan: if you show nutrition, ingredient or barcode data, also link to foodashi.com/data-sources somewhere your users can find it. The full terms are in the API License Agreement, Section 6.

Error Handling

A call that fails costs nothing. An answer of 400, 402, 403, 404, 405, 413, 422 or any 5xx gives back the requests it counted, and any extra usage it took from your balance. There are two exceptions: an AI endpoint whose AI step already ran before the error, and nutrition calculate answering 422 after it matched your ingredients (no ingredient could be matched, or nutrition could not be computed). That work is done, so the call’s credits stay spent; a 400 before any work is still free. A 429 costs nothing either.

{
  "error": "Rate Limit Exceeded",
  "code": "quota_exceeded",
  "message": "Monthly Quota Exceeded",
  "retry_after": 561600,
  "upgrade_url": "https://foodashi.com/pricing"
}

Every error body carries a stable machine-readable code (for example invalid_parameter, unknown_parameter, unknown_field, invalid_allergen, invalid_id, offset_too_deep, not_found, unauthorized, missing_api_key, invalid_api_key, service_unavailable). Branch on code; the error and message text may change. Report a Recipe has its own codes: invalid_report, customer_key_required, recipe_not_found and report_limit_exceeded.

Authorization: Bearer <your API key> is accepted as an alternative to X-Api-Key; both pass the CORS preflight from an allowed origin.

Get Recipes

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

Query Parameters

Unknown query parameters return 400 with code unknown_parameter and the list of accepted_parameters. Out-of-range page and limit values are clamped, never refused. A page past the last one returns 200 with an empty recipes list and the true pagination.total and total_pages. Pages past offset 1000 return 400 with code offset_too_deep; pagination.total_pages counts only servable pages (pages_truncated tells you when more match).

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

{
  "recipes": [
    {
      "id": "a1b2c3d4-...",
      "title": "Spaghetti Carbonara",
      "cuisine": "Italian",
      "meal_types": ["Dinner", "Main Course"],
      "dish_types": ["Pasta"],
      "difficulty": null,
      "total_time_minutes": 30,
      "servings": 4,
      "image_url": "https://...",
      "dietary_tags": ["Nut-Free"],
      "allergens": ["Gluten", "Eggs", "Dairy"],
      "nutrition": { "calories": 520, "protein_g": 22, ... },
      "ingredients": [ ... ],
      "steps": [ ... ],
      ...
    }
  ],
  "pagination": { "page": 1, "limit": 2, "total": 86, "total_pages": 43 }
}

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=b1a2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "X-Api-Key: YOUR_API_KEY"

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

import requests

response = requests.get(
    "https://api.foodashi.com/api/recipes/details?id=b1a2c3d4-e5f6-7890-abcd-ef1234567890",
    headers={"X-Api-Key": "YOUR_API_KEY"}
)
data = response.json()

Example Response

{
  "id": "07211f3f-a2e6-4d5e-ad3c-703ac6512548",
  "title": "Milanesa de Pollo Napolitana",
  "title_english": "Chicken Neapolitan Milanese",
  "cuisine": "Argentine",
  "cuisine_code": "AR",
  "servings": 4,
  "ingredients": [
    { "text": "600 g chicken breast", "name": "chicken breast", "quantity": 600, "unit": "g", "gram_weight": 600, "is_main": true, ... }
  ],
  "steps": [
    { "step": 1, "text": "Place each chicken breast cutlet between two sheets...", "duration_minutes": 5, ... }
  ],
  "nutrition": {
    "calories": 758,
    "protein_g": 58.4,
    "fat_g": 45.5,
    "carbohydrate_g": 28.1,
    ...
    "per_100g": { "calories": 222.8, "protein_g": 17.2, ... }
  },
  "nutrimetric": {
    "grade": "C",
    "score": 69,
    "label": "Moderate",
    "version": "nutrimetric-1.0"
  },
  ...
}

nutrimetric and beverage_pairing are paid fields (Indie plan and above). A Hobby key receives a {"locked": true, ...} marker in their place; see Paid Fields.

Random Recipe

Returns a random recipe, great for "Surprise Me" features. Every filter is optional and they combine.

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

count=1 returns one recipe object; count>1 returns {recipes, count} (plus partial and failed_ids if a recipe could not be formatted).

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.

Every list returns the full recipe

Each item of recipes[] is the complete recipe object /api/recipes/details returns, ingredients, steps, nutrition and allergens included, under your plan. Every browse endpoint and /api/recipes/filter also take fields to return only the fields you name (Trimming the Recipe). A list may carry "partial": true and failed_ids when a recipe could not be formatted, and a list whose data could not be read is a retryable 503 service_unavailable, never a partial page.

Pagination (default behaviour)

Default ordering: newest-published first. Every response includes a pagination object with page, limit, total, and total_pages, and page and limit are the values actually served after clamping. total_pages counts only the pages that can be served; when more recipes match, pages_truncated is true.

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. Each call reads a window of matching recipes at a random position in the whole matching set and shuffles it, so every matching recipe can appear. Pagination is meaningless in random mode: each request is its own independent sample.

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"

Season and occasion queries match what the recipe is served with

A season or occasion filter returns exactly the recipes whose served seasons or occasions array holds the value you asked for (what these fields mean). An empty array means the value is not known, so such a recipe matches no season and no occasion.

• • ?season=Spring, Summer, Fall (alias Autumn) or Winter: recipes served with that season.
• • ?season=Year-Round and ?occasion=Everyday are refused with 400 invalid_parameter, with a reason and the valid_values. Both were written when no evidence was found, so they are not served. Omit the filter to list every recipe.
• • On /api/recipes/by-season and /api/recipes/by-occasion, any other value (?season=Monsoon, ?occasion=Birthday) is refused with 400 invalid_parameter and the accepted valid_values, never an empty page.
• • ?occasion=Weeknight: recipes whose total_time_minutes is 30 or less, waits included.

This applies to /api/recipes/by-season, /api/recipes/by-occasion and /api/recipes/filter.

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.

Taxonomy filters: include & exclude (works on every browse endpoint)

Every /api/recipes/by-* browse endpoint and /api/recipes/filter accept these optional taxonomy filters. They combine with the endpoint’s own filters (diet, exclude_allergens, max_time_minutes, difficulty, has_image, …). All values are case-insensitive, resolved against the two-axis taxonomy, and unknown values are silently ignored (never an error).

curl -X GET "https://api.foodashi.com/api/recipes/by-cuisine?cuisine=Italian&exclude_meal_types=Dessert,Appetizer,Side&exclude_dish_types=Salad&limit=100" \
  -H "X-Api-Key: YOUR_API_KEY"

Unknown parameters are refused

Every /api/recipes/by-* endpoint answers a parameter name it does not read with 400 and code unknown_parameter: unknown_parameters names it and accepted_parameters lists every name that endpoint reads, so a misspelt filter never returns an unfiltered page that looks filtered. The cache buster _ is accepted.

To exclude allergens on any /api/recipes/by-* endpoint, send exclude_allergens (aliases exclude_alg and allergen) with case-insensitive EU-14 names, as on /api/recipes; an unknown name is a 400 with code invalid_allergen. /api/recipes/filter takes exclude_allergens only: the two aliases are refused there with 400 unknown_parameter. /api/recipes/by-ingredients applies the allergen exclusion and the taxonomy filters above before it counts its total and cuts its page.

Browse by Cuisine

Browse recipes filtered by cuisine type. Returns full recipe objects 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/by-cuisine?cuisine=Italian",
    headers={"X-Api-Key": "YOUR_API_KEY"}
)
data = response.json()

GET /api/recipes/by-cuisine?cuisine=Italian&exclude_meal_types=Dessert,Appetizer,Side&exclude_dish_types=Salad&limit=100

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

Nutrient bounds are per serving and compared as numbers. Malformed numbers, an unknown sort, grade or country code and unknown parameters return 400 (code invalid_parameter or unknown_parameter).

Examples

Quick weeknight dinners (under 30 min, Easy)

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": [
    { // the full recipe object, as /api/recipes/details returns it (abridged)
      "id", "title", "title_english", "cuisine", "cuisine_code", "image_url",
      "total_time_minutes", "active_time_minutes", "meal_types", "dish_types",
      "dietary_tags", "allergens", "nutrition", "ingredients", "steps", ... }
  ],
  "filter": { // The parameters 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, "total_pages": 7 }
}

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: 108 valid values

Pass to dish_type=. Describes what the dish structurally is, unlike 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: 81 valid values

Pass to cuisine=. Case-sensitive exact match.

region: 14 valid values

Pass to region=. Sub-continental grouping.

continent: 5 valid values

diet: 21 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. Low-FODMAP is withheld on every recipe: a low-FODMAP rating depends on the amount of each food per serving and on how FODMAPs add up across the meal, and we hold no sourced per-serving FODMAP data. It stays a valid value, matches no recipe, and the response names the reason in withheld_diets.

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: 97 valid values

Pass to cooking_method= or by-cooking-method. Case does not matter. Single value (intersect with other filters for AND). The everyday word for a method is accepted too: baking for baked, roasting for roasted, grilling for grilled, frying for fried, steaming for steamed, and the like. smoking (cold smoke) and smoked (hot smoke) are two methods. Any other value is refused with 400 and the list.

occasion: 5 valid values

Pass to occasion=. Case-insensitive. Weeknight means the whole recipe, waits included, takes 30 minutes or less; the others come from the recipe’s own text and tags. A recipe with no known occasion serves occasions: []. Everyday is refused (what these fields mean).

season: 4 valid values

Pass to season=. Case-insensitive. Autumn is accepted as an alias for Fall. A recipe with no known season serves seasons: [], and Year-Round is refused (what these fields mean).

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. A withheld diet (Low-FODMAP) is a valid value that matches no recipe: the answer is a 200 with no recipes and withheld_diets: [{"diet": "Low-FODMAP", "reason": "..."}]. The same holds for diet= on every endpoint that takes it, and exclude_diets=Low-FODMAP excludes nothing.

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 a maximum total time in minutes (prep + cook + rest, waits included), fastest first. For hands-on time, add max_active_minutes (browse conventions).

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

Browse by Difficulty

Filter recipes by difficulty: Easy, Hard or Expert. Medium is not accepted as a filter value and is refused with 400 invalid_parameter (what these fields mean).

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 the dietary tags recipes are served with, with their counts. Useful for dietary filter UIs. A withheld diet (Low-FODMAP) is served on no recipe, so it is not listed; withheld_diets names it with the reason.

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: the text is matched anywhere in the title, case-insensitive, not only at its start (chi finds "Gnocchi di Patate" and "American Beef Chili").

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

{
  "results": [
    { "id": "50ab7323-f52d-4765-9b0e-06cc2df8b6ce", "title": "Southern Fried Chicken" },
    { "id": "2d0660b3-f5f8-459f-b48e-5fdab657c14c", "title": "Chicken and Leek Pie" }
  ]
}

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=3f8a1c2e-9b4d-4e6f-8a2b-1c3d5e7f9a0b,9c1d2e3f-4a5b-4c6d-8e7f-0a1b2c3d4e5f" \
  -H "X-Api-Key: YOUR_API_KEY"

Similar Recipes

Recipes from the same cuisine, those sharing a dish type with the source first, newest first. Perfect for "You might also like" features. Optional narrowing: diet, meal_type, dish_type and exclude_allergens, with the same rules as /api/recipes.

curl -X GET "https://api.foodashi.com/api/similar?id=3f8a1c2e-9b4d-4e6f-8a2b-1c3d5e7f9a0b" \
  -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 the recipes served with an occasion: Weeknight, Family Meal, Party, Holiday or Meal Prep. See occasions.

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

Browse by Season

Find seasonal recipes for a given time of year. Returns the recipes served with the requested season. A recipe with no known season (seasons: []) is not returned, and Year-Round is refused. 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: a 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/search?q=comfort+food",
    headers={"X-Api-Key": "YOUR_API_KEY"}
)
data = response.json()

Response

Both modes return the same shape: each item of data is the full recipe object (Response Schema) plus similarity, from 0 to 1 rounded to four decimals, or null on text_fallback.

{
  "success": true,
  "query": "comfort food for winter",
  "count": 5,
  "filters_applied": false,
  "data": [
    {
      "id": "3f8a1c2e-9b4d-4e6f-8a2b-1c3d5e7f9a0b",
      "title": "Pot-au-feu",
      "title_english": "Beef and Vegetable Stew",
      "description": "...",
      "image_url": "https://...",
      "total_time_minutes": 210,
      "active_time_minutes": 40,
      "servings": 6,
      "cuisine": "French",
      "cuisine_code": "FR",
      "meal_types": ["Dinner", "Main Course"],
      "dish_types": ["Stew"],
      "difficulty": null,
      "dietary_tags": ["Dairy-Free"],
      "allergens": ["Celery"],
      "nutrition": { "calories": 410, "protein_g": 38.5, ... },
      "ingredients": [ ... ],
      "steps": [ ... ],
      ...
      "ai_generated": true,
      "api_version": "v1",
      "similarity": 0.8123
    }
  ],
  "meta": { "mode": "semantic", "semantic_ranking": true, "tier": "indie" }
}

meta.mode is "semantic" or "text_fallback". If a recipe could not be formatted, the body also carries "partial": true and failed_ids; if the data behind the answer could not be read, the answer is a retryable 503 service_unavailable. The search card’s meal_type and published_at are not part of the recipe: read meal_types[].

Browse by Nutrients

Filter recipes by nutrient ranges. Find high-protein, low-calorie, or custom macro recipes. Every bound is per serving, at least one is required, and each has a snake_case name too (min_calories, max_protein_g, max_saturated_fat_g, max_sugar_g, max_sodium_mg, as on /api/recipes/filter). The recipes come back whole, nutrition included.

curl -X GET "https://api.foodashi.com/api/recipes/by-nutrients?minProtein=25&maxCalories=500&maxSaturatedFat=5" \
  -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"

curl -X GET "https://api.foodashi.com/api/recipes/by-ingredients?ingredients=leek,potato,bacon&match=any&max_active_minutes=30" \
  -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",
      "total_time_minutes": 22,
      "servings": 4,
      "cuisine": "Bangladeshi",
      "cuisine_code": "BD",
      "difficulty": "Easy",
      "dietary_tags": ["Vegan", "Gluten-Free", "Nut-Free", "Soy-Free"],
      "allergens": [],
      "nutrition": { "calories": 190, ... },
      "ingredients": [ ... ],
      "steps": [ ... ],
      ...
    }
  ],
  "filter": {
    "include": ["red onion"],
    "exclude": [],
    "match": "all"
  },
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 10,
    "total_pages": 1
  }
}

Error responses

Recipe Nutrition

Get a recipe's nutrition with the ingredient lines it is computed from: the eight nutrients per serving with their daily value percentages and caloric breakdown, and the same eight per 100 g.

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

nutrition_per_serving carries calories, protein_g, fat_g, saturated_fat_g, carbohydrate_g, fiber_g, sugars_total_g and sodium_mg, plus net_carbs_g, daily_value_percent and caloric_breakdown. nutrition_per_serving.per_100g has the same eight keys per 100 g of the dish, as on the full recipe, each a number or null when the data does not state it (never 0); a ?servings= override never changes it.

Recipe Allergens

Allergen declaration covering all 14 EU-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"

allergen_declaration has the same shape as on the full recipe: framework, note and declaration, an object with contains, may_contain (each with its reason) and hidden_sources, or null. Here hidden_sources leaves out ingredients allergen_sources already names.

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"

beverage_pairing carries six lists of strings, each always present (empty when there is nothing of that kind): wine, beer, cocktails, non_alcoholic, spirits and recommendations. A recipe without a pairing returns null.

beverage_pairing is a paid field (Indie plan and above). If it is ever served locked, it is the locked marker and note reads “Beverage pairings are included from the Indie plan.” In the Test Kitchen the body also carries "field_plans": {"beverage_pairing": "indie"}.

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"

Each line carries original_quantity and scaled_quantity (numbers, or null when the line has no usable amount), the edible grams the nutrition scales with (original_gram_weight, scaled_gram_weight), scaled_purchase_gram_weight, the scaled mass to buy (bone-in, shell-on, undrained; equal to scaled_gram_weight when nothing is removed before eating), and text, the scaled line as a cook reads it.

Taste Profile

6-axis taste profile rated 1-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

The recipe's climate footprint: kg CO2 equivalent per serving and per recipe, estimated from each ingredient's weight and a climate factor for its food class. Also the plant-based share of the recipe's weight, the ingredients that contribute most, and how much of the recipe the estimate covers. No AI is involved: the same recipe always gives the same number.

• Scope: ingredients from farm to consumer, packaging and transport included; home cooking energy excluded. An estimate for comparing dishes, not a certified label.
• coverage: the share of the recipe's weight (water excluded) that has a climate factor. An ingredient we cannot place is listed in uncovered_ingredients and never guessed.
• food_class: the food class each top contributor was costed as, a readable label such as beef, cheese, chocolate or milk or white chocolate. Milk and white chocolate count as animal-based in plant_based_share.
• Source: climate factors from ADEME AGRIBALYSE v3.2 (see Data Sources).

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

{
  "id": "…", "title": "Bánh tôm", "title_english": "Vietnamese Fried Shrimp and Pork Cakes",
  "sustainability": {
    "co2e_kg_per_serving": 0.49, "co2e_kg_total": 1.96, "servings": 4,
    "plant_based_share": 0.59, "coverage": 1,
    "top_contributors": [
      { "ingredient": "shrimp", "food_class": "shrimp, crab or lobster", "co2e_kg": 1.33, "share": 0.68 }
    ],
    "uncovered_ingredients": [],
    "scope": "Ingredients from farm to consumer, packaging and transport included; home cooking energy excluded.",
    "method": "Estimate: each ingredient's weight times a climate factor for its food class …"
  }
}

Medical Cautions

Medical caution flags for conditions like diabetes, hypertension, gout, and kidney disease. Its dietary_tags are the tags the recipe is served with everywhere, and never include a withheld claim: Low-FODMAP is withheld on every recipe.

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"

The comparison array is not guaranteed to follow the order of ids: match each entry to your request by its id.

Report a Recipe

Let the people using your app tell us when a recipe looks wrong. Reporting is free on every plan, Hobby included: it costs 0 credits and still works when your key is over its monthly quota. Reports of a wrong allergen or a wrong diet tag are safety reports and alert the Foodashi team straight away, so the correction reaches every app that shows the recipe.

The unversioned path /api/recipes/:id/reports is the same endpoint. Send reports from your server like every other call: your API key never belongs in client-side code.

Request body (JSON)

No other field is accepted: an unknown field returns 400 invalid_report naming it.

Reasons

Limits and duplicates

• • Each API key can file 20 reports per hour and 200 per 24 hours. Over either limit the answer is 429 report_limit_exceeded with a Retry-After header.
• • The same key reporting the same recipe again for at least one of the same reasons within 24 hours gets the existing report back (200, "duplicate": true). Nothing new is stored and it does not count toward the limits, so a double tap in your app is harmless.
• • Reports never use your monthly credits, and they keep working when your key is over its monthly quota.

curl -X POST "https://api.foodashi.com/api/v1/recipes/b1a2c3d4-e5f6-7890-abcd-ef1234567890/reports" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reasons": ["allergen_wrong"], "comment": "The sauce uses fish sauce but Fish is not listed.", "end_user_ref": "usr_7f3a92"}'

Responses

{
  "report_id": "5d0c7e8a-1f2b-4c3d-9e4f-6a7b8c9d0e1f",
  "status": "received",
  "duplicate": false
}

{
  "report_id": "5d0c7e8a-1f2b-4c3d-9e4f-6a7b8c9d0e1f",
  "status": "received",
  "duplicate": true
}

{
  "error": "Invalid report",
  "code": "invalid_report",
  "field": "comment",
  "message": "comment is required when reasons includes 'other' ..."
}

{
  "error": "Report limit reached",
  "code": "report_limit_exceeded",
  "message": "This API key reached its limit of 20 reports per hour ...",
  "window": "hour",
  "limit": 20,
  "retry_after": 1260
}

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 autocomplete for ingredient search bars: names that start with the query come first, then names that contain it anywhere. 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",
      "food_group_name": "Vegetables and Vegetable Products",
      "category": "Produce",
      "ingredient_type": "raw"
    },
    {
      "id": "f67dbb93-479b-4ea1-8a50-d6dc2cc33771",
      "name": "Red Onions",
      "food_group": "11",
      "food_group_name": "Vegetables and Vegetable Products",
      "category": "Produce",
      "ingredient_type": "raw"
    }
  ],
  "query": "red onion",
  "count": 2
}

query and count come with every answer to a query of 2 characters or more; the empty answer to a shorter one carries results only.

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_name": "breast", "gram_weight": 174 }
  ],
  "source": "Blended: USDA SR Legacy + CIQUAL (France)",
  "license": "Multiple (see sources)",
  "license_url": null,
  "attribution_required": true,
  "sources": [
    { "name": "USDA SR Legacy", "license": "CC0-1.0 (U.S. public domain)", "license_url": "https://creativecommons.org/publicdomain/zero/1.0/", "attribution": "...", "source_url": "https://fdc.nal.usda.gov" },
    { "name": "CIQUAL (France)", "license": "Licence Ouverte / Open Licence (ANSES)", "license_url": "...", "attribution": "...", "source_url": "https://ciqual.anses.fr" }
  ]
}

/api/ingredients/search results carry the same five fields. Open Food Facts product rows are served only by /api/barcode, with its ODbL notice. Rows from the Indian Nutrient Databank (INDB) are never served: every by-id ingredient endpoint answers 404 for them, as for an unknown id.

In nutrition_per_100g, a value the source does not state is null, never 0; a measured 0 stays 0.

Barcode Lookup

Look up a packaged product by its UPC/EAN barcode and get its name, brand, and per-100g nutrition (energy, protein, fat, carbs, sodium, fiber, saturated fat, sugars), normalized to Foodashi's nutrient model. Data sourced from Open Food Facts under the ODbL; community-sourced nutrition is flagged with confidence 0.7. Results are cached. Every response carries the credit, the licence and a link to the product page (see Data licensing below).

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

{
  "barcode": "3017620422003",
  "product_name": "Nutella",
  "brand": "Ferrero, Nutella, Yum yum",
  "country": "france",
  "nutrition": {
    "energy_kcal": 539,
    "protein": 6.3,
    "total_fat": 30.9,
    "carbohydrate": 57.5,
    "sodium": 0.0428,
    "fiber": null,
    "saturated_fat": 10.6,
    "sugars_total": 56.3
  },
  "nutrition_confidence": 0.7,
  "nutrition_gaps": ["fiber"],
  "matched_canonical_id": null,
  "data_origin": "openfoodfacts_live",
  "source": "openfoodfacts",
  "attribution": "Data from Open Food Facts (ODbL)",
  "attribution_url": "https://world.openfoodfacts.org",
  "license": "ODbL-1.0",
  "license_url": "https://opendatacommons.org/licenses/odbl/1-0/",
  "product_url": "https://world.openfoodfacts.org/product/3017620422003",
  "cached_at": "2026-06-25T...",
  "image_url": "https://images.openfoodfacts.org/images/products/301/762/042/2003/front_en.879.400.jpg",
  "image_small_url": "https://images.openfoodfacts.org/images/products/301/762/042/2003/front_en.879.200.jpg",
  "image_license": "CC BY-SA 3.0",
  "image_attribution": "Open Food Facts",
  "image_source": "https://world.openfoodfacts.org/product/3017620422003"
}

Nutrition is per 100 g, with sodium in grams per 100 g. A nutrient the product data does not state is null and is named in nutrition_gaps, never 0; a stated 0 stays 0.

Image licensing. All five image fields are null together when the product has no photo. Product images are Open Food Facts photos under CC BY-SA 3.0 (a separate license from the ODbL nutrition data). If your app displays the image you must attribute "Open Food Facts", keep the CC BY-SA 3.0 credit, link back (the image_attribution, image_license, and image_source fields carry exactly what you need), and show the image unmodified.

Data licensing. Product data is from Open Food Facts under the Open Database License (ODbL). If your app shows or redistributes it, credit Open Food Facts and keep the licence; the attribution, license, license_url, attribution_url and product_url fields carry what you need. Local hits (data_origin "openfoodfacts_export") carry no brand or photo: brand, country, quantity and the five image fields are null.

Errors. A code that is not a GTIN-8, UPC-A (12 digits), EAN-13 or GTIN-14 with a valid check digit returns 400 invalid_barcode before any lookup is made. An unknown product returns 404. When a lookup needs the live Open Food Facts service and its rate limit is reached, the answer is 503 with code upstream_rate_limited and a Retry-After header in seconds; retry after it.

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"

Errors. A unit the API does not know (parsec) returns 400 with code unknown_unit. A known unit this food has no portion or density data for (a cup of raw chicken breast) returns 404 with code no_conversion_data, rather than a guess. Both name the unit and list the units this food does convert in available_units, with a hint.

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()

{
  "ingredient": { "id": "e595c015-faf4-4662-9ec9-2f2fe5589a4b", "name": "Chicken, broiler or fryers, breast, skinless, boneless, meat only, raw", "food_group": "5" },
  "substitutes": [
    {
      "id": "445de72a-4cf2-4526-82f5-2a5a0a4eaae5",
      "name": "Turkey Meat",
      "slug": "turkey-whole-meat-only-raw",
      "food_nature": "sr_legacy_food",
      "food_group": "5",
      "nutrition_per_100g": { "calories": 115, "protein": 22.6, "carbohydrates": 0.14, "fat": 1.93, "fiber": 0, "sugar": 0.07, "sodium": 118 },
      "similarity": 0.973,
      "similarity_score": 12,
      "nutrition_diff": { "calories": -5, "protein": 0.1, "fat": -0.7, "carbohydrates": 0.1 }
    }
  ]
}

Up to 10 cooking ingredients (never branded products) from the same food group, most similar first. similarity runs from 0 to 1 (higher is closer); similarity_score is the distance behind it (lower is closer). nutrition_diff is the substitute minus the original, per 100 g. An ingredient with no energy value on record returns an empty substitutes list with a note.

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",
      "total_time_minutes": 66,
      "servings": 6,
      "cuisine": "Sri Lankan",
      "difficulty": null,
      "dietary_tags": ["Vegan", "Gluten-Free"],
      "allergens": ["Mustard"],
      "nutrition": { "calories": 215, ... },
      "ingredients": [ ... ],
      "steps": [ ... ],
      ...
    }
  ],
  "pagination": { "page": 1, "limit": 10, "total": 10, "total_pages": 1 },
  "match_meta": { "fallback_attempted": false, "fallback_used": false }
}

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).
• • Each item of recipes is the full recipe object; a recipe that could not be formatted is named in failed_ids with "partial": true, and a failed read is a retryable 503 service_unavailable.

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, it 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. It 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-..."}'

Response

{
  "recipe_id": "3f8a1c2e-9b4d-4e6f-8a2b-1c3d5e7f9a0b",
  "title": "Pot-au-feu",
  "title_english": "Beef and Vegetable Stew",
  "source": "stored_analysis",
  "classification": {
    "cuisine": "French",
    "meal_types": ["Dinner", "Main Course"],
    "dish_types": ["Stew"],
    "occasions": ["Family Meal"],
    "seasons": ["Winter"],
    "cooking_methods": ["Simmering"],
    "difficulty": null,
    "protein_source": "Beef"
  },
  "nutrition": { /* same nutrition object as /api/recipes/details */ },
  "allergens": ["Celery"],
  "allergen_declaration": { /* EU 1169/2011 declaration */ },
  "dietary_tags": ["Dairy-Free"],
  "dietary_tag_confidence": { "Dairy-Free": 0.95 },
  "nutrimetric": { /* score and grade */ }
}

dietary_tag_confidence maps each tag to a confidence from 0 to 1. To analyse an ad hoc ingredient list instead, send {"ingredients": [{"ingredient_id": "<canonical ingredient UUID>", "amount": 250, "unit": "g"}], "servings": 4} (resolve names to ids with /api/ingredients/search). Send one body or the other, not both.

The ingredients body weighs masses only: unit is g, kg, mg, lb or oz, or a spelling of one such as grams or ounces (case-insensitive), and amount is a number from 0. A volume or piece unit (cup, tbsp, piece) is refused with a 400 invalid_parameter that lists supported_units: send grams, or use /api/nutrition/calculate, which weighs volumes and pieces from the food's own data. In the breakdown, a nutrient a food does not state is null on its line and in every total it enters, never 0.

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"]}'

Or pass {"ids": ["<canonical ingredient UUID>", ...]} (max 50) to look up by id; results come back in your order with match_type "id". Names are also limited to 50 per call. Each found result carries ingredient.nutrition_per_100g, the values per 100 g by nutrient key; a value the source does not state is null, never 0.

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 Daily Values for 31 nutrients, based on a 2,000 calorie diet (21 CFR 101.9, the current Nutrition Facts rule). A nutrient with no Daily Value, such as total sugars or trans fat, returns value: null with a note. The 50 g sugar reference applies to added sugars only, so recipe responses report daily_value_percent.sugars_total_g as null.

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

Personalized Daily Needs

Estimate a person's daily calorie and macro targets (BMR, TDEE, protein/fat/carbohydrate) using the Mifflin-St Jeor equation. Deterministic and free of AI. Unlike Daily Values (the fixed FDA labeling reference), this personalizes to the individual. All inputs are optional: supply all five core inputs (age, weight, height, sex, activity level) for a personalized result; if any are missing, sensible defaults are applied, the result is flagged estimated, and each defaulted field is named in assumptions. This is always an estimate from a population formula, not medical or dietary advice.

curl -X POST "https://api.foodashi.com/api/nutrition/daily-needs" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"age":30,"weight_kg":75,"height_cm":180,"sex":"male","activity_level":"moderate","goal":"maintain"}'

{
  "precision": "personalized",
  "estimated": false,
  "bmr_kcal": 1730,
  "tdee_kcal": 2682,
  "target_kcal": 2682,
  "goal": "maintain",
  "macros": { "protein_g": 120, "fat_g": 89, "carbohydrate_g": 350 },
  "targets": { "fiber_g": 38, "saturated_fat_max_g": 30, "added_sugars_max_g": 67, "sodium_max_mg": 2300 },
  "targets_note": "Fiber is a daily minimum (14 g per 1,000 kcal). Saturated fat and added sugars are upper limits (10% of calories). Sodium is the fixed FDA upper reference of 2,300 mg/day and is NOT personalized. For the full vitamin and mineral reference table, use GET /api/nutrition/daily-values.",
  "inputs_used": { "age": 30, "weight_kg": 75, "height_cm": 180, "sex": "male", "activity_level": "moderate", "activity_label": "Moderate exercise 3-5 days/week" },
  "assumptions": [],
  "method": "Mifflin-St Jeor BMR x activity factor. Protein 1.6 g/kg, fat 30% of calories, carbohydrate remainder.",
  "disclaimer": "Estimate only, not medical or dietary advice. ..."
}

Inputs outside what the equation describes are refused with a 400, never answered with a negative or empty target: a combination whose BMR is not positive, or whose protein (1.6 g per kg) and fat (30% of calories) already exceed the calorie target. activity_level must be one of sedentary, light, moderate, active or very_active.

Calculate Nutrition

Send a structured ingredient list and get complete nutrition back. Every name is resolved against our canonical ingredient database, then run through the same nutrition engine that powers the recipe catalog, so you get per-serving, per-100g and whole-recipe figures plus a NutriMetric grade. It makes no AI calls, which means it is fast, repeatable, and costs 5 rather than 175.

curl -X POST "https://api.foodashi.com/api/nutrition/calculate"   -H "X-Api-Key: YOUR_API_KEY"   -H "Content-Type: application/json"   -d '{"ingredients":[{"name":"chicken breast","grams":300},{"name":"basmati rice","grams":200},{"name":"olive oil","amount":1,"unit":"tbsp"}],"servings":2}'

Response

Returns per_serving, per_100g and total nutrition, a nutrimetric grade, coverage and confidence, and an ingredients breakdown showing exactly which canonical food each name matched, so you can see why a number came out the way it did, and which items we could not match.

If no name matches a known food, or no matched food has nutrient data, the answer is 422 with code unprocessable_entity. If a nutrient read fails, the answer is a 503 with code service_unavailable (retry), never a total that counts the food as zero.

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 to 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"}'

Natural-Language Meal Logging

Send free text describing what someone ate and get a per-item breakdown of foods with estimated grams and an 8-nutrient profile each, plus a summed total. This is an AI endpoint (one Gemini parse followed by deterministic nutrition lookup) billed at 85 credits. It is stateless: it computes and returns, it stores nothing. Portions are inferred from the text and some nutrition values are AI-estimated (flagged at nutrition_confidence 0.7, versus 1.0 for USDA values). Free and Indie developers can try it in the Test Kitchen on the trial budget. Limits: 500-character max input, 20 items max per call.

curl -X POST "https://api.foodashi.com/api/nutrition/log" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"2 scrambled eggs, a slice of whole wheat toast, and a cup of orange juice"}'

{
  "input": "2 scrambled eggs, a slice of whole wheat toast, and a cup of orange juice",
  "items": [
    {
      "food": "egg",
      "quantity": 2,
      "unit": "medium",
      "grams": 100,
      "matched_canonical_id": "ec721176-...",
      "matched_name": "Egg, whole, raw, fresh",
      "match_confidence": 1,
      "nutrition": { "energy_kcal": 143, "protein": 12.6, "total_fat": 9.5, "carbohydrate": 0.7, "sodium": 142, "fiber": 0, "saturated_fat": 3.1, "sugars_total": 0.4 },
      "nutrition_confidence": 1
    },
    {
      "food": "whole wheat toast",
      "quantity": 1,
      "unit": "slice",
      "grams": 30,
      "matched_name": "Whole Wheat Toast",
      "match_confidence": 1,
      "nutrition": { "energy_kcal": 102, "protein": 1.8, "total_fat": 1.2, "carbohydrate": 19.7, "sodium": 132, "fiber": 2.8, "saturated_fat": 0.3, "sugars_total": 1.7 },
      "nutrition_confidence": 1
    },
    {
      "food": "orange juice",
      "quantity": 1,
      "unit": "cup",
      "grams": 240,
      "matched_name": "Orange juice, raw",
      "match_confidence": 1,
      "nutrition": { "energy_kcal": 113, "protein": 1.6, "total_fat": 0.5, "carbohydrate": 26.4, "sodium": 2.4, "fiber": 0.5, "saturated_fat": 0.1, "sugars_total": 20.8 },
      "nutrition_confidence": 1
    }
  ],
  "total": { "energy_kcal": 358, "protein": 16, "total_fat": 11.2, "carbohydrate": 46.8, "sodium": 276.4, "fiber": 3.3, "saturated_fat": 3.5, "sugars_total": 22.9 },
  "item_count": 3,
  "unresolved": [],
  "confidence": 1,
  "disclaimer": "Portions inferred from text; nutrition is per-ingredient estimated or USDA. Stateless, nothing is stored.",
  "source": "foodashi"
}

Errors. If the meal text cannot be parsed, the answer is 502 (rephrase it). If a food lookup or a nutrient read fails after the parse, the answer is 503 service_unavailable with "retryable": true, never a meal with that food counted as zero or as unmatched, and nothing is cached. The AI parse has already run, so, as for any error after AI tokens were billed, the call’s credits stay spent.

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"

{
  "original": { "amount": 1, "unit": "cup" },
  "converted": { "amount": 125, "unit": "g" },
  "grams": 125,
  "ingredient": "flour"
}

• • Every answer carries grams, the weight of the original amount, also when to is g.
• • US volume units (fl oz, pint, quart, gallon) follow the ingredient’s density through cups and tablespoons, so a pint of flour weighs what two cups of flour weigh.
• • A piece unit (piece, whole, small, medium, large) needs an ingredient whose piece weight is known, such as ingredient=egg; without one it returns 400.
• • A unit the API does not recognise, on either side, returns 400 with code unknown_unit, a hint and the supported_units. No weight is guessed.
• • Large amounts are converted in full: there is no cap on the result.

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 21 dietary tags, grouped by category: lifestyle, low-carb, allergen-free, nutritional, regional and other. These are exactly the values diet= accepts. Each entry carries withheld: it is true for Low-FODMAP, which is accepted but served on no recipe, with the reason in withheld_diets.

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

Cuisine List

All 81 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, NutriMetric scoring, and the recipe's climate footprint (sustainability, the same fields as Sustainability).

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: from the 21 dietary tags (Vegan, Keto, Gluten-Free, etc.)
• nutrimetric: Proprietary nutrition grade (A to 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."}'

Errors. If a nutrient read fails after the recipe is extracted, the answer is 503 service_unavailable with "retryable": true, never totals that leave a food out or count it as zero. The AI extraction has already run, so the call’s credits stay spent.

Analyze Recipe URL

Fetch a recipe from any URL, extract it with AI, then run the full nutrition + allergen + NutriMetric pipeline, with the recipe's climate footprint (sustainability). 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"}'

Errors. 502 when the page cannot be fetched, 422 when no recipe is found on it. If a nutrient read fails after the recipe is extracted, the answer is 503 service_unavailable with "retryable": true, never totals that leave a food out or count it as zero. The AI extraction has already run, so the call’s credits stay spent.

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}'

Matched recipes. Each item of data.matched_recipes is the full recipe object, under your plan. To trim it, add fields to the query string (/api/recognize/image?fields=title,image_url,nutrition); it is checked before the image is analysed, so a typo is a free 400 unknown_field (Trimming the Recipe).

Partial answers. If the recipe lookup fails after the dish is identified, the identification is still served with matched_recipes: [], and data carries "partial": true and errors: [{"code": "service_unavailable", "field": "matched_recipes", "message": "...", "retryable": true}]. Both fields appear only then: an empty matched_recipes without them means no recipe matched.

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"}'

Suggested recipes. Each item of data.suggested_recipes is the full recipe object, under your plan. To trim it, add fields to the query string (/api/recognize/ingredients?fields=title,ingredients); it is checked before the image is analysed, so a typo is a free 400 unknown_field (Trimming the Recipe).

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}]}]}}'

Each meal is bought for its servings, a number from 1 to 100, or for the recipe's own servings when you leave it out; repeated meals of one recipe add up, never capped. Any other servings value (0, negative, above 100, a string) is refused with a 400 invalid_parameter naming meal_plan.days[i].meals[j].servings.

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 '{"recipe_ids": ["uuid-1", "uuid-2"], "unit_system": "metric", "preferences": {"budget": "normal", "diet": "none"}}'

A meal_plan body (instead of recipe_ids) follows the same servings rule as Shopping List from Meal Plan: 1 to 100 per meal, or omitted for the recipe's own servings.

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

Public totals for the catalogue, with no API key needed: published recipes, ingredients, nutrients, allergens, diets and cuisines. It serves totals only, no breakdown by cuisine, diet or anything else. total_diets and total_cuisines are the lengths of the lists /api/diets and /api/cuisines serve. Rate limited per client address; the figures are cached for up to five minutes.

{
  "total_recipes": 6596,
  "total_ingredients": 1069820,
  "total_nutrients": 64,
  "total_allergens": 14,
  "total_diets": 21,
  "total_cuisines": 81,
  "data_sources": 8,
  "api_version": "v1",
  "pipeline_version": "3.0-pipeline",
  "status": "operational"
}

api_version is the API contract version. pipeline_version is a build label, not part of the contract. total_ingredients is an estimate over the full ingredient table.

Response Schema

Example response from /api/recipes/details, as a paid plan receives it. Every endpoint that returns recipes returns this same object (which ones, and how to trim it). nutrimetric and beverage_pairing are paid fields (Indie plan and above): see Paid Fields for what a Hobby key and the Test Kitchen receive.

{
  "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,
  "active_time_minutes": 115,
  "total_time_minutes": 115,
  "requires_advance_preparation": false,
  "untimed_minutes": 17,
  "overlap_minutes": 0,
  "servings": 4,
  "cuisine": "Mexican",
  "cuisine_code": "MX",
  "meal_types": ["Dinner", "Main Course"],
  "dish_types": ["Stew"],
  "difficulty": null,
  "cost_level": 2,
  "protein_source": ["Beef"],
  "tags": ["authentic", "comfort-food"],
  "cooking_methods": ["Braising", "Simmering"],
  "occasions": [],
  "seasons": ["Winter", "Fall"],
  "equipment": ["Dutch Oven", "Knife"],
  "dietary_tags": ["Gluten-Free"],
  "allergens": ["Celery"],
  "allergen_declaration": {
    "framework": "EU Regulation 1169/2011 (14 allergens)",
    "declaration": {
      "contains": ["Celery"],
      "may_contain": [],
      "hidden_sources": [{ "allergen": "Celery", "hidden_in": ["beef stock"] }]
    },
    "note": "Derived from ingredient data to support your own labelling; not a legal declaration."
  },

  "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,
    "net_carbs_g": 34.7,
    "daily_value_percent": { "calories": 23, "protein_g": 70, "sodium_mg": 37, ... },
    "caloric_breakdown": { "percent_protein": 30, "percent_fat": 34, "percent_carbs": 36 },
    "per_100g": { "calories": 98, "protein_g": 7.6, "fat_g": 3.9, "saturated_fat_g": 1.1, "carbohydrate_g": 9.3, "fiber_g": 1.8, "sugars_total_g": 1.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,
    "scale": "1-10"
  },

  "storage": {
    "fridge_days": 3,
    "freezer_days": 90,
    "instructions": "Cool, then refrigerate in an airtight container. Reheat on the stovetop until simmering..."
  },

  "beverage_pairing": { "wine": ["Tempranillo"], "beer": ["Negra Modelo"], "cocktails": ["Michelada"], "non_alcoholic": ["Agua de jamaica"], "spirits": [], "recommendations": ["A malty Negra Modelo matches the beef broth without overpowering the vegetables."] },

  "ingredients": [
    {
      "text": "450 g Beef chuck",
      "name": "Beef chuck",
      "quantity": 450,
      "unit": "g",
      "is_main": true,
      "preparation": "cubed",
      "optional": false,
      "gram_weight": 450,
      "purchase_gram_weight": 450
    },
    {
      "text": "900 g beef shank, bone-in",
      "name": "beef shank, bone-in",
      "quantity": 900,
      "unit": "g",
      "is_main": true,
      "preparation": null,
      "optional": false,
      "gram_weight": 630,
      "purchase_gram_weight": 900
    }
  ],

  "steps": [
    {
      "step": 1,
      "text": "Sear the beef...",
      "duration_minutes": 8,
      "temperature": null,
      "heat_level": "medium-high"
    },
    {
      "step": 2,
      "text": "Simmer until the beef is tender...",
      "duration_minutes": 90,
      "temperature": { "value": 95, "unit": "c" },
      "heat_level": null
    }
  ],

  "ai_generated": true,
  "api_version": "v1",
  "provenance": { "text": "ai_generated", "ingredients": "ai_generated_db_resolved", "nutrition": "database_computed", "image": "ai_generated" }
}

Field types worth knowing.

• allergen_declaration.declaration is an object (contains, may_contain with a reason for each, hidden_sources), never a sentence, or null. Render your own wording from it.
• ingredients[].quantity is a number (fractions as decimals, such as 0.5), "" when the line gives no amount, or null for an unresolved line. It is never 0 for an unknown amount.
• ingredients[].gram_weight is the edible grams the nutrition is computed on; purchase_gram_weight is the mass of the quantity as written, to buy (bone-in, shell-on, undrained), and equals gram_weight when nothing is removed before eating. Use it for shopping lists.
• ingredients[].nutrition_estimated is true when that line’s nutrition rests on an AI estimate, because no open food-composition table carries the food, false when it rests on table values, and null when it cannot be told. provenance.nutrition_estimated_lines counts the estimated lines of the recipe.
• steps[].temperature is {value, unit} (unit is c or f; a range adds max_value) or null, and a freezer temperature keeps its sign (-18); a heat named in words such as medium-high (or several, joined in order) is in heat_level, never turned into a number, and heat_level is null when the step states degrees or no heat.
• storage is {fridge_days, freezer_days, instructions}: days in the fridge, days in the freezer (null when the dish does not freeze) and how to store and reheat it; {} when the recipe has no storage guidance.
• taste_profile scores each of the six tastes from 1 to 10.
• Nutrient values can be null when a value is unknown, which is different from 0.
• nutrition.per_100g has the same eight keys as the per-serving values (calories, protein_g, fat_g, saturated_fat_g, carbohydrate_g, fiber_g, sugars_total_g, sodium_mg), per 100 g of the dish, each a number or null when the data does not state it, never 0.
• cuisine_code is the ISO 3166-1 alpha-2 code of the cuisine’s country, or null when the cuisine has no code; never an empty string.