{
 "openapi": "3.1.0",
 "info": {
  "title": "EduPulse API",
  "description": "Global education intelligence API — 14 endpoints for students, test-takers, homeschool families, and lifelong learners worldwide. Study guide generation (any subject, any grade level, 190+ countries), adaptive quiz with explanations, concept explainer, backwards-planned study schedule (with Magoosh/Kaplan/Coursera exam prep links), authentic exam-style practice questions (GRE/GMAT/Bar/CPA/NCLEX/LSAT/MCAT/Series 7 and 200+ exams), flashcard sets for spaced repetition, exam format explainer, full mock exam simulation, misconception diagnosis (pinpoints the exact knowledge gap behind a wrong answer), rubric-based exam grading with detailed feedback, homeschool co-op/support-group finder, homeschool curriculum matcher, college admissions essay review, and homeschool legal-requirements lookup by jurisdiction. All require x402 micropayment (USDC on Base).",
  "version": "1.3.0",
  "contact": {
   "url": "https://edupulse.vercel.app"
  }
 },
 "servers": [
  {
   "url": "https://edupulse.vercel.app"
  }
 ],
 "components": {
  "securitySchemes": {
   "x402": {
    "type": "apiKey",
    "in": "header",
    "name": "PAYMENT-SIGNATURE",
    "description": "x402 payment signature. Send without this header to receive a 402 with payment requirements. Sign and retry."
   }
  }
 },
 "security": [
  {
   "x402": []
  }
 ],
 "paths": {
  "/api/study/guide": {
   "get": {
    "summary": "Study guide generation — any subject, any grade, any country",
    "description": "Generates a complete, structured study guide for any topic at any grade level. Adapts to 190+ educational systems globally (US Common Core, UK National Curriculum, IB, French Baccalauréat, etc.). Includes key concepts, worked examples, mnemonics, and exam tips. Supports ?lang= for response in any language.",
    "operationId": "studyGuide",
    "parameters": [
     {
      "name": "grade",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "Grade level: K, 1-12"
     },
     {
      "name": "subject",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "Subject (algebra, biology, chemistry, history, etc.)"
     },
     {
      "name": "topic",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "Specific topic within the subject"
     },
     {
      "name": "lang",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Response language code (e.g. es, fr, zh, ja)"
     },
     {
      "name": "PAYMENT-SIGNATURE",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Study guide"
     },
     "402": {
      "description": "Payment required"
     }
    },
    "x-price-usd": 0.1,
    "x-agent-use-case": "on-demand"
   }
  },
  "/api/study/quiz": {
   "get": {
    "summary": "Practice quiz with adaptive difficulty and answer explanations",
    "description": "Generates a practice quiz for any subject with MCQ, short answer, and true/false formats. Each answer includes a detailed explanation of why it is correct and why distractors are wrong. Adaptive difficulty: set ?level= from beginner to advanced. Global curriculum coverage.",
    "operationId": "studyQuiz",
    "parameters": [
     {
      "name": "grade",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "subject",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "topic",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "questions",
      "in": "query",
      "required": false,
      "schema": {
       "type": "integer",
       "default": 5,
       "maximum": 15
      }
     },
     {
      "name": "difficulty",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string",
       "enum": [
        "easy",
        "medium",
        "hard",
        "mixed"
       ]
      }
     },
     {
      "name": "lang",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "PAYMENT-SIGNATURE",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Quiz with answer explanations"
     },
     "402": {
      "description": "Payment required"
     }
    },
    "x-price-usd": 0.1,
    "x-agent-use-case": "on-demand"
   }
  },
  "/api/study/explain": {
   "get": {
    "summary": "Concept explainer — any topic at any level from 5th grade to PhD",
    "description": "Explains any concept at the requested level — from 'explain like I'm 12' to graduate-level rigor. Uses analogies, visual descriptions, real-world examples, and connects to related concepts. Essential for self-directed learners in any country.",
    "operationId": "studyExplain",
    "parameters": [
     {
      "name": "concept",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "grade",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "audience",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "e.g. 'nursing student', 'Series 7 candidate', 'adult learner'"
     },
     {
      "name": "lang",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "PAYMENT-SIGNATURE",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Concept explanation"
     },
     "402": {
      "description": "Payment required"
     }
    },
    "x-price-usd": 0.05,
    "x-agent-use-case": "on-demand"
   }
  },
  "/api/study/schedule": {
   "get": {
    "summary": "Backwards-planned study schedule — from exam date to today, with daily tasks",
    "description": "Generates a complete backwards-planned study schedule from exam date to today. Breaks the syllabus into daily/weekly tasks, accounts for hours available per week, and includes milestone checkpoints. Response includes Magoosh/Kaplan exam prep links and Coursera/Udemy course links.",
    "operationId": "studySchedule",
    "parameters": [
     {
      "name": "exam",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string",
       "enum": [
        "NCLEX",
        "Series-3",
        "Series-7",
        "CPA",
        "LSAT",
        "MCAT",
        "Bar",
        "PMP",
        "AWS-SAA",
        "CompTIA-Security-Plus",
        "USMLE-Step-1",
        "USMLE-Step-2",
        "SAT",
        "GRE",
        "GMAT"
       ]
      }
     },
     {
      "name": "date",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string",
       "format": "date"
      },
      "description": "Exam date YYYY-MM-DD"
     },
     {
      "name": "hours_per_week",
      "in": "query",
      "required": false,
      "schema": {
       "type": "integer",
       "default": 15
      }
     },
     {
      "name": "lang",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "PAYMENT-SIGNATURE",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Study schedule"
     },
     "402": {
      "description": "Payment required"
     }
    },
    "x-price-usd": 0.1,
    "x-agent-use-case": "on-demand",
    "x-agent-chaining": "Response includes Magoosh/Kaplan and Coursera/Udemy links; pair with /api/exam/prep for practice questions alongside the schedule"
   }
  },
  "/api/exam/prep": {
   "get": {
    "summary": "Exam-style practice questions — 200+ exams, rubric-matched difficulty",
    "description": "Generates authentic exam-style practice questions matched to official rubrics for 200+ exams: GRE, GMAT, Bar, CPA, CFA, NCLEX, LSAT, MCAT, Series 7/66, USMLE, IELTS, TOEFL, SAT, ACT, and more. Questions are exam-specific in format, difficulty, and style. Response includes Magoosh/Kaplan/Princeton Review affiliate links matched to exam type.",
    "operationId": "examPrep",
    "parameters": [
     {
      "name": "exam",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "topic",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "questions",
      "in": "query",
      "required": false,
      "schema": {
       "type": "integer",
       "default": 5,
       "maximum": 10
      }
     },
     {
      "name": "difficulty",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string",
       "enum": [
        "easy",
        "medium",
        "hard"
       ]
      }
     },
     {
      "name": "lang",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "PAYMENT-SIGNATURE",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Exam-style questions with rationales"
     },
     "402": {
      "description": "Payment required"
     }
    },
    "x-price-usd": 1.0,
    "x-agent-use-case": "on-demand",
    "x-agent-chaining": "Response includes exam prep platform links matched to exam type; follow with /api/study/schedule for a complete study plan"
   }
  },
  "/api/exam/flashcards": {
   "get": {
    "summary": "Spaced-repetition flashcard set — import into Anki or Quizlet",
    "description": "Generates a structured flashcard set for any exam topic optimized for spaced repetition. Output is structured for easy import into Anki (.apkg format) or Quizlet. Includes front, back, and hint fields. Any subject, any exam, any language.",
    "operationId": "examFlashcards",
    "parameters": [
     {
      "name": "exam",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "topic",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "section",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Exam section (e.g. FAR for CPA)"
     },
     {
      "name": "count",
      "in": "query",
      "required": false,
      "schema": {
       "type": "integer",
       "default": 10,
       "maximum": 20
      }
     },
     {
      "name": "lang",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "PAYMENT-SIGNATURE",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Flashcard set"
     },
     "402": {
      "description": "Payment required"
     }
    },
    "x-price-usd": 0.5,
    "x-agent-use-case": "on-demand"
   }
  },
  "/api/exam/explain": {
   "get": {
    "summary": "Exam format explainer — complete breakdown of any exam structure and strategy",
    "description": "Complete breakdown of any exam: sections, timing, question types, scoring rubric, passing requirements, and score interpretation. Includes strategic advice (time allocation, question ordering, flagging strategy, partial credit rules). Works for any exam globally.",
    "operationId": "examExplain",
    "parameters": [
     {
      "name": "exam",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "question_type",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "e.g. NGN, logic-games, task-based-simulation, data-sufficiency"
     },
     {
      "name": "lang",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "PAYMENT-SIGNATURE",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Format explainer with worked example"
     },
     "402": {
      "description": "Payment required"
     }
    },
    "x-price-usd": 0.5,
    "x-agent-use-case": "on-demand"
   }
  },
  "/api/exam/mock": {
   "get": {
    "summary": "Full mock exam simulation — timed, scored, with performance report",
    "description": "Generates a full 20-question mock exam with authentic question formats, real content-area weighting, and a complete answer key with rationales for self-grading. Includes a generic scoring guide (score-band interpretations and a next-steps recommendation) — the response does not grade your actual answers. Response includes exam prep affiliate links for follow-up study.",
    "operationId": "examMock",
    "parameters": [
     {
      "name": "exam",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "duration",
      "in": "query",
      "required": false,
      "schema": {
       "type": "integer",
       "default": 60
      },
      "description": "Duration in minutes"
     },
     {
      "name": "lang",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "PAYMENT-SIGNATURE",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Mock exam with answer key"
     },
     "402": {
      "description": "Payment required"
     }
    },
    "x-price-usd": 1.0,
    "x-agent-use-case": "on-demand",
    "x-agent-chaining": "Response includes exam prep platform links matched to exam type; follow with /api/study/schedule for a complete study plan"
   }
  },
  "/api/study/misconception": {
   "get": {
    "operationId": "studyMisconception",
    "summary": "Misconception diagnosis — pinpoints the exact knowledge gap behind a wrong answer",
    "description": "Advanced learning diagnostic: given a student's wrong answer, identifies the specific misconception or knowledge gap that caused it — not just \"incorrect\" but exactly what the student believes that is wrong, why that belief formed, and how to correct it. Especially valuable for teachers, tutors, and adaptive learning systems. Works for any subject worldwide.",
    "parameters": [
     {
      "name": "question",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "The exam/study question"
     },
     {
      "name": "answer",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "The student's wrong answer"
     },
     {
      "name": "subject",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "level",
      "in": "query",
      "schema": {
       "type": "string"
      },
      "description": "Grade level or exam type"
     },
     {
      "name": "lang",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "PAYMENT-SIGNATURE",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Misconception analysis with root cause, correction, and targeted review materials"
     },
     "402": {
      "description": "Payment required"
     }
    },
    "x-price-usd": 0.1,
    "x-agent-use-case": "on-demand"
   }
  },
  "/api/exam/grade": {
   "get": {
    "operationId": "examGrade",
    "summary": "Rubric-based exam grading — written response scoring with detailed feedback",
    "description": "Rubric-based grading for written exam responses: Bar exam essays (MEE, MPT, MBE performance tests), CPA BEC written communications, NCLEX SATA, LSAT analytical reasoning, GRE/GMAT essays, and law school exam answers. Returns a score with rubric breakdown, strength/weakness identification, and specific improvement suggestions. Covers all major professional and graduate-level written exams.",
    "parameters": [
     {
      "name": "exam",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "Exam type (e.g. Bar, CPA-BEC, GRE, LSAT)",
      "example": "Bar"
     },
     {
      "name": "question",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "response",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "The student response to grade"
     },
     {
      "name": "lang",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "PAYMENT-SIGNATURE",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Graded response with score, rubric breakdown, and improvement feedback"
     },
     "402": {
      "description": "Payment required"
     }
    },
    "x-price-usd": 1.0,
    "x-agent-use-case": "on-demand",
    "x-agent-chaining": "Response includes exam prep links; follow with /api/exam/prep for targeted practice on weak areas identified"
   }
  },
  "/api/edu/co-op-guide": {
   "get": {
    "summary": "Homeschool co-op finder — live web search for local groups and support communities",
    "description": "Where can I find a homeschool co-op or support group near me? Locates active homeschool co-ops, support groups, and educational communities for any area via live web search, with evaluation criteria, cost expectations, and how-to-start guidance if none exist yet locally.",
    "operationId": "eduCoOpGuide",
    "parameters": [
     {
      "name": "state",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "State or region — e.g. \"Texas\" | \"Ohio\""
     },
     {
      "name": "city",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "City or metro area — improves result specificity"
     },
     {
      "name": "child_ages",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string",
       "default": "all ages"
      },
      "description": "Child ages (e.g. 5-10, all ages)"
     },
     {
      "name": "focus",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string",
       "enum": [
        "academic",
        "enrichment",
        "both"
       ],
       "default": "both"
      },
      "description": "Focus (academic, enrichment, both)"
     },
     {
      "name": "lang",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Response language (default en)"
     },
     {
      "name": "PAYMENT-SIGNATURE",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Homeschool co-op guide with live search results, evaluation criteria, and startup guidance"
     },
     "402": {
      "description": "Payment required"
     }
    },
    "x-price-usd": 0.1,
    "x-agent-use-case": "on-demand"
   }
  },
  "/api/edu/curriculum-match": {
   "get": {
    "summary": "Homeschool curriculum finder — personalized matches by grade, subject, and learning style",
    "description": "What curriculum should I use for homeschooling? Returns personalized homeschool curriculum recommendations by grade, subject, learning style, and religious preference, with side-by-side comparisons and at least one free or low-cost option.",
    "operationId": "eduCurriculumMatch",
    "parameters": [
     {
      "name": "grade",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "Grade level (K-12)"
     },
     {
      "name": "subject",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "Subject"
     },
     {
      "name": "style",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string",
       "enum": [
        "classical",
        "charlotte-mason",
        "traditional",
        "eclectic",
        "unschooling",
        "online",
        "unit-studies",
        "any"
       ],
       "default": "any"
      },
      "description": "Learning style"
     },
     {
      "name": "religious",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string",
       "default": "none"
      },
      "description": "Religious preference (none, christian, catholic, etc. — default none includes all)"
     },
     {
      "name": "lang",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Response language (default en)"
     },
     {
      "name": "PAYMENT-SIGNATURE",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Homeschool curriculum comparison with recommendations by grade, subject, and learning style"
     },
     "402": {
      "description": "Payment required"
     }
    },
    "x-price-usd": 0.1,
    "x-agent-use-case": "on-demand"
   }
  },
  "/api/edu/essay": {
   "get": {
    "summary": "College admissions essay review — admissions-coach feedback",
    "description": "Is my college application essay good? What should I fix? Returns admissions-coach feedback on a personal statement or supplemental essay, optionally tailored to a target school and the essay prompt. For applicants worldwide.",
    "operationId": "eduEssay",
    "parameters": [
     {
      "name": "essay",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "Essay text (min. 50 characters). Use POST body for long essays."
     },
     {
      "name": "school",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Target school"
     },
     {
      "name": "prompt",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Essay prompt"
     },
     {
      "name": "lang",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Response language (default en)"
     },
     {
      "name": "PAYMENT-SIGNATURE",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Admissions-coach essay review with strengths, weaknesses, and line-level feedback"
     },
     "402": {
      "description": "Payment required"
     }
    },
    "x-price-usd": 0.25,
    "x-agent-use-case": "on-demand"
   }
  },
  "/api/edu/homeschool-laws": {
   "get": {
    "summary": "Homeschool law lookup — legal requirements and compliance checklist by jurisdiction",
    "description": "Is homeschooling legal here, and what are the requirements? Returns notification rules, curriculum mandates, testing requirements, and a compliance checklist for any US state (all 50) or country, backed by live web research.",
    "operationId": "eduHomeschoolLaws",
    "parameters": [
     {
      "name": "state",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "US state name/abbreviation or country — e.g. \"California\" | \"TX\" | \"New York\""
     },
     {
      "name": "lang",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "Response language (default en)"
     },
     {
      "name": "PAYMENT-SIGNATURE",
      "in": "header",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Homeschool legal compliance guide with notification rules and requirements checklist"
     },
     "402": {
      "description": "Payment required"
     }
    },
    "x-price-usd": 0.1,
    "x-agent-use-case": "on-demand"
   }
  }
 }
}