{
  "openapi": "3.1.0",
  "info": {
    "title": "HarvestPulse API",
    "description": "Global farm-to-table and agricultural intelligence API. USDA + ERS data synthesis. Local food finder (farmers markets, CSAs, on-farm markets), seasonal produce calendars, organic certification lookup, regenerative farming guides, food safety tracking, agricultural tourism discovery, and food label decoding. Covers US USDA data with international seasonal produce guidance. Misfits Market, Thrive Market, Imperfect Foods, LocalHarvest, and agricultural tool affiliates included. All endpoints support any language via ?lang=. Pricing: $0.05\u2013$0.15 USDC/call via x402 micropayment.",
    "version": "1.2.0",
    "contact": {
      "url": "https://harvestpulse.vercel.app"
    }
  },
  "servers": [
    {
      "url": "https://harvestpulse.vercel.app"
    }
  ],
  "components": {
    "securitySchemes": {
      "x402": {
        "type": "apiKey",
        "in": "header",
        "name": "PAYMENT-SIGNATURE",
        "description": "x402 micropayment on Base mainnet. On 402, read PAYMENT-REQUIRED header for amount and wallet."
      }
    }
  },
  "security": [
    {
      "x402": []
    }
  ],
  "paths": {
    "/api/harvest/find": {
      "get": {
        "summary": "Local Farm & Market Finder",
        "description": "Find farmers markets, CSAs, and on-farm markets near a ZIP code via USDA Local Food Directories. $0.05.",
        "operationId": "localFoodFind",
        "parameters": [
          {
            "name": "zip",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "US ZIP code"
          },
          {
            "name": "radius",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 25
            },
            "description": "Search radius in miles"
          }
        ],
        "responses": {
          "200": {
            "description": "Local food listings from USDA"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Local food finder \u2014 Misfits Market + Thrive Market affiliate links auto-appended; start here for any local food query",
        "x-price-usd": 0.05
      }
    },
    "/api/harvest/season": {
      "get": {
        "summary": "Seasonal Produce Calendar",
        "description": "What's in season right now by US state or country. All 50 states + UK/AU/CA. Hardcoded calendar, no API key required. $0.05.",
        "operationId": "seasonalCalendar",
        "parameters": [
          {
            "name": "state",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "2-letter US state code (e.g. CA, TX, NY)"
          },
          {
            "name": "country",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "UK",
                "AU",
                "CA"
              ]
            },
            "description": "Country (for international calendar)"
          },
          {
            "name": "month",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 12
            },
            "description": "Month (1-12). Defaults to current month."
          }
        ],
        "responses": {
          "200": {
            "description": "Seasonal produce intelligence"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Seasonal produce calendar \u2014 chain before /api/harvest/find to target seasonal farmers market visits; global seasonal data",
        "x-price-usd": 0.05
      }
    },
    "/api/harvest/labels": {
      "get": {
        "summary": "Food Label Decoder",
        "description": "Decode food marketing labels \u2014 what they legally mean vs. what they imply to consumers. $0.08.",
        "operationId": "decodeLabel",
        "parameters": [
          {
            "name": "label",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Label to decode (e.g. free-range, natural, pasture-raised, grass-fed, non-GMO)"
          }
        ],
        "responses": {
          "200": {
            "description": "Label analysis with legal vs marketing reality"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Food label decoder \u2014 organic, non-GMO, fair trade, grass-fed certification analysis",
        "x-price-usd": 0.05
      }
    },
    "/api/harvest/organic": {
      "get": {
        "summary": "Certified Organic Farm Finder",
        "description": "USDA Organic INTEGRITY database lookup for certified organic operations. $0.08.",
        "operationId": "findOrganic",
        "parameters": [
          {
            "name": "state",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "2-letter US state code"
          },
          {
            "name": "city",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "City name (optional filter)"
          }
        ],
        "responses": {
          "200": {
            "description": "Certified organic operations from USDA Organic INTEGRITY"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Organic certification lookup \u2014 chain after /api/harvest/find to verify organic claims; USDA NOP database",
        "x-price-usd": 0.08
      }
    },
    "/api/harvest/dirty-dozen": {
      "get": {
        "summary": "Dirty Dozen & Clean Fifteen",
        "description": "EWG pesticide priority list \u2014 which produce to buy organic vs. when conventional is fine. $0.05.",
        "operationId": "dirtyDozen",
        "responses": {
          "200": {
            "description": "Pesticide guide with organic buying strategy"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-agent-use-case": "on-demand"
      }
    },
    "/api/harvest/food-hub": {
      "get": {
        "summary": "Regional Food Hub Finder",
        "description": "Find food hubs \u2014 farm aggregators connecting local farms to restaurants, schools, and institutions. $0.08.",
        "operationId": "findFoodHub",
        "parameters": [
          {
            "name": "zip",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "US ZIP code"
          },
          {
            "name": "radius",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 75
            },
            "description": "Search radius in miles"
          }
        ],
        "responses": {
          "200": {
            "description": "Food hub listings"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-agent-use-case": "on-demand"
      }
    },
    "/api/harvest/regenerative": {
      "get": {
        "summary": "Regenerative Agriculture Guide",
        "description": "Certification tiers (ROC, CNG, Land to Market), what regenerative means, how to find farms. $0.10.",
        "operationId": "regenerativeGuide",
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Search terms (e.g. beef, dairy, grain)"
          },
          {
            "name": "state",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "US state for local context"
          }
        ],
        "responses": {
          "200": {
            "description": "Regenerative agriculture intelligence"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Regenerative farming practices \u2014 pairs with ClimatePulse for carbon sequestration context; seed affiliate links",
        "x-price-usd": 0.1
      }
    },
    "/api/harvest/designations": {
      "get": {
        "summary": "Global Food Designations",
        "description": "EU PDO/PGI, French AOC, Italian DOP \u2014 authentic vs imitation guide for protected origin foods. $0.10.",
        "operationId": "foodDesignations",
        "parameters": [
          {
            "name": "product",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Product name (e.g. parmigiano-reggiano, champagne, prosciutto-di-parma, roquefort)"
          }
        ],
        "responses": {
          "200": {
            "description": "Designation analysis with authenticity guide"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Geographical designation lookup (PDO/PGI/AOC) \u2014 pairs with TravelPulse for food tourism",
        "x-price-usd": 0.08
      }
    },
    "/api/harvest/agritourism": {
      "get": {
        "summary": "Agritourism & U-Pick Finder",
        "description": "Find u-pick farms, farm stays, harvest festivals, and farm experiences via USDA data. $0.05.",
        "operationId": "findAgritourism",
        "parameters": [
          {
            "name": "zip",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "US ZIP code"
          },
          {
            "name": "state",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "US state for broader search"
          },
          {
            "name": "radius",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50
            },
            "description": "Search radius in miles"
          }
        ],
        "responses": {
          "200": {
            "description": "Agritourism listings"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Agricultural tourism \u2014 farm stays, u-pick, harvest festivals; pairs with TravelPulse",
        "x-price-usd": 0.08
      }
    },
    "/api/harvest/csa": {
      "get": {
        "summary": "CSA Evaluation Guide",
        "description": "How to choose, join, and maximize a Community Supported Agriculture share. Types, costs, questions to ask. $0.10.",
        "operationId": "csaGuide",
        "parameters": [
          {
            "name": "location",
            "in": "query",
            "schema": {
              "type": "string",
              "default": "US"
            },
            "description": "City/state or region"
          },
          {
            "name": "household_size",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 2
            },
            "description": "Number of people in household"
          }
        ],
        "responses": {
          "200": {
            "description": "CSA evaluation guide"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-agent-use-case": "on-demand"
      }
    },
    "/api/harvest/cost": {
      "get": {
        "summary": "Local vs. Conventional Cost Analysis",
        "description": "Real cost comparison of local/organic vs. conventional grocery. Uses FRED food CPI data. $0.10.",
        "operationId": "costComparison",
        "parameters": [
          {
            "name": "items",
            "in": "query",
            "schema": {
              "type": "string",
              "default": "strawberries tomatoes lettuce"
            },
            "description": "Produce items to compare (space or comma separated)"
          },
          {
            "name": "location",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Region or city for local market context"
          }
        ],
        "responses": {
          "200": {
            "description": "Cost comparison with FRED macro context"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-agent-use-case": "on-demand"
      }
    },
    "/api/harvest/roadmap": {
      "get": {
        "summary": "Farm-to-Table Lifestyle Roadmap",
        "description": "Phased 3-month transition guide to eating more locally and seasonally. Budget-aware and practical. $0.15.",
        "operationId": "farmToTableRoadmap",
        "parameters": [
          {
            "name": "location",
            "in": "query",
            "schema": {
              "type": "string",
              "default": "US"
            },
            "description": "City, state, or region"
          },
          {
            "name": "weekly_budget",
            "in": "query",
            "schema": {
              "type": "string",
              "default": "150"
            },
            "description": "Weekly food budget in USD"
          },
          {
            "name": "goals",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Specific goals (e.g. reduce pesticides, support local farms, eat seasonally)"
          }
        ],
        "responses": {
          "200": {
            "description": "Farm-to-table lifestyle roadmap"
          },
          "402": {
            "description": "Payment required"
          }
        },
        "x-agent-use-case": "on-demand",
        "x-agent-chaining": "Starting a farm/homestead roadmap \u2014 seed + tool affiliate links; pairs with FranchisePulse for agricultural franchise options",
        "x-price-usd": 0.1
      }
    }
  }
}