{
  "openapi": "3.0.0",
  "info": {
    "title": "Avocavo Nutrition API",
    "version": "2.0.0",
    "description": "Nutrition API powered by USDA FoodData Central that parses messy inputs like '1 cup rice' and returns clean JSON with FDC IDs",
    "contact": {
      "name": "API Support",
      "url": "https://nutrition.avocavo.app/contact"
    }
  },
  "servers": [
    {
      "url": "https://app.avocavo.app",
      "description": "Production server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    },
    "schemas": {
      "IngredientRequest": {
        "type": "object",
        "required": [
          "ingredient"
        ],
        "properties": {
          "ingredient": {
            "type": "string",
            "example": "1 cup brown rice",
            "description": "Natural language ingredient description"
          }
        }
      },
      "NutritionResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "ingredient": {
            "type": "string"
          },
          "nutrition": {
            "type": "object",
            "properties": {
              "calories": {
                "type": "number"
              },
              "protein": {
                "type": "number"
              },
              "total_fat": {
                "type": "number"
              },
              "saturated_fat": {
                "type": "number"
              },
              "trans_fat": {
                "type": "number",
                "nullable": true
              },
              "cholesterol": {
                "type": "number"
              },
              "carbohydrates": {
                "type": "number"
              },
              "fiber": {
                "type": "number"
              },
              "sugar": {
                "type": "number"
              },
              "calcium": {
                "type": "number"
              },
              "iron": {
                "type": "number"
              },
              "magnesium": {
                "type": "number"
              },
              "phosphorus": {
                "type": "number"
              },
              "potassium": {
                "type": "number"
              },
              "sodium": {
                "type": "number"
              },
              "zinc": {
                "type": "number"
              },
              "vitamin_a": {
                "type": "number",
                "nullable": true
              },
              "vitamin_c": {
                "type": "number",
                "nullable": true
              },
              "vitamin_d_iu": {
                "type": "number",
                "nullable": true
              },
              "vitamin_e": {
                "type": "number",
                "nullable": true
              },
              "vitamin_k": {
                "type": "number",
                "nullable": true
              },
              "thiamin": {
                "type": "number"
              },
              "riboflavin": {
                "type": "number"
              },
              "niacin": {
                "type": "number"
              },
              "vitamin_b6": {
                "type": "number"
              },
              "folate": {
                "type": "number"
              },
              "vitamin_b12": {
                "type": "number",
                "nullable": true
              },
              "selenium": {
                "type": "number",
                "nullable": true
              },
              "monounsaturated_fat": {
                "type": "number"
              },
              "polyunsaturated_fat": {
                "type": "number"
              }
            }
          },
          "metadata": {
            "type": "object",
            "properties": {
              "usda_match": {
                "type": "object",
                "properties": {
                  "fdc_id": {
                    "type": "integer"
                  },
                  "description": {
                    "type": "string"
                  }
                }
              },
              "usda_link": {
                "type": "string"
              },
              "match_quality": {
                "type": "string"
              },
              "confidence": {
                "type": "number"
              },
              "processing_time_ms": {
                "type": "number"
              }
            }
          },
          "parsing": {
            "type": "object",
            "properties": {
              "estimated_grams": {
                "type": "number"
              },
              "ingredient_name": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  },
  "paths": {
    "/api/v2/nutrition/ingredient": {
      "post": {
        "summary": "Analyze single ingredient",
        "description": "Parse a natural language ingredient and return complete nutrition data with USDA FDC ID",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/IngredientRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful nutrition analysis",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NutritionResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v2/nutrition/batch": {
      "post": {
        "summary": "Analyze multiple ingredients",
        "description": "Analyze multiple ingredients in a single request",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "ingredients"
                ],
                "properties": {
                  "ingredients": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/IngredientRequest"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful batch analysis",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "batch_size": {
                      "type": "integer"
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/NutritionResponse"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v2/nutrition/recipe": {
      "post": {
        "summary": "Analyze recipe with servings",
        "description": "Analyze a complete recipe and get per-serving nutrition breakdown",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "ingredients",
                  "servings"
                ],
                "properties": {
                  "ingredients": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "example": [
                      "2 cups flour",
                      "1 cup milk"
                    ]
                  },
                  "servings": {
                    "type": "number",
                    "example": 8
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful recipe analysis",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean"
                    },
                    "recipe": {
                      "type": "object",
                      "properties": {
                        "servings": {
                          "type": "number"
                        },
                        "total_ingredients": {
                          "type": "integer"
                        }
                      }
                    },
                    "nutrition": {
                      "type": "object",
                      "properties": {
                        "total": {
                          "$ref": "#/components/schemas/NutritionResponse/properties/nutrition"
                        },
                        "per_serving": {
                          "$ref": "#/components/schemas/NutritionResponse/properties/nutrition"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}