{
  "openapi": "3.1.0",
  "info": {
    "title": "FieldPulse API",
    "version": "1.0.0",
    "description": "Global precision agriculture intelligence API. Synthesizes satellite NDVI data, Open-Meteo soil/weather data, USDA WASDE, FAO, and EPPO into structured, actionable intelligence for growers, agronomists, commodity traders, and AI agents. 10 endpoints covering crop health, yield forecasting, weather risk, soil intelligence, pest/disease alerts, irrigation scheduling, commodity outlook, input costs, planting windows, and seasonal briefs. All endpoints require x402 USDC micropayment on Base mainnet.",
    "contact": { "name": "The Aslan Group LLC", "email": "info@theaslangroupllc.com" },
    "x-agent-network": "PulseNetwork",
    "x-payment-protocol": "x402",
    "x-payment-asset": "USDC on Base (eip155:8453)"
  },
  "servers": [{ "url": "https://fieldpulse.vercel.app", "description": "Production" }],
  "paths": {
    "/api/crop-health": {
      "get": {
        "operationId": "cropHealth",
        "summary": "Crop health assessment from satellite + soil data",
        "description": "Returns a comprehensive crop health assessment using satellite-derived NDVI context, live soil moisture, soil temperature, and weather stress factors. Covers any crop at any global location. Use this as the daily/weekly field health check for precision agriculture workflows.",
        "x-agent-use-case": "poll-daily",
        "x-price-usdc": "0.10",
        "x-data-sources": ["Open-Meteo soil/weather", "GEOGLAM satellite monitoring", "Tavily crop condition search"],
        "x-model": "claude-sonnet-4-6",
        "parameters": [
          { "name": "lat", "in": "query", "required": true, "schema": { "type": "number" }, "description": "Latitude of the field (e.g. 41.88 for Iowa, 48.85 for Paris, -33.87 for Sydney)" },
          { "name": "lon", "in": "query", "required": true, "schema": { "type": "number" }, "description": "Longitude of the field" },
          { "name": "crop", "in": "query", "schema": { "type": "string", "default": "wheat" }, "description": "Crop name: wheat, corn/maize, rice, soybean, cotton, coffee, cocoa, barley, canola, sugarcane, potato, tomato, cassava, millet, sorghum, palm-oil, etc." },
          { "name": "lang", "in": "query", "schema": { "type": "string", "default": "en" }, "description": "Response language ISO 639-1 code (en, es, fr, pt, zh, hi, ar, id, sw, etc.)" }
        ],
        "responses": {
          "200": { "description": "Crop health assessment", "content": { "application/json": { "schema": { "type": "object", "properties": { "crop": { "type": "string" }, "region": { "type": "string" }, "overall_health": { "type": "string", "enum": ["excellent","good","fair","stressed","critical"] }, "health_score": { "type": "number" }, "ndvi_context": { "type": "object" }, "soil_conditions": { "type": "object" }, "recommended_actions": { "type": "array", "items": { "type": "string" } }, "urgency": { "type": "string" } } } } } },
          "402": { "description": "Payment required — x402 USDC micropayment on Base" }
        }
      }
    },
    "/api/yield-forecast": {
      "get": {
        "operationId": "yieldForecast",
        "summary": "Yield and production forecast for any crop and region",
        "description": "Synthesizes USDA WASDE, FAO supply/demand data, and historical climate into a yield and production forecast. Returns direction, confidence, production estimate, key drivers, price implications, and country-level breakdown. Essential for commodity traders, buyers, and agribusiness planning agents.",
        "x-agent-use-case": "on-demand",
        "x-price-usdc": "0.15",
        "x-data-sources": ["USDA WASDE", "FAO GIEWS", "CME futures context", "Open-Meteo historical climate"],
        "x-model": "claude-sonnet-4-6",
        "parameters": [
          { "name": "crop", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Crop: wheat, corn, rice, soybeans, cotton, coffee, cocoa, palm-oil, canola, barley, sorghum" },
          { "name": "region", "in": "query", "schema": { "type": "string" }, "description": "Named region: 'Black Sea', 'US Midwest', 'Brazil Mato Grosso', 'India Punjab', 'EU', 'Australia', 'Global'" },
          { "name": "lat", "in": "query", "schema": { "type": "number" }, "description": "Latitude (alternative to region name)" },
          { "name": "lon", "in": "query", "schema": { "type": "number" }, "description": "Longitude (alternative to region name)" },
          { "name": "lang", "in": "query", "schema": { "type": "string", "default": "en" }, "description": "Response language ISO 639-1" }
        ],
        "responses": {
          "200": { "description": "Yield forecast", "content": { "application/json": { "schema": { "type": "object", "properties": { "yield_outlook": { "type": "object" }, "production_estimate": { "type": "object" }, "key_drivers": { "type": "array" }, "price_implications": { "type": "object" }, "regional_breakdown": { "type": "array" } } } } } },
          "402": { "description": "Payment required" }
        }
      }
    },
    "/api/weather-risk": {
      "get": {
        "operationId": "weatherRisk",
        "summary": "7-14 day crop-specific weather risk assessment",
        "description": "Assesses frost, heat stress, drought, waterlogging, and wind damage risk for the next 7-14 days using Open-Meteo forecast data. Returns a risk score, specific risk events with timing, and a critical action window (e.g. 'apply fungicide before Day 4 rain event'). Global coverage via lat/lon.",
        "x-agent-use-case": "poll-daily",
        "x-price-usdc": "0.08",
        "x-data-sources": ["Open-Meteo 7-day forecast", "Soil moisture and ET0 data"],
        "x-model": "claude-haiku-4-5-20251001",
        "parameters": [
          { "name": "lat", "in": "query", "required": true, "schema": { "type": "number" }, "description": "Field latitude" },
          { "name": "lon", "in": "query", "required": true, "schema": { "type": "number" }, "description": "Field longitude" },
          { "name": "crop", "in": "query", "schema": { "type": "string", "default": "wheat" }, "description": "Crop being assessed" },
          { "name": "lang", "in": "query", "schema": { "type": "string", "default": "en" }, "description": "Response language" }
        ],
        "responses": {
          "200": { "description": "Weather risk assessment", "content": { "application/json": { "schema": { "type": "object", "properties": { "overall_risk": { "type": "string" }, "risk_score": { "type": "number" }, "forecast_risks": { "type": "array" }, "critical_window": { "type": "string" } } } } } },
          "402": { "description": "Payment required" }
        }
      }
    },
    "/api/soil-intel": {
      "get": {
        "operationId": "soilIntel",
        "summary": "Live soil moisture, temperature, and evapotranspiration intelligence",
        "description": "Returns real-time soil moisture at 0-7cm and 7-28cm depth, soil temperature, daily ET0 evapotranspiration, and soil health signals from Open-Meteo. Foundation layer for irrigation scheduling and crop management. Works for any lat/lon globally.",
        "x-agent-use-case": "poll-daily",
        "x-price-usdc": "0.08",
        "x-data-sources": ["Open-Meteo soil sensor data", "Open-Meteo ERA5 historical"],
        "x-model": "claude-haiku-4-5-20251001",
        "parameters": [
          { "name": "lat", "in": "query", "required": true, "schema": { "type": "number" }, "description": "Field latitude" },
          { "name": "lon", "in": "query", "required": true, "schema": { "type": "number" }, "description": "Field longitude" },
          { "name": "lang", "in": "query", "schema": { "type": "string", "default": "en" }, "description": "Response language" }
        ],
        "responses": {
          "200": { "description": "Soil intelligence", "content": { "application/json": { "schema": { "type": "object", "properties": { "soil_moisture": { "type": "object" }, "soil_temperature": { "type": "object" }, "evapotranspiration": { "type": "object" } } } } } },
          "402": { "description": "Payment required" }
        }
      }
    },
    "/api/pest-disease": {
      "get": {
        "operationId": "pestDisease",
        "summary": "Pest and disease risk assessment with outbreak alerts",
        "description": "Assesses active and emerging pest/disease threats using EPPO Global Database, FAO IPPC surveillance reports, and current weather conditions. Returns specific threat profiles, outbreak status, treatment windows, and IPM guidance. Global coverage — especially relevant for rice in Asia, wheat rusts in East Africa, coffee leaf rust in Latin America.",
        "x-agent-use-case": "on-demand",
        "x-price-usdc": "0.10",
        "x-data-sources": ["EPPO Global Database", "FAO IPPC", "Open-Meteo weather", "Regional extension alerts via Tavily"],
        "x-model": "claude-sonnet-4-6",
        "parameters": [
          { "name": "crop", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Crop: wheat, rice, corn, potato, coffee, cocoa, soybean, cotton, etc." },
          { "name": "region", "in": "query", "schema": { "type": "string" }, "description": "Named region (e.g. 'Punjab India', 'Mekong Delta Vietnam', 'Ethiopian Highlands')" },
          { "name": "lat", "in": "query", "schema": { "type": "number" }, "description": "Field latitude" },
          { "name": "lon", "in": "query", "schema": { "type": "number" }, "description": "Field longitude" },
          { "name": "lang", "in": "query", "schema": { "type": "string", "default": "en" }, "description": "Response language" }
        ],
        "responses": {
          "200": { "description": "Pest and disease risk assessment", "content": { "application/json": { "schema": { "type": "object", "properties": { "overall_risk": { "type": "string" }, "active_threats": { "type": "array" }, "preventive_actions": { "type": "array" }, "treatment_window": { "type": "string" } } } } } },
          "402": { "description": "Payment required" }
        }
      }
    },
    "/api/irrigation": {
      "get": {
        "operationId": "irrigationSchedule",
        "summary": "ET0-based irrigation recommendation and water budget",
        "description": "Generates a science-based irrigation recommendation using FAO-56 ET0 methodology, soil moisture data, and 7-day precipitation forecast. Returns irrigation decision (irrigate now / hold / skip), water budget, recommended application amount, and scheduling frequency. Global coverage — optimized for drip, pivot, furrow, and flood systems.",
        "x-agent-use-case": "poll-daily",
        "x-price-usdc": "0.08",
        "x-data-sources": ["Open-Meteo ET0 + soil moisture", "Open-Meteo 7-day precipitation forecast"],
        "x-model": "claude-haiku-4-5-20251001",
        "parameters": [
          { "name": "lat", "in": "query", "required": true, "schema": { "type": "number" }, "description": "Field latitude" },
          { "name": "lon", "in": "query", "required": true, "schema": { "type": "number" }, "description": "Field longitude" },
          { "name": "crop", "in": "query", "schema": { "type": "string", "default": "wheat" }, "description": "Crop type (affects crop coefficient Kc)" },
          { "name": "soil_type", "in": "query", "schema": { "type": "string", "default": "loam" }, "description": "Soil type: sandy, loam, clay, silt-loam, sandy-loam, clay-loam" },
          { "name": "lang", "in": "query", "schema": { "type": "string", "default": "en" }, "description": "Response language" }
        ],
        "responses": {
          "200": { "description": "Irrigation recommendation", "content": { "application/json": { "schema": { "type": "object", "properties": { "irrigation_decision": { "type": "string" }, "water_budget": { "type": "object" }, "irrigation_schedule": { "type": "object" }, "water_stress_risk": { "type": "string" } } } } } },
          "402": { "description": "Payment required" }
        }
      }
    },
    "/api/commodity-outlook": {
      "get": {
        "operationId": "commodityOutlook",
        "summary": "Agricultural commodity market outlook and price intelligence",
        "description": "Synthesizes USDA WASDE, FAO Food Price Index, and futures market data into a 30-90 day commodity outlook. Returns supply/demand balance, major exporter/importer conditions, price targets, and grower decision guidance. Covers all major global commodities: wheat, corn, soybeans, rice, coffee, cocoa, cotton, palm oil, sugar, canola.",
        "x-agent-use-case": "on-demand",
        "x-price-usdc": "0.10",
        "x-data-sources": ["USDA WASDE", "FAO Food Price Index", "CME/CBOT/LIFFE futures context via Tavily"],
        "x-model": "claude-sonnet-4-6",
        "parameters": [
          { "name": "crop", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Commodity: wheat, corn, soybeans, rice, cotton, coffee, cocoa, sugar, canola, palm-oil, barley, oats" },
          { "name": "lang", "in": "query", "schema": { "type": "string", "default": "en" }, "description": "Response language" }
        ],
        "responses": {
          "200": { "description": "Commodity outlook", "content": { "application/json": { "schema": { "type": "object", "properties": { "market_outlook": { "type": "object" }, "supply_factors": { "type": "array" }, "demand_factors": { "type": "array" }, "price_targets": { "type": "object" }, "farmer_decision_guidance": { "type": "string" } } } } } },
          "402": { "description": "Payment required" }
        }
      }
    },
    "/api/input-cost": {
      "get": {
        "operationId": "inputCost",
        "summary": "Fertilizer, seed, and crop protection cost intelligence",
        "description": "Returns current fertilizer (N/P/K), seed, and crop protection pricing with trend direction, breakeven analysis, and cost reduction opportunities. Global regional coverage — prices quoted in USD with local market context. Agents can use this to model farm profitability and identify optimal input purchasing windows.",
        "x-agent-use-case": "on-demand",
        "x-price-usdc": "0.08",
        "x-data-sources": ["DTN/Progressive Farmer", "Crop Life", "Regional fertilizer market data via Tavily"],
        "x-model": "claude-haiku-4-5-20251001",
        "parameters": [
          { "name": "crop", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Crop: corn, wheat, soybeans, rice, cotton, canola, sugarcane, coffee, cocoa, potato" },
          { "name": "region", "in": "query", "schema": { "type": "string", "default": "United States" }, "description": "Region: 'US Corn Belt', 'Brazil', 'EU', 'India', 'Australia', 'Black Sea', 'Southeast Asia', etc." },
          { "name": "hectares", "in": "query", "schema": { "type": "string" }, "description": "Farm size in hectares (optional — enables total cost estimate)" },
          { "name": "lang", "in": "query", "schema": { "type": "string", "default": "en" }, "description": "Response language" }
        ],
        "responses": {
          "200": { "description": "Input cost intelligence", "content": { "application/json": { "schema": { "type": "object", "properties": { "fertilizer_costs": { "type": "object" }, "total_variable_cost_estimate": { "type": "object" }, "breakeven_price": { "type": "string" }, "cost_reduction_opportunities": { "type": "array" } } } } } },
          "402": { "description": "Payment required" }
        }
      }
    },
    "/api/planting-window": {
      "get": {
        "operationId": "plantingWindow",
        "summary": "Optimal planting window based on soil temperature and frost dates",
        "description": "Determines whether conditions are optimal for planting based on live soil temperature vs. germination threshold, last/first frost estimates, growing degree days, and regional crop calendar data. Works globally — southern hemisphere aware. Returns recommended planting action, soil readiness, and harvest window estimate.",
        "x-agent-use-case": "on-demand",
        "x-price-usdc": "0.05",
        "x-data-sources": ["Open-Meteo soil temperature + forecast", "Regional crop calendar data via Tavily"],
        "x-model": "claude-haiku-4-5-20251001",
        "parameters": [
          { "name": "lat", "in": "query", "required": true, "schema": { "type": "number" }, "description": "Field latitude" },
          { "name": "lon", "in": "query", "required": true, "schema": { "type": "number" }, "description": "Field longitude" },
          { "name": "crop", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Crop to plant: corn, wheat, soybeans, rice, cotton, sunflower, canola, potatoes, tomatoes, etc." },
          { "name": "lang", "in": "query", "schema": { "type": "string", "default": "en" }, "description": "Response language" }
        ],
        "responses": {
          "200": { "description": "Planting window recommendation", "content": { "application/json": { "schema": { "type": "object", "properties": { "planting_recommendation": { "type": "object" }, "soil_readiness": { "type": "object" }, "frost_risk": { "type": "object" }, "growing_season": { "type": "object" } } } } } },
          "402": { "description": "Payment required" }
        }
      }
    },
    "/api/season-brief": {
      "get": {
        "operationId": "seasonBrief",
        "summary": "Comprehensive seasonal agricultural intelligence brief",
        "description": "The highest-value FieldPulse endpoint — a complete seasonal intelligence brief for any crop and region. Covers global production outlook, weather situation (including El Niño/La Niña influence), crop health by region, market summary, top risks and opportunities, key dates (USDA reports, crop progress), and specific action items for growers, traders, and buyers. Used by commodity trading agents for weekly portfolio positioning.",
        "x-agent-use-case": "poll-weekly",
        "x-price-usdc": "0.20",
        "x-data-sources": ["Open-Meteo", "USDA WASDE", "FAO GIEWS", "GEOGLAM", "CME Group"],
        "x-model": "claude-sonnet-4-6",
        "parameters": [
          { "name": "crop", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Crop: wheat, corn, soybeans, rice, coffee, cocoa, cotton, sugar, palm-oil, canola, barley" },
          { "name": "region", "in": "query", "schema": { "type": "string" }, "description": "Focus region: 'Global', 'US', 'South America', 'Black Sea', 'EU', 'Asia', 'Sub-Saharan Africa', 'Australia'" },
          { "name": "lat", "in": "query", "schema": { "type": "number" }, "description": "Lat (alternative to region name for field-level context)" },
          { "name": "lon", "in": "query", "schema": { "type": "number" }, "description": "Lon" },
          { "name": "lang", "in": "query", "schema": { "type": "string", "default": "en" }, "description": "Response language" }
        ],
        "responses": {
          "200": { "description": "Season brief", "content": { "application/json": { "schema": { "type": "object", "properties": { "executive_summary": { "type": "string" }, "production_outlook": { "type": "object" }, "weather_situation": { "type": "object" }, "market_summary": { "type": "object" }, "top_risks": { "type": "array" }, "action_items": { "type": "object" } } } } } },
          "402": { "description": "Payment required" }
        }
      }
    }
  }
}