{"openapi":"3.1.0","info":{"title":"Macro Friendly Meals","version":"2026-10-08.2","summary":"Read-only nutrition, recipes, and deterministic day plans. Values are estimates until verified."},"servers":[{"url":"https://macrofriendlymeals.com"}],"paths":{"/api/v1/foods":{"get":{"operationId":"listFoods","summary":"List foods","responses":{"200":{"description":"Food list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FoodList"},"example":{"foods":[{"slug":"almond-butter","name":"Almond butter","summary":"Estimated nutrition for Almond butter, per 100 g and per 2 tbsp (32 g).","serving_label":"2 tbsp","serving_g":32,"per_100g":{"kcal":614,"p":21,"c":19,"f":56,"cost":2.66},"per_serving":{"kcal":196,"p":6.7,"c":6.1,"f":17.9,"cost":0.85},"protein_per_100kcal":3.4,"cost_low":0.5,"cost_high":1.2,"cost_per_10g_protein":1.27,"diets":["Low-carb","Paleo","Mediterranean","Vegetarian","Vegan","Pescatarian","Gluten-Free","Dairy-Free"],"scores":{"efficiency":8,"taste":9,"overall":8.5},"longevity":"Vitamin E, fiber, magnesium","recipes":[],"related":[{"name":"Ground flaxseed","canonical_url":"https://macrofriendlymeals.com/foods/ground-flaxseed"},{"name":"Cashews","canonical_url":"https://macrofriendlymeals.com/foods/cashews"},{"name":"Chia seeds","canonical_url":"https://macrofriendlymeals.com/foods/chia-seeds"},{"name":"Hummus","canonical_url":"https://macrofriendlymeals.com/foods/hummus"},{"name":"Almonds","canonical_url":"https://macrofriendlymeals.com/foods/almonds"},{"name":"Pistachios","canonical_url":"https://macrofriendlymeals.com/foods/pistachios"}],"source":"estimate","usda_fdc_id":null,"verified_at":null,"data_version":"2026-10-08.2","canonical_url":"https://macrofriendlymeals.com/foods/almond-butter","kcal":614,"p":21,"c":19,"f":56,"cost":0.85}]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/foods/{slug}":{"get":{"operationId":"getFood","summary":"One food","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Food","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Food"},"example":{"slug":"almond-butter","name":"Almond butter","summary":"Estimated nutrition for Almond butter, per 100 g and per 2 tbsp (32 g).","serving_label":"2 tbsp","serving_g":32,"per_100g":{"kcal":614,"p":21,"c":19,"f":56,"cost":2.66},"per_serving":{"kcal":196,"p":6.7,"c":6.1,"f":17.9,"cost":0.85},"protein_per_100kcal":3.4,"cost_low":0.5,"cost_high":1.2,"cost_per_10g_protein":1.27,"diets":["Low-carb","Paleo","Mediterranean","Vegetarian","Vegan","Pescatarian","Gluten-Free","Dairy-Free"],"scores":{"efficiency":8,"taste":9,"overall":8.5},"longevity":"Vitamin E, fiber, magnesium","recipes":[],"related":[{"name":"Ground flaxseed","canonical_url":"https://macrofriendlymeals.com/foods/ground-flaxseed"},{"name":"Cashews","canonical_url":"https://macrofriendlymeals.com/foods/cashews"},{"name":"Chia seeds","canonical_url":"https://macrofriendlymeals.com/foods/chia-seeds"},{"name":"Hummus","canonical_url":"https://macrofriendlymeals.com/foods/hummus"},{"name":"Almonds","canonical_url":"https://macrofriendlymeals.com/foods/almonds"},{"name":"Pistachios","canonical_url":"https://macrofriendlymeals.com/foods/pistachios"}],"source":"estimate","usda_fdc_id":null,"verified_at":null,"data_version":"2026-10-08.2","canonical_url":"https://macrofriendlymeals.com/foods/almond-butter","kcal":614,"p":21,"c":19,"f":56,"cost":0.85}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown slug","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/recipes":{"get":{"operationId":"listRecipes","summary":"List recipes","responses":{"200":{"description":"Recipe list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecipeList"},"example":{"recipes":[{"slug":"chicken-rice-broccoli-l1","name":"Baked chicken, rice, and broccoli","description":"Baked chicken, rice, and broccoli: 527 kcal and 50 g protein per serving. Estimates only.","level":1,"meal_types":["lunch","dinner"],"prep_min":10,"cook_min":22,"total_min":32,"servings":4,"ingredients":[{"food_slug":"chicken-breast-cooked","name":"Chicken breast, cooked","grams":140,"amount":5,"unit":"oz","canonical_url":"https://macrofriendlymeals.com/foods/chicken-breast-cooked"},{"food_slug":"white-rice-cooked","name":"White rice, cooked","grams":145,"amount":0.75,"unit":"cup","canonical_url":"https://macrofriendlymeals.com/foods/white-rice-cooked"},{"food_slug":"broccoli","name":"Broccoli","grams":130,"amount":1.5,"unit":"cups","canonical_url":"https://macrofriendlymeals.com/foods/broccoli"},{"food_slug":"extra-virgin-olive-oil","name":"Extra virgin olive oil","grams":7,"amount":1.5,"unit":"tsp","canonical_url":"https://macrofriendlymeals.com/foods/extra-virgin-olive-oil"}],"steps":["Heat the oven to 400°F. Toss chicken with oil, salt, and pepper.","Bake the chicken until it is cooked through, about 18 minutes.","Steam the broccoli until tender-crisp.","Heat the cooked rice and plate it with the chicken and broccoli."],"kcal":527,"p":50,"c":50,"f":13,"cost":3.43,"per_serving":{"kcal":527,"p":50,"c":50,"f":13,"cost":3.43},"diets":["Gluten-Free","Dairy-Free"],"source":"estimate","usda_fdc_id":null,"verified_at":null,"data_version":"2026-10-08.2","canonical_url":"https://macrofriendlymeals.com/recipes/chicken-rice-broccoli-l1"}]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/recipes/{slug}":{"get":{"operationId":"getRecipe","summary":"One recipe","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Recipe","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Recipe"},"example":{"slug":"chicken-rice-broccoli-l1","name":"Baked chicken, rice, and broccoli","description":"Baked chicken, rice, and broccoli: 527 kcal and 50 g protein per serving. Estimates only.","level":1,"meal_types":["lunch","dinner"],"prep_min":10,"cook_min":22,"total_min":32,"servings":4,"ingredients":[{"food_slug":"chicken-breast-cooked","name":"Chicken breast, cooked","grams":140,"amount":5,"unit":"oz","canonical_url":"https://macrofriendlymeals.com/foods/chicken-breast-cooked"},{"food_slug":"white-rice-cooked","name":"White rice, cooked","grams":145,"amount":0.75,"unit":"cup","canonical_url":"https://macrofriendlymeals.com/foods/white-rice-cooked"},{"food_slug":"broccoli","name":"Broccoli","grams":130,"amount":1.5,"unit":"cups","canonical_url":"https://macrofriendlymeals.com/foods/broccoli"},{"food_slug":"extra-virgin-olive-oil","name":"Extra virgin olive oil","grams":7,"amount":1.5,"unit":"tsp","canonical_url":"https://macrofriendlymeals.com/foods/extra-virgin-olive-oil"}],"steps":["Heat the oven to 400°F. Toss chicken with oil, salt, and pepper.","Bake the chicken until it is cooked through, about 18 minutes.","Steam the broccoli until tender-crisp.","Heat the cooked rice and plate it with the chicken and broccoli."],"kcal":527,"p":50,"c":50,"f":13,"cost":3.43,"per_serving":{"kcal":527,"p":50,"c":50,"f":13,"cost":3.43},"diets":["Gluten-Free","Dairy-Free"],"source":"estimate","usda_fdc_id":null,"verified_at":null,"data_version":"2026-10-08.2","canonical_url":"https://macrofriendlymeals.com/recipes/chicken-rice-broccoli-l1"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown slug","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/plan":{"get":{"operationId":"getPlan","summary":"Deterministic day plan","parameters":[{"name":"kcal","in":"query","schema":{"type":"integer","minimum":1000,"maximum":5000}},{"name":"p","in":"query","schema":{"type":"integer","minimum":0,"maximum":500}},{"name":"c","in":"query","schema":{"type":"integer","minimum":0,"maximum":500}},{"name":"f","in":"query","schema":{"type":"integer","minimum":0,"maximum":500}},{"name":"meals","in":"query","schema":{"type":"integer","minimum":1,"maximum":6}},{"name":"mode","in":"query","schema":{"type":"string"}},{"name":"keys","in":"query","schema":{"type":"string"}},{"name":"seed","in":"query","schema":{"type":"integer"}},{"name":"plan","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Plan","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Plan"},"example":{"query":{"kcal":1800,"p":90,"c":90,"f":40,"meals":3,"mode":"balanced","keys":[],"seed":0},"canonical_url":"https://macrofriendlymeals.com/plan?kcal=1800&p=90&c=90&f=40&meals=3&mode=balanced&seed=0","effective_kcal":1800,"bumped":false,"meals":[{"name":"Protein overnight oats","kind":"recipe","recipe_slug":"greek-yogurt-bowl-l2","servings":1.75,"kcal":654,"p":67,"c":58,"f":19,"cost":4.75,"foods":[],"source":"estimate","usda_fdc_id":null,"verified_at":null,"data_version":"2026-10-08.2","canonical_url":"https://macrofriendlymeals.com/recipes/greek-yogurt-bowl-l2"},{"name":"Tuna poke-style bowl","kind":"recipe","recipe_slug":"tuna-potato-rice-l3","servings":1.3,"kcal":566,"p":53,"c":54,"f":15,"cost":3.86,"foods":[],"source":"estimate","usda_fdc_id":null,"verified_at":null,"data_version":"2026-10-08.2","canonical_url":"https://macrofriendlymeals.com/recipes/tuna-potato-rice-l3"},{"name":"Egg-white scramble with oats","kind":"recipe","recipe_slug":"eggs-oats-l1","servings":1.5,"kcal":580,"p":50,"c":53,"f":18,"cost":3.42,"foods":[],"source":"estimate","usda_fdc_id":null,"verified_at":null,"data_version":"2026-10-08.2","canonical_url":"https://macrofriendlymeals.com/recipes/eggs-oats-l1"}],"totals":{"kcal":1800,"p":170,"c":165,"f":52},"minimums_met":{"p":true,"c":true,"f":true},"kcal_within_target":true,"kcal_delta":0,"repeat_note":null,"portion_note":null,"est_cost_per_day":12.03,"builder_version":"4","source":"estimate","usda_fdc_id":null,"verified_at":null,"data_version":"2026-10-08.2"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"Provenance":{"type":"object","required":["source","usda_fdc_id","verified_at","data_version","canonical_url"],"properties":{"source":{"type":"string","enum":["estimate"]},"usda_fdc_id":{"type":["number","null"]},"verified_at":{"type":["string","null"]},"data_version":{"type":"string","examples":["2026-10-08.2"]},"canonical_url":{"type":"string","format":"uri"}}},"Nutrients":{"type":"object","required":["kcal","p","c","f","cost"],"properties":{"kcal":{"type":"number"},"p":{"type":"number"},"c":{"type":"number"},"f":{"type":"number"},"cost":{"type":"number"}}},"MacroTotals":{"type":"object","required":["kcal","p","c","f"],"properties":{"kcal":{"type":"number"},"p":{"type":"number"},"c":{"type":"number"},"f":{"type":"number"}}},"PlanMeal":{"type":"object","required":["name","kind","recipe_slug","servings","kcal","p","c","f","cost","foods","source","usda_fdc_id","verified_at","data_version","canonical_url"],"properties":{"name":{"type":"string"},"kind":{"type":"string","enum":["recipe","plate"]},"recipe_slug":{"type":["string","null"]},"servings":{"type":"number"},"kcal":{"type":"number"},"p":{"type":"number"},"c":{"type":"number"},"f":{"type":"number"},"cost":{"type":"number"},"foods":{"type":"array","items":{"type":"object","required":["food_slug","name","grams","kcal","p","c","f","canonical_url"],"properties":{"food_slug":{"type":"string"},"name":{"type":"string"},"role":{"type":"string"},"grams":{"type":"number"},"kcal":{"type":"number"},"p":{"type":"number"},"c":{"type":"number"},"f":{"type":"number"},"canonical_url":{"type":"string"}}}},"source":{"type":"string","enum":["estimate"]},"usda_fdc_id":{"type":["number","null"]},"verified_at":{"type":["string","null"]},"data_version":{"type":"string"},"canonical_url":{"type":"string"}}},"Error":{"type":"object","required":["error","source","usda_fdc_id","verified_at","data_version","canonical_url"],"properties":{"error":{"type":"string"},"source":{"type":"string","enum":["estimate"]},"usda_fdc_id":{"type":["number","null"]},"verified_at":{"type":["string","null"]},"data_version":{"type":"string","examples":["2026-10-08.2"]},"canonical_url":{"type":"string","format":"uri"}}},"Food":{"allOf":[{"$ref":"#/components/schemas/Provenance"},{"type":"object","required":["slug","name","kcal","p","c","f","cost","per_100g","per_serving","diets","source","usda_fdc_id","verified_at","data_version","canonical_url"],"properties":{"slug":{"type":"string"},"name":{"type":"string"},"kcal":{"type":"number"},"p":{"type":"number"},"c":{"type":"number"},"f":{"type":"number"},"cost":{"type":"number"},"per_100g":{"$ref":"#/components/schemas/Nutrients"},"per_serving":{"$ref":"#/components/schemas/Nutrients"},"diets":{"type":"array","items":{"type":"string"}}}}]},"FoodList":{"type":"object","required":["foods"],"properties":{"foods":{"type":"array","items":{"$ref":"#/components/schemas/Food"}}}},"Recipe":{"allOf":[{"$ref":"#/components/schemas/Provenance"},{"type":"object","required":["slug","name","kcal","p","c","f","cost","per_serving","diets","ingredients","source","usda_fdc_id","verified_at","data_version","canonical_url"],"properties":{"slug":{"type":"string"},"name":{"type":"string"},"kcal":{"type":"number"},"p":{"type":"number"},"c":{"type":"number"},"f":{"type":"number"},"cost":{"type":"number"},"per_serving":{"$ref":"#/components/schemas/Nutrients"},"diets":{"type":"array","items":{"type":"string"}},"ingredients":{"type":"array","items":{"type":"object","required":["food_slug","name","grams","canonical_url"],"properties":{"food_slug":{"type":"string"},"name":{"type":"string"},"grams":{"type":"number"},"amount":{"type":"number"},"unit":{"type":"string"},"canonical_url":{"type":"string"}}}}}}]},"RecipeList":{"type":"object","required":["recipes"],"properties":{"recipes":{"type":"array","items":{"$ref":"#/components/schemas/Recipe"}}}},"Plan":{"allOf":[{"$ref":"#/components/schemas/Provenance"},{"type":"object","required":["query","effective_kcal","bumped","meals","totals","minimums_met","kcal_within_target","kcal_delta","repeat_note","portion_note","est_cost_per_day","builder_version","source","usda_fdc_id","verified_at","data_version","canonical_url"],"properties":{"query":{"type":"object"},"effective_kcal":{"type":"number"},"bumped":{"type":"boolean"},"meals":{"type":"array","items":{"$ref":"#/components/schemas/PlanMeal"}},"totals":{"$ref":"#/components/schemas/MacroTotals"},"minimums_met":{"type":"object","required":["p","c","f"],"properties":{"p":{"type":"boolean"},"c":{"type":"boolean"},"f":{"type":"boolean"}}},"kcal_within_target":{"type":"boolean","description":"Day kcal is within 3 percent of the effective target."},"kcal_delta":{"type":"number","description":"Rounded day kcal minus the rounded effective target."},"repeat_note":{"type":["string","null"]},"portion_note":{"type":["string","null"]},"est_cost_per_day":{"type":"number"},"builder_version":{"type":"string"}}}]}}}}