{
  "openapi": "3.1.0",
  "info": {
    "title": "MealPulse API",
    "description": "Global meal planning and culinary intelligence API. AI-synthesized meal plans, recipe generation, dietary restriction guidance, grocery optimization, pantry utilization, batch cooking, food budgeting, cooking substitutions, leftover transformation, and kitchen equipment recommendations. Supports every major diet (Mediterranean, keto, vegan, Ayurvedic, Japanese, halal, kosher, diabetic-friendly, FODMAP, AIP, and more). Serves users in 100+ countries \u2014 responds in any language via ?lang=. Pricing: $0.08\u2013$0.15 USDC/call via x402 micropayment on Base mainnet.",
    "version": "1.2.0"
  },
  "servers": [
    {
      "url": "https://mealpulse.vercel.app"
    }
  ],
  "paths": {
    "/api/meal/plan": {
      "get": {
        "summary": "Weekly meal plan",
        "description": "7-day meal plan with recipes, nutrition estimates, prep tips, and cost by dietary needs, budget, and servings.",
        "parameters": [
          {
            "name": "PAYMENT-SIGNATURE",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "dietary",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "budget",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "servings",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "cuisine",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "preferences",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "7-day meal plan with nutrition and cost estimates"
          },
          "402": {
            "description": "Payment required \u2014 x402 USDC on Base, $0.15"
          }
        },
        "x-agent-use-case": "on-demand",
        "x-price-usd": 0.15,
        "x-agent-chaining": "Most expensive endpoint \u2014 pair with /api/meal/grocery to convert the plan into a shopping list; follow with /api/meal/batch for prep-day instructions; pairs with FitPulse /api/fit/nutrition for macro targets"
      }
    },
    "/api/meal/recipe": {
      "get": {
        "summary": "Recipe with technique tips",
        "description": "Full recipe with instructions, technique tips, nutrition per serving, substitutions, and storage guidance.",
        "parameters": [
          {
            "name": "PAYMENT-SIGNATURE",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "dish",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "dietary",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "servings",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Complete recipe with technique guidance"
          },
          "402": {
            "description": "Payment required \u2014 x402 USDC on Base, $0.08"
          }
        },
        "x-agent-use-case": "on-demand",
        "x-price-usd": 0.1,
        "x-agent-chaining": "Follow with /api/meal/substitute if user is missing ingredients; pairs with /api/meal/grocery to add missing items to shopping list; follow with /api/meal/batch if scaling for multiple servings"
      }
    },
    "/api/meal/grocery": {
      "get": {
        "summary": "Grocery list by store section",
        "description": "Organized grocery list with cost estimates, bulk-buy opportunities, and money-saving tips.",
        "parameters": [
          {
            "name": "PAYMENT-SIGNATURE",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "meals",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "servings",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "budget",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "store",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Grocery list organized by store section"
          },
          "402": {
            "description": "Payment required \u2014 x402 USDC on Base, $0.10"
          }
        },
        "x-agent-use-case": "on-demand",
        "x-price-usd": 0.1,
        "x-agent-chaining": "Always chain after /api/meal/plan to convert the plan into a consolidated shopping list; pairs with /api/meal/budget for cost optimization; follow with /api/meal/pantry to cross-reference what is already on hand"
      }
    },
    "/api/meal/pantry": {
      "get": {
        "summary": "Pantry-to-meal ideas",
        "description": "Meal ideas from available ingredients with minimal additional shopping required.",
        "parameters": [
          {
            "name": "PAYMENT-SIGNATURE",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "ingredients",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "dietary",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Meal ideas with strategic purchase suggestions"
          },
          "402": {
            "description": "Payment required \u2014 x402 USDC on Base, $0.10"
          }
        },
        "x-agent-use-case": "on-demand",
        "x-price-usd": 0.08,
        "x-agent-chaining": "Run before /api/meal/recipe to surface what can be made with existing ingredients; pairs with /api/meal/leftover for nearly-expired items; reduces grocery spend when paired with /api/meal/grocery"
      }
    },
    "/api/meal/batch": {
      "get": {
        "summary": "Batch cooking guide",
        "description": "Parallel prep schedule with storage times and reheating instructions for weekly meal prep.",
        "parameters": [
          {
            "name": "PAYMENT-SIGNATURE",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "meals",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "servings",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Batch cooking schedule and storage guide"
          },
          "402": {
            "description": "Payment required \u2014 x402 USDC on Base, $0.10"
          }
        },
        "x-agent-use-case": "on-demand",
        "x-price-usd": 0.1,
        "x-agent-chaining": "Always pair with /api/meal/plan \u2014 batch cooking is only efficient when the plan is known first; pairs with /api/meal/grocery for consolidated shopping; follow with /api/meal/budget for cost-per-serving calculations"
      }
    },
    "/api/meal/dietary": {
      "get": {
        "summary": "Dietary restriction guide",
        "description": "Safe foods, hidden sources, safe swaps, label reading tips, and restaurant ordering guidance.",
        "parameters": [
          {
            "name": "PAYMENT-SIGNATURE",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "dietary",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "concern",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Complete dietary restriction guidance"
          },
          "402": {
            "description": "Payment required \u2014 x402 USDC on Base, $0.08"
          }
        },
        "x-agent-use-case": "on-demand",
        "x-price-usd": 0.08,
        "x-agent-chaining": "Run early in any dietary restriction workflow \u2014 feeds params into /api/meal/plan, /api/meal/recipe, and /api/meal/grocery; pairs with FitPulse /api/fit/nutrition for clinical dietary + performance nutrition integration"
      }
    },
    "/api/meal/budget": {
      "get": {
        "summary": "Budget meal strategy",
        "description": "Real weekly meal strategy with sample menus, cheapest protein sources, and shopping tactics.",
        "parameters": [
          {
            "name": "PAYMENT-SIGNATURE",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "budget",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "people",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "location",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "dietary",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Budget meal plan with shopping strategy"
          },
          "402": {
            "description": "Payment required \u2014 x402 USDC on Base, $0.10"
          }
        },
        "x-agent-use-case": "on-demand",
        "x-price-usd": 0.08,
        "x-agent-chaining": "Pair with /api/meal/plan for budget-constrained meal planning; follow with /api/meal/grocery for the optimized shopping list; highest value for users on SNAP/food assistance budgets"
      }
    },
    "/api/meal/substitute": {
      "get": {
        "summary": "Ingredient substitutions",
        "description": "Ranked substitutes with exact ratios, similarity ratings, and honest texture/flavor notes.",
        "parameters": [
          {
            "name": "PAYMENT-SIGNATURE",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "ingredient",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "reason",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Ranked substitution options with ratios"
          },
          "402": {
            "description": "Payment required \u2014 x402 USDC on Base, $0.05"
          }
        },
        "x-agent-use-case": "on-demand",
        "x-price-usd": 0.05,
        "x-agent-chaining": "Chain immediately when an ingredient is flagged as unavailable in /api/meal/recipe; pairs with /api/meal/pantry to find what substitutes are already on hand"
      }
    },
    "/api/meal/leftover": {
      "get": {
        "summary": "Leftover transformation",
        "description": "Creative new meals from leftovers with food safety guide and 30-second quick wins.",
        "parameters": [
          {
            "name": "PAYMENT-SIGNATURE",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "leftovers",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Leftover transformation ideas with food safety guidance"
          },
          "402": {
            "description": "Payment required \u2014 x402 USDC on Base, $0.08"
          }
        },
        "x-agent-use-case": "on-demand",
        "x-price-usd": 0.05,
        "x-agent-chaining": "Pairs with /api/meal/pantry for nearly-expired inventory; follow with /api/meal/recipe for full instructions using the suggested approach; reduces food waste significantly in weekly meal planning loops"
      }
    },
    "/api/meal/kitchen": {
      "get": {
        "summary": "Kitchen equipment advisor",
        "description": "Equipment recommendations by cooking style with budget and upgrade picks and Amazon links.",
        "parameters": [
          {
            "name": "PAYMENT-SIGNATURE",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "cooking_style",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "budget",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "experience",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Kitchen equipment recommendations with Amazon links"
          },
          "402": {
            "description": "Payment required \u2014 x402 USDC on Base, $0.08"
          }
        },
        "x-agent-use-case": "on-demand",
        "x-price-usd": 0.08,
        "x-agent-chaining": "Call when a recipe requires equipment the user may not have; pairs with /api/meal/substitute for technique substitutions; good onboarding endpoint for new cooks building their kitchen setup"
      }
    }
  }
}