{"openapi":"3.1.0","info":{"title":"Food & Nutrition API","description":"\nBilingual (English + Polish) nutrition and recipes API.\n\n**Database:**\n- 3000+ ingredients with full macros per 100 g (energy, protein, carbs, sugars, fats, saturated fats, fiber, salt, sodium) and tags (vegan, gluten free, high protein, low GI, etc.)\n- 370 recipes with ingredient lists (grams), step-by-step instructions, per-serving macros, and tags (breakfast, lunch, dinner, after workout, etc.)\n\n**Highlights:**\n- Fuzzy search in EN and PL\n- Filter recipes by macros, tags, included or excluded ingredients (allergens)\n- Nutrition calculator — provide ingredients + grams, get full nutrition breakdown\n- \"What can I cook\" — pass ingredients you have, get ranked recipes\n- Macro-target matcher — find recipes matching your kcal/protein goals\n- Scaled servings — get a recipe re-portioned for any serving count\n\nAll endpoints return JSON. Authentication is handled by the API marketplace (RapidAPI) gateway, which forwards the X-RapidAPI-Proxy-Secret header. Subscribe at https://rapidapi.com to obtain access.\n","contact":{"name":"Food API","email":"api@yourfoodapi.com"},"license":{"name":"Commercial"},"version":"1.0.0"},"paths":{"/ingredients":{"get":{"tags":["ingredients"],"summary":"List ingredients","description":"List ingredients with optional filters and pagination. Over 3000 ingredients available.","operationId":"listIngredients","parameters":[{"name":"category","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by category","title":"Category"},"description":"Filter by category"},{"name":"tags","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Filter by tag (repeat for multiple, AND logic)","title":"Tags"},"description":"Filter by tag (repeat for multiple, AND logic)"},{"name":"lang","in":"query","required":false,"schema":{"type":"string","pattern":"^(en|pl)$","description":"Language for category/tags filters","default":"en","title":"Lang"},"description":"Language for category/tags filters"},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Fuzzy search by name (EN+PL)","title":"Search"},"description":"Fuzzy search by name (EN+PL)"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1,"title":"Page"}},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"default":25,"title":"Page Size"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_Ingredient_"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/ingredients/categories":{"get":{"tags":["ingredients"],"summary":"List ingredient categories","operationId":"listIngredientCategories","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/ingredients/tags":{"get":{"tags":["ingredients"],"summary":"List ingredient tags","operationId":"listIngredientTags","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/ingredients/search":{"get":{"tags":["ingredients"],"summary":"Fuzzy search ingredients","operationId":"searchIngredients","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1,"description":"Search query (EN or PL)","title":"Q"},"description":"Search query (EN or PL)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"default":25,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Ingredient"},"title":"Response Searchingredients"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/ingredients/random":{"get":{"tags":["ingredients"],"summary":"Get a random ingredient","description":"Returns a single random ingredient. Useful for daily food picks, app demos, and discovery features.","operationId":"getRandomIngredient","parameters":[{"name":"category","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Restrict to a category (EN name)","title":"Category"},"description":"Restrict to a category (EN name)"},{"name":"tags","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Require these tags (AND, EN names)","title":"Tags"},"description":"Require these tags (AND, EN names)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Ingredient"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/ingredients/{ingredient_id}":{"get":{"tags":["ingredients"],"summary":"Get ingredient by id","operationId":"getIngredient","parameters":[{"name":"ingredient_id","in":"path","required":true,"schema":{"type":"integer","title":"Ingredient Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Ingredient"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/recipes":{"get":{"tags":["recipes"],"summary":"List recipes","description":"List recipes with rich filters: tags, macros, included/excluded ingredients.","operationId":"listRecipes","parameters":[{"name":"tags","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Filter by tag (AND logic)","title":"Tags"},"description":"Filter by tag (AND logic)"},{"name":"lang","in":"query","required":false,"schema":{"type":"string","pattern":"^(en|pl)$","default":"en","title":"Lang"}},{"name":"include_ingredients","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Only recipes containing ALL these ingredient names","title":"Include Ingredients"},"description":"Only recipes containing ALL these ingredient names"},{"name":"exclude_ingredients","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Exclude recipes containing ANY of these ingredients (allergens)","title":"Exclude Ingredients"},"description":"Exclude recipes containing ANY of these ingredients (allergens)"},{"name":"max_kcal","in":"query","required":false,"schema":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}],"title":"Max Kcal"}},{"name":"min_kcal","in":"query","required":false,"schema":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}],"title":"Min Kcal"}},{"name":"min_protein","in":"query","required":false,"schema":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}],"title":"Min Protein"}},{"name":"max_carbs","in":"query","required":false,"schema":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}],"title":"Max Carbs"}},{"name":"max_fats","in":"query","required":false,"schema":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}],"title":"Max Fats"}},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Fuzzy search by recipe name","title":"Search"},"description":"Fuzzy search by recipe name"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1,"title":"Page"}},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"default":20,"title":"Page Size"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page_Recipe_"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/recipes/tags":{"get":{"tags":["recipes"],"summary":"List recipe tags","operationId":"listRecipeTags","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/recipes/search":{"get":{"tags":["recipes"],"summary":"Fuzzy search recipes by name","operationId":"searchRecipes","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1,"title":"Q"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"default":25,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Recipe"},"title":"Response Searchrecipes"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/recipes/by-ingredients":{"get":{"tags":["recipes"],"summary":"Find recipes you can cook with what you have","description":"Rank recipes by how many of your ingredients they use. Pass ingredients you have via repeated `have` query params. Returns recipes sorted by match ratio, with missing ingredient list.","operationId":"findRecipesByIngredients","parameters":[{"name":"have","in":"query","required":true,"schema":{"type":"array","items":{"type":"string"},"minItems":1,"description":"Ingredients you have (EN or PL)","title":"Have"},"description":"Ingredients you have (EN or PL)"},{"name":"min_ratio","in":"query","required":false,"schema":{"type":"number","maximum":1,"minimum":0,"description":"Min fraction of recipe ingredients you must have","default":0.5,"title":"Min Ratio"},"description":"Min fraction of recipe ingredients you must have"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"default":20,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true},"title":"Response Findrecipesbyingredients"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/recipes/by-macros":{"get":{"tags":["recipes"],"summary":"Find recipes matching macro targets","description":"Return recipes closest to provided macro targets (kcal/protein/carbs/fats).","operationId":"findRecipesByMacros","parameters":[{"name":"kcal","in":"query","required":false,"schema":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}],"title":"Kcal"}},{"name":"protein","in":"query","required":false,"schema":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}],"title":"Protein"}},{"name":"carbs","in":"query","required":false,"schema":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}],"title":"Carbs"}},{"name":"fats","in":"query","required":false,"schema":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}],"title":"Fats"}},{"name":"tolerance","in":"query","required":false,"schema":{"type":"number","maximum":1,"minimum":0,"description":"Allowed fractional deviation","default":0.2,"title":"Tolerance"},"description":"Allowed fractional deviation"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"default":20,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Recipe"},"title":"Response Findrecipesbymacros"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/recipes/random":{"get":{"tags":["recipes"],"summary":"Get a random recipe","description":"Returns a single random recipe. Perfect for 'recipe of the day' features, app demos, and meal inspiration.","operationId":"getRandomRecipe","parameters":[{"name":"tags","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Require these tags (AND, EN names, e.g. breakfast, vegan)","title":"Tags"},"description":"Require these tags (AND, EN names, e.g. breakfast, vegan)"},{"name":"max_kcal","in":"query","required":false,"schema":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}],"description":"Cap energy per serving","title":"Max Kcal"},"description":"Cap energy per serving"},{"name":"min_protein","in":"query","required":false,"schema":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}],"description":"Minimum protein per serving","title":"Min Protein"},"description":"Minimum protein per serving"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Recipe"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/recipes/{recipe_id}":{"get":{"tags":["recipes"],"summary":"Get recipe by id","operationId":"getRecipe","parameters":[{"name":"recipe_id","in":"path","required":true,"schema":{"type":"integer","title":"Recipe Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Recipe"}}}},"404":{"description":"Not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/recipes/{recipe_id}/scaled":{"get":{"tags":["recipes"],"summary":"Get recipe scaled to N servings","description":"Returns the recipe with ingredient amounts and per-serving macros recalculated for the requested servings.","operationId":"getScaledRecipe","parameters":[{"name":"recipe_id","in":"path","required":true,"schema":{"type":"integer","title":"Recipe Id"}},{"name":"servings","in":"query","required":true,"schema":{"type":"integer","maximum":50,"minimum":1,"title":"Servings"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Recipe"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/nutrition/calculate":{"post":{"tags":["nutrition"],"summary":"Calculate nutrition for a list of ingredients","description":"Given a list of ingredient names and gram amounts, returns per-item nutrition (scaled from per-100g base values) and totals. Names are fuzzy-matched against the EN + PL ingredient database — pass either language.","operationId":"calculateNutrition","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NutritionCalcRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NutritionCalcResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/meta/stats":{"get":{"tags":["meta"],"summary":"Dataset stats","description":"High-level statistics over the entire dataset — counts per category and per tag, total ingredient and recipe counts, supported languages, API version. Useful for building filter UIs and verifying coverage before committing to a tier.","operationId":"getDatasetStats","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasetStats"}}}}}}}},"components":{"schemas":{"CountedName":{"properties":{"name":{"type":"string","title":"Name"},"name_pl":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name Pl"},"count":{"type":"integer","title":"Count"}},"type":"object","required":["name","count"],"title":"CountedName"},"DatasetStats":{"properties":{"api_version":{"type":"string","title":"Api Version"},"languages":{"items":{"type":"string"},"type":"array","title":"Languages"},"ingredients_total":{"type":"integer","title":"Ingredients Total"},"recipes_total":{"type":"integer","title":"Recipes Total"},"ingredient_categories":{"items":{"$ref":"#/components/schemas/CountedName"},"type":"array","title":"Ingredient Categories"},"ingredient_tags":{"items":{"$ref":"#/components/schemas/TagCount"},"type":"array","title":"Ingredient Tags"},"recipe_tags":{"items":{"$ref":"#/components/schemas/TagCount"},"type":"array","title":"Recipe Tags"}},"type":"object","required":["api_version","languages","ingredients_total","recipes_total","ingredient_categories","ingredient_tags","recipe_tags"],"title":"DatasetStats"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"Ingredient":{"properties":{"id":{"type":"integer","title":"Id"},"slug":{"type":"string","title":"Slug"},"name":{"type":"string","title":"Name"},"name_pl":{"type":"string","title":"Name Pl"},"category":{"type":"string","title":"Category"},"category_pl":{"type":"string","title":"Category Pl"},"tags":{"items":{"type":"string"},"type":"array","title":"Tags"},"tags_pl":{"items":{"type":"string"},"type":"array","title":"Tags Pl"},"serving_amount":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Serving Amount"},"serving_amount_pl":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Serving Amount Pl"},"serving_amount_value":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Serving Amount Value"},"nutrition_per_100g":{"$ref":"#/components/schemas/NutritionPer100g"}},"type":"object","required":["id","slug","name","name_pl","category","category_pl","tags","tags_pl","nutrition_per_100g"],"title":"Ingredient"},"NutritionCalcItem":{"properties":{"requested_name":{"type":"string","title":"Requested Name"},"matched_ingredient_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Matched Ingredient Id"},"matched_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Matched Name"},"matched_name_pl":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Matched Name Pl"},"amount_g":{"type":"number","title":"Amount G"},"nutrition":{"$ref":"#/components/schemas/NutritionPerServing"}},"type":"object","required":["requested_name","matched_ingredient_id","matched_name","matched_name_pl","amount_g","nutrition"],"title":"NutritionCalcItem"},"NutritionCalcRequest":{"properties":{"items":{"items":{"$ref":"#/components/schemas/NutritionInput"},"type":"array","maxItems":100,"minItems":1,"title":"Items"}},"type":"object","required":["items"],"title":"NutritionCalcRequest"},"NutritionCalcResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/NutritionCalcItem"},"type":"array","title":"Items"},"totals":{"$ref":"#/components/schemas/NutritionPerServing"}},"type":"object","required":["items","totals"],"title":"NutritionCalcResponse"},"NutritionInput":{"properties":{"name":{"type":"string","title":"Name","description":"Ingredient name in English or Polish"},"amount_g":{"type":"number","exclusiveMinimum":0.0,"title":"Amount G","description":"Amount in grams"}},"type":"object","required":["name","amount_g"],"title":"NutritionInput"},"NutritionPer100g":{"properties":{"energy_kcal":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Energy Kcal"},"energy_kj":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Energy Kj"},"protein":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Protein"},"carbs":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Carbs"},"sugars":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Sugars"},"fats":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Fats"},"saturated_fatty_acids":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Saturated Fatty Acids"},"fiber":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Fiber"},"salt":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Salt"},"sodium_mg":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Sodium Mg"}},"type":"object","title":"NutritionPer100g"},"NutritionPerServing":{"properties":{"energy_kcal":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Energy Kcal"},"protein":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Protein"},"carbs":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Carbs"},"sugars":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Sugars"},"fats":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Fats"},"saturated_fatty_acids":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Saturated Fatty Acids"},"fiber":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Fiber"},"salt":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Salt"},"sodium_mg":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Sodium Mg"}},"type":"object","title":"NutritionPerServing"},"Page_Ingredient_":{"properties":{"total":{"type":"integer","title":"Total"},"page":{"type":"integer","title":"Page"},"page_size":{"type":"integer","title":"Page Size"},"items":{"items":{"$ref":"#/components/schemas/Ingredient"},"type":"array","title":"Items"}},"type":"object","required":["total","page","page_size","items"],"title":"Page[Ingredient]"},"Page_Recipe_":{"properties":{"total":{"type":"integer","title":"Total"},"page":{"type":"integer","title":"Page"},"page_size":{"type":"integer","title":"Page Size"},"items":{"items":{"$ref":"#/components/schemas/Recipe"},"type":"array","title":"Items"}},"type":"object","required":["total","page","page_size","items"],"title":"Page[Recipe]"},"Recipe":{"properties":{"id":{"type":"integer","title":"Id"},"slug":{"type":"string","title":"Slug"},"name":{"type":"string","title":"Name"},"name_pl":{"type":"string","title":"Name Pl"},"servings":{"type":"integer","title":"Servings"},"tags":{"items":{"type":"string"},"type":"array","title":"Tags"},"tags_pl":{"items":{"type":"string"},"type":"array","title":"Tags Pl"},"nutrition_per_serving":{"$ref":"#/components/schemas/NutritionPerServing"},"ingredients":{"items":{"$ref":"#/components/schemas/RecipeIngredient"},"type":"array","title":"Ingredients"},"instructions":{"type":"string","title":"Instructions"},"instructions_pl":{"type":"string","title":"Instructions Pl"}},"type":"object","required":["id","slug","name","name_pl","servings","tags","tags_pl","nutrition_per_serving","ingredients","instructions","instructions_pl"],"title":"Recipe"},"RecipeIngredient":{"properties":{"name":{"type":"string","title":"Name"},"name_pl":{"type":"string","title":"Name Pl"},"amount_g":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Amount G"}},"type":"object","required":["name","name_pl"],"title":"RecipeIngredient"},"TagCount":{"properties":{"name":{"type":"string","title":"Name"},"count":{"type":"integer","title":"Count"}},"type":"object","required":["name","count"],"title":"TagCount"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}