{
  "openapi": "3.1.0",
  "info": {
    "title": "ScholarPulse API",
    "description": "Global scholarship and student finance intelligence. 12 endpoints covering scholarship search (190+ countries), international scholarship matching, government programs, Erasmus+, US financial aid (College Scorecard), FAFSA strategy, student loan repayment (US/UK/AU/CA), loan forgiveness (PSLF/TEACH/state), degree ROI, merit aid, deadlines, and essay coaching. All endpoints require x402 payment (USDC on Base mainnet) via the PAYMENT-SIGNATURE header.",
    "version": "1.0.0",
    "contact": {
      "url": "https://scholarpulse-bice.vercel.app"
    }
  },
  "servers": [
    {
      "url": "https://scholarpulse-bice.vercel.app"
    }
  ],
  "components": {
    "securitySchemes": {
      "x402": {
        "type": "apiKey",
        "in": "header",
        "name": "PAYMENT-SIGNATURE",
        "description": "x402 payment signature (USDC on Base mainnet). Send a GET request without this header to receive a 402 response with payment requirements. Sign the payment and retry with the PAYMENT-SIGNATURE header."
      }
    }
  },
  "security": [{ "x402": [] }],
  "paths": {
    "/api/search": {
      "get": {
        "summary": "Scholarship search",
        "description": "Find matched scholarships globally by academic profile. Real-time sources, sorted by match strength and deadline urgency. Covers 190+ countries.",
        "operationId": "scholarshipSearch",
        "x-agent-use-case": "on-demand",
        "x-price-usd": 0.15,
        "parameters": [
          {"name": "major", "in": "query", "required": true, "schema": {"type": "string"}, "description": "Field of study (e.g. nursing, engineering, computer-science)"},
          {"name": "country", "in": "query", "required": false, "schema": {"type": "string"}, "description": "Country to search in (default: US)"},
          {"name": "level", "in": "query", "required": false, "schema": {"type": "string", "enum": ["undergraduate","graduate","phd","professional"]}, "description": "Education level"},
          {"name": "gpa", "in": "query", "required": false, "schema": {"type": "string"}, "description": "GPA (e.g. 3.8)"},
          {"name": "income", "in": "query", "required": false, "schema": {"type": "number"}, "description": "Household income for need-based filtering"},
          {"name": "demographic", "in": "query", "required": false, "schema": {"type": "string"}, "description": "first-gen | veteran | international | stem-women"},
          {"name": "lang", "in": "query", "required": false, "schema": {"type": "string"}, "description": "Response language (default: English)"}
        ],
        "responses": {
          "200": {"description": "Matched scholarships with amounts, deadlines, and match reasoning"},
          "402": {"description": "Payment required — see PAYMENT-REQUIRED header for x402 details"}
        }
      }
    },
    "/api/global": {
      "get": {
        "summary": "International scholarship matching",
        "description": "Cross-border funding for international students. Covers Chevening, DAAD, Fulbright, Commonwealth, Erasmus Mundus, CSC, MEXT, GKS, Türkiye Bursları, and 50+ government programs by nationality/destination.",
        "operationId": "globalScholarships",
        "x-agent-use-case": "on-demand",
        "x-price-usd": 0.15,
        "parameters": [
          {"name": "nationality", "in": "query", "required": true, "schema": {"type": "string"}, "description": "Student's nationality (e.g. Indian, Nigerian, Brazilian)"},
          {"name": "destination", "in": "query", "required": true, "schema": {"type": "string"}, "description": "Target country (e.g. UK, Germany, USA, Japan)"},
          {"name": "level", "in": "query", "required": false, "schema": {"type": "string"}, "description": "undergraduate | masters | phd"},
          {"name": "field", "in": "query", "required": false, "schema": {"type": "string"}, "description": "Field of study"},
          {"name": "lang", "in": "query", "required": false, "schema": {"type": "string"}, "description": "Response language"}
        ],
        "responses": {
          "200": {"description": "International scholarships with eligibility, amounts, timeline, and visa notes"},
          "402": {"description": "Payment required"}
        }
      }
    },
    "/api/government": {
      "get": {
        "summary": "Government scholarship programs",
        "description": "Official government scholarships by country. India NSP (100M+ eligible), US Pell/TEACH, UK Student Finance, Germany BAföG, Japan MEXT, South Africa NSFAS, Brazil ProUni, and 50+ country programs.",
        "operationId": "governmentPrograms",
        "x-agent-use-case": "on-demand",
        "x-price-usd": 0.10,
        "parameters": [
          {"name": "country", "in": "query", "required": true, "schema": {"type": "string"}, "description": "Country name"},
          {"name": "level", "in": "query", "required": false, "schema": {"type": "string"}, "description": "undergraduate | graduate | phd | vocational"},
          {"name": "field", "in": "query", "required": false, "schema": {"type": "string"}, "description": "Field filter"},
          {"name": "lang", "in": "query", "required": false, "schema": {"type": "string"}, "description": "Response language"}
        ],
        "responses": {
          "200": {"description": "Government programs with amounts, eligibility, and application guidance"},
          "402": {"description": "Payment required"}
        }
      }
    },
    "/api/erasmus": {
      "get": {
        "summary": "Erasmus+ program guide",
        "description": "EU student mobility: monthly grant amounts by country group (€700-1,000/month), KA131 vs Erasmus Mundus eligibility, application process, partner universities. 33 countries, 800+ universities, €26B budget 2021-2027.",
        "operationId": "erasmusGuide",
        "x-agent-use-case": "on-demand",
        "x-price-usd": 0.08,
        "parameters": [
          {"name": "from", "in": "query", "required": true, "schema": {"type": "string"}, "description": "Home EU/EEA country"},
          {"name": "to", "in": "query", "required": true, "schema": {"type": "string"}, "description": "Host country"},
          {"name": "field", "in": "query", "required": false, "schema": {"type": "string"}, "description": "Field of study"},
          {"name": "level", "in": "query", "required": false, "schema": {"type": "string"}, "description": "undergraduate | masters | phd"},
          {"name": "duration", "in": "query", "required": false, "schema": {"type": "number"}, "description": "Duration in months (2-12)"},
          {"name": "lang", "in": "query", "required": false, "schema": {"type": "string"}, "description": "Response language"}
        ],
        "responses": {
          "200": {"description": "Erasmus+ grant details, application process, and partner universities"},
          "402": {"description": "Payment required"}
        }
      }
    },
    "/api/aid": {
      "get": {
        "summary": "US financial aid estimate",
        "description": "College Scorecard federal data: net price by income bracket, Pell Grant eligibility, institutional generosity, 4-year cost estimate, and negotiation leverage for any US college.",
        "operationId": "financialAidEstimate",
        "x-agent-use-case": "on-demand",
        "x-price-usd": 0.12,
        "parameters": [
          {"name": "college", "in": "query", "required": true, "schema": {"type": "string"}, "description": "US college or university name"},
          {"name": "income", "in": "query", "required": true, "schema": {"type": "number"}, "description": "Household AGI"},
          {"name": "family_size", "in": "query", "required": false, "schema": {"type": "number"}, "description": "Household size (default: 4)"},
          {"name": "assets", "in": "query", "required": false, "schema": {"type": "number"}, "description": "Reportable assets (exclude retirement accounts)"},
          {"name": "dependency_status", "in": "query", "required": false, "schema": {"type": "string", "enum": ["dependent","independent"]}, "description": "Dependency status"},
          {"name": "lang", "in": "query", "required": false, "schema": {"type": "string"}, "description": "Response language"}
        ],
        "responses": {
          "200": {"description": "Net price estimate by income bracket, Pell eligibility, and 4-year cost projection"},
          "402": {"description": "Payment required"}
        }
      }
    },
    "/api/fafsa": {
      "get": {
        "summary": "FAFSA strategy",
        "description": "Student Aid Index estimate, Pell eligibility, maximize-aid action plan (timed and prioritized), asset strategy (what FAFSA counts vs exempts), filing deadlines, and common mistakes.",
        "operationId": "fafsaStrategy",
        "x-agent-use-case": "on-demand",
        "x-price-usd": 0.10,
        "parameters": [
          {"name": "income", "in": "query", "required": true, "schema": {"type": "number"}, "description": "Household AGI"},
          {"name": "family_size", "in": "query", "required": false, "schema": {"type": "number"}, "description": "Household size"},
          {"name": "assets", "in": "query", "required": false, "schema": {"type": "number"}, "description": "Reportable assets (NOT retirement accounts — those are exempt)"},
          {"name": "year", "in": "query", "required": false, "schema": {"type": "string"}, "description": "freshman | sophomore | junior | senior | graduate"},
          {"name": "dependency_status", "in": "query", "required": false, "schema": {"type": "string"}, "description": "dependent | independent"},
          {"name": "lang", "in": "query", "required": false, "schema": {"type": "string"}, "description": "Response language"}
        ],
        "responses": {
          "200": {"description": "SAI estimate, Pell eligibility, and maximize-aid action plan"},
          "402": {"description": "Payment required"}
        }
      }
    },
    "/api/loans": {
      "get": {
        "summary": "Student loan repayment strategy",
        "description": "Compares all applicable repayment plans by country: US (SAVE/IBR/PAYE/ICR/Standard/Extended), UK (Plan 2/Plan 5), Australia (HELP/HECS), Canada (RAP), New Zealand. Monthly payment, total interest, payoff timeline, and refinancing analysis.",
        "operationId": "loanRepayment",
        "x-agent-use-case": "on-demand",
        "x-price-usd": 0.12,
        "parameters": [
          {"name": "country", "in": "query", "required": false, "schema": {"type": "string"}, "description": "US | UK | Australia | Canada | New Zealand (default: US)"},
          {"name": "balance", "in": "query", "required": true, "schema": {"type": "number"}, "description": "Total loan balance"},
          {"name": "income", "in": "query", "required": true, "schema": {"type": "number"}, "description": "Annual income"},
          {"name": "loan_type", "in": "query", "required": false, "schema": {"type": "string"}, "description": "federal | private | HELP | Plan2 | OSAP"},
          {"name": "family_size", "in": "query", "required": false, "schema": {"type": "number"}, "description": "For US IDR plan calculations"},
          {"name": "years_in_repayment", "in": "query", "required": false, "schema": {"type": "number"}, "description": "Years already in repayment"},
          {"name": "lang", "in": "query", "required": false, "schema": {"type": "string"}, "description": "Response language"}
        ],
        "responses": {
          "200": {"description": "Repayment plan comparison with recommended plan and refinancing analysis"},
          "402": {"description": "Payment required"}
        }
      }
    },
    "/api/forgiveness": {
      "get": {
        "summary": "Loan forgiveness eligibility",
        "description": "PSLF eligibility with payment count estimate, TEACH Grant, Nurse Corps, NHSC, military forgiveness, profession-specific programs, state programs (50 states), and international equivalents. Includes action plan and timeline.",
        "operationId": "loanForgiveness",
        "x-agent-use-case": "on-demand",
        "x-price-usd": 0.10,
        "parameters": [
          {"name": "profession", "in": "query", "required": true, "schema": {"type": "string"}, "description": "teacher | nurse | doctor | social-worker | lawyer | military | government-employee | researcher | veterinarian"},
          {"name": "employer_type", "in": "query", "required": false, "schema": {"type": "string"}, "description": "public-school | nonprofit | government | private"},
          {"name": "country", "in": "query", "required": false, "schema": {"type": "string"}, "description": "Country (default: US)"},
          {"name": "state", "in": "query", "required": false, "schema": {"type": "string"}, "description": "US state for state-specific programs"},
          {"name": "years_in_service", "in": "query", "required": false, "schema": {"type": "number"}, "description": "Years in qualifying employment"},
          {"name": "loan_type", "in": "query", "required": false, "schema": {"type": "string"}, "description": "federal | private"},
          {"name": "lang", "in": "query", "required": false, "schema": {"type": "string"}, "description": "Response language"}
        ],
        "responses": {
          "200": {"description": "Forgiveness eligibility, estimated forgiveness amount, and action plan"},
          "402": {"description": "Payment required"}
        }
      }
    },
    "/api/roi": {
      "get": {
        "summary": "Degree ROI analysis",
        "description": "Median earnings by major/level (College Scorecard + BLS), debt-to-income ratio (excellent <0.75x | manageable 0.75-1.5x | concerning >1.5x), payoff timeline, best/worst case scenarios, and comparison to alternatives.",
        "operationId": "degreeROI",
        "x-agent-use-case": "on-demand",
        "x-price-usd": 0.10,
        "parameters": [
          {"name": "major", "in": "query", "required": true, "schema": {"type": "string"}, "description": "Field of study"},
          {"name": "degree_level", "in": "query", "required": false, "schema": {"type": "string"}, "description": "bachelor | master | phd | associate | professional"},
          {"name": "debt", "in": "query", "required": true, "schema": {"type": "number"}, "description": "Total expected debt at graduation"},
          {"name": "college", "in": "query", "required": false, "schema": {"type": "string"}, "description": "College for institution-specific earnings data"},
          {"name": "country", "in": "query", "required": false, "schema": {"type": "string"}, "description": "Country (default: US)"},
          {"name": "lang", "in": "query", "required": false, "schema": {"type": "string"}, "description": "Response language"}
        ],
        "responses": {
          "200": {"description": "ROI verdict with earnings data, debt analysis, and alternatives comparison"},
          "402": {"description": "Payment required"}
        }
      }
    },
    "/api/merit": {
      "get": {
        "summary": "Merit aid strategy",
        "description": "Colleges with automatic merit scholarships for this GPA/test profile. State programs: FL Bright Futures, GA HOPE, LA TOPS, WV full tuition, and 30+ others. Net cost estimates, stacking strategy, and score investment analysis.",
        "operationId": "meritAid",
        "x-agent-use-case": "on-demand",
        "x-price-usd": 0.12,
        "parameters": [
          {"name": "gpa", "in": "query", "required": true, "schema": {"type": "string"}, "description": "Unweighted GPA (e.g. 3.8)"},
          {"name": "test_score", "in": "query", "required": false, "schema": {"type": "string"}, "description": "SAT 1400 | ACT 32 | IB 38"},
          {"name": "major", "in": "query", "required": false, "schema": {"type": "string"}, "description": "Intended major"},
          {"name": "state", "in": "query", "required": false, "schema": {"type": "string"}, "description": "Home state"},
          {"name": "lang", "in": "query", "required": false, "schema": {"type": "string"}, "description": "Response language"}
        ],
        "responses": {
          "200": {"description": "Automatic merit scholarships, state programs, and stacking strategy"},
          "402": {"description": "Payment required"}
        }
      }
    },
    "/api/deadline": {
      "get": {
        "summary": "Scholarship deadline tracker",
        "description": "Real-time scholarship deadlines sorted by urgency (days remaining), with amounts, difficulty rating, and quick-win opportunities (short applications, real money). Poll weekly for fresh results.",
        "operationId": "scholarshipDeadlines",
        "x-agent-use-case": "poll-weekly",
        "x-price-usd": 0.08,
        "parameters": [
          {"name": "country", "in": "query", "required": false, "schema": {"type": "string"}, "description": "Country (default: US)"},
          {"name": "major", "in": "query", "required": false, "schema": {"type": "string"}, "description": "Field of study"},
          {"name": "level", "in": "query", "required": false, "schema": {"type": "string"}, "description": "undergraduate | graduate | phd"},
          {"name": "month", "in": "query", "required": false, "schema": {"type": "string"}, "description": "next | this-month | next-3-months"},
          {"name": "state", "in": "query", "required": false, "schema": {"type": "string"}, "description": "US state for local scholarships"},
          {"name": "lang", "in": "query", "required": false, "schema": {"type": "string"}, "description": "Response language"}
        ],
        "responses": {
          "200": {"description": "Upcoming deadlines sorted by urgency with quick-win opportunities"},
          "402": {"description": "Payment required"}
        }
      }
    },
    "/api/essay": {
      "get": {
        "summary": "Scholarship essay strategy",
        "description": "Committee values, optimal angle, structure, voice, and insider tips specific to each scholarship and prompt. Strategic coaching only — not AI-generated content.",
        "operationId": "essayStrategy",
        "x-agent-use-case": "on-demand",
        "x-price-usd": 0.10,
        "parameters": [
          {"name": "scholarship", "in": "query", "required": true, "schema": {"type": "string"}, "description": "Scholarship name (e.g. Gates Scholarship, Chevening, DAAD, Rhodes)"},
          {"name": "prompt", "in": "query", "required": true, "schema": {"type": "string"}, "description": "The essay prompt text"},
          {"name": "word_limit", "in": "query", "required": false, "schema": {"type": "number"}, "description": "Word limit"},
          {"name": "background", "in": "query", "required": false, "schema": {"type": "string"}, "description": "Brief student background"},
          {"name": "lang", "in": "query", "required": false, "schema": {"type": "string"}, "description": "Response language"}
        ],
        "responses": {
          "200": {"description": "Essay strategy with angle, structure, voice, and insider tips"},
          "402": {"description": "Payment required"}
        }
      }
    }
  }
}