{
  "openapi": "3.1.0",
  "info": {
    "title": "NutriPulse API",
    "description": "Global nutrition intelligence API. PubMed-grounded supplement analysis, macro/micronutrient planning, food database lookups, glucose/metabolic health guidance, lab result interpretation, longevity nutrition protocols, prenatal nutrition, and personalized nutrition stack design. Backed by real-time PubMed abstracts and clinical literature. Serves consumers, dietitians, health coaches, fitness coaches, and AI health agents. iHerb, Amazon, InsideTracker, and Levels CGM affiliate links included. All endpoints support any language via ?lang=. Pricing: $0.08\u2013$0.15 USDC/call via x402 micropayment.",
    "version": "1.2.0",
    "contact": {
      "url": "https://nutripulse.vercel.app"
    }
  },
  "servers": [
    {
      "url": "https://nutripulse.vercel.app"
    }
  ],
  "components": {
    "securitySchemes": {
      "x402": {
        "type": "apiKey",
        "in": "header",
        "name": "PAYMENT-SIGNATURE",
        "description": "x402 payment signature. Send without header to receive 402 with payment requirements."
      }
    }
  },
  "security": [
    {
      "x402": []
    }
  ],
  "paths": {
    "/api/nutrition/research": {
      "get": {
        "summary": "Nutrition research synthesis",
        "description": "PubMed-grounded synthesis on any nutrition topic with evidence quality rating.",
        "operationId": "nutritionResearch",
        "parameters": [
          {
            "name": "topic",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Research synthesis"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.15,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "PubMed deep-dive research endpoint \u2014 highest clinical value; chain after /api/nutrition/supplement for topic expansion"
      }
    },
    "/api/nutrition/food": {
      "get": {
        "summary": "Food nutrition profile",
        "description": "USDA nutritional breakdown with health context, preparation tips, and Amazon product link.",
        "operationId": "nutritionFood",
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Food profile"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.05,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Food database lookup \u2014 chain before /api/nutrition/analyze to build diet profile; highest automation value for food-logging agents"
      }
    },
    "/api/nutrition/supplement": {
      "get": {
        "summary": "Supplement analysis",
        "description": "Evidence-based supplement analysis \u2014 benefits, dosage, risks, interactions, verdict, Amazon link.",
        "operationId": "nutritionSupplement",
        "parameters": [
          {
            "name": "name",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Supplement analysis"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.1,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Most comprehensive supplement endpoint \u2014 iHerb + Amazon links auto-appended; chain after /api/nutrition/analyze to identify gaps; pairs with FitPulse /api/fit/supplement for athlete-specific stacks"
      }
    },
    "/api/nutrition/plan": {
      "get": {
        "summary": "Personalized nutrition plan",
        "description": "Full nutrition plan with macros, meal timing, sample day, and supplement suggestions.",
        "operationId": "nutritionPlan",
        "parameters": [
          {
            "name": "goal",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "muscle-gain",
                "fat-loss",
                "maintenance",
                "performance",
                "longevity",
                "gut-health",
                "energy"
              ]
            }
          },
          {
            "name": "calories",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "diet",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "omnivore",
                "vegetarian",
                "vegan",
                "keto",
                "paleo",
                "mediterranean",
                "carnivore",
                "gluten-free"
              ]
            }
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Nutrition plan"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.15,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Personalized nutrition plan \u2014 chain to /api/nutrition/supplement for supporting stack; pairs with MealPulse /api/meal/plan for meal-level implementation"
      }
    },
    "/api/nutrition/compare": {
      "get": {
        "summary": "Food comparison",
        "description": "Side-by-side nutritional comparison of 2-4 foods with goal-based winner analysis.",
        "operationId": "nutritionCompare",
        "parameters": [
          {
            "name": "foods",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Comma-separated food names e.g. chicken,beef,tofu"
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Food comparison"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.1,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Diet comparison \u2014 pairs with /api/nutrition/plan for implementation; useful for keto vs Mediterranean vs plant-based decision making"
      }
    },
    "/api/nutrition/analyze": {
      "get": {
        "summary": "Meal analysis",
        "description": "Analyze a meal description \u2014 estimated macros, nutrient score 1-10, strengths, weaknesses, improvements.",
        "operationId": "nutritionAnalyze",
        "parameters": [
          {
            "name": "meal",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "goal",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Meal analysis"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.1,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Macro/micronutrient analysis \u2014 chain after user inputs diet; chain to /api/nutrition/supplement for gap-filling recommendations; pairs with FitPulse /api/fit/nutrition"
      }
    },
    "/api/nutrition/stack": {
      "get": {
        "summary": "Supplement stack",
        "description": "Evidence-ranked supplement stack for any goal, with what to skip and budget-conscious priority order.",
        "operationId": "nutritionStack",
        "parameters": [
          {
            "name": "goal",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "budget",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "budget",
                "mid-range",
                "premium"
              ]
            }
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Supplement stack"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-price-usd": 0.15,
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Full nutrition + supplement stack design \u2014 most comprehensive endpoint; chains to all supplement/nutrition endpoints; InsideTracker biomarker affiliate included"
      }
    }
  }
}