{
  "openapi": "3.1.0",
  "info": {
    "title": "AI Coach for Indian Competitive Exams — by MockTestZone",
    "description": "Public read-only Action API providing 5 validated teaching sample questions per exam (SSC CGL, RRB NTPC, CAT IIM) with all 4 MCQ options, Setter-Trap diagnostics (whyWrong / misconception), built-in In-Test AI Hint previews (Level 1 Nudge), fast exam-hall shortcuts, SHA-256 citation-backed official cut-off highlights, and the 500-question CC-BY-4.0 Open Benchmark preview. Strictly capped at 5 sample questions per category with zero full-mock spoilers.",
    "version": "1.1.0"
  },
  "servers": [
    {
      "url": "https://www.mocktestzone.in",
      "description": "MockTestZone Production Public AI Feed"
    }
  ],
  "paths": {
    "/api/ai-public/sample-drill": {
      "get": {
        "operationId": "getExamSampleDrillAndCutoffs",
        "summary": "Fetch 5 validated high-trap sample questions, all 4 MCQ options, In-Test AI Hints, and official cut-off highlights for SSC CGL, RRB NTPC, or CAT.",
        "description": "Returns a fixed 5-question teaching unit with 4 options (A–D) per question, Setter-Trap misconception warnings, Socratic Level-1 AI hints, 25-second exam-hall shortcuts, official cited cut-off highlights, and direct links to start a free full-length timed mock test on MockTestZone.",
        "parameters": [
          {
            "name": "exam",
            "in": "query",
            "required": true,
            "description": "Target exam identifier: 'ssc-cgl' (SSC CGL Tier-I), 'rrb-ntpc' (RRB NTPC CBT-1), or 'cat' (CAT IIM).",
            "schema": {
              "type": "string",
              "enum": ["ssc-cgl", "rrb-ntpc", "cat"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "5 validated sample questions with 4 options each, Setter-Trap warnings, In-Test AI Hints, and official cut-off highlights.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "exam",
                    "category",
                    "title",
                    "markingSummary",
                    "selectionPolicy",
                    "officialCutoffHighlights",
                    "sampleQuestions",
                    "nextStepLinks"
                  ],
                  "properties": {
                    "exam": { "type": "string" },
                    "category": { "type": "string" },
                    "title": { "type": "string" },
                    "markingSummary": { "type": "string" },
                    "selectionPolicy": {
                      "type": "object",
                      "properties": {
                        "maxQuestions": { "type": "integer", "enum": [5] },
                        "excludesFullMocks": { "type": "boolean" },
                        "excludesSeriesDaySlots": { "type": "boolean" },
                        "excludesPremiumTests": { "type": "boolean" }
                      }
                    },
                    "officialCutoffHighlights": {
                      "type": "object",
                      "properties": {
                        "conductingBody": { "type": "string" },
                        "cycleLabel": { "type": "string" },
                        "headlineFigures": {
                          "type": "array",
                          "items": { "type": "string" }
                        },
                        "cutoffPageUrl": { "type": "string" },
                        "markdownFeedUrl": { "type": "string" }
                      }
                    },
                    "sampleQuestions": {
                      "type": "array",
                      "maxItems": 5,
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": { "type": "string" },
                          "number": { "type": "integer" },
                          "topic": { "type": "string" },
                          "subtopic": { "type": "string" },
                          "difficulty": { "type": "string" },
                          "marks": { "type": "string" },
                          "targetSeconds": { "type": "integer" },
                          "stem": { "type": "string" },
                          "options": {
                            "type": "array",
                            "maxItems": 4,
                            "items": {
                              "type": "object",
                              "properties": {
                                "label": { "type": "string", "enum": ["A", "B", "C", "D"] },
                                "text": { "type": "string" },
                                "isCorrect": { "type": "boolean" },
                                "isPrimaryTrap": { "type": "boolean" },
                                "whyWrong": { "type": ["string", "null"] },
                                "misconception": { "type": ["string", "null"] }
                              }
                            }
                          },
                          "correctOption": { "type": "string", "enum": ["A", "B", "C", "D"] },
                          "inTestAiHint": {
                            "type": "object",
                            "properties": {
                              "badgeLabel": { "type": "string" },
                              "levelLabel": { "type": "string" },
                              "promptText": { "type": "string" }
                            }
                          },
                          "setterTrap": {
                            "type": "object",
                            "properties": {
                              "trapOption": { "type": "string", "enum": ["A", "B", "C", "D"] },
                              "misconceptionLabel": { "type": "string" },
                              "whyWrong": { "type": "string" }
                            }
                          },
                          "fastShortcut": { "type": "string" },
                          "sourceExamTitle": { "type": "string" },
                          "practiceHref": { "type": "string" }
                        }
                      }
                    },
                    "nextStepLinks": {
                      "type": "object",
                      "properties": {
                        "startFreeFullMockUrl": { "type": "string" },
                        "officialCutoffsUrl": { "type": "string" },
                        "officialCutoffsMarkdownUrl": { "type": "string" },
                        "aiCoachOverviewUrl": { "type": "string" }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/ai-public/open-benchmark-preview": {
      "get": {
        "operationId": "getOpenSetterTrapBenchmarkPreview",
        "summary": "Fetch metadata and 5 representative cross-exam rows (SSC, Railway, Banking, CAT, UPSC) from the 500-question CC-BY-4.0 Setter-Trap & AI-Hint Open Benchmark.",
        "description": "Returns dataset provenance, CC-BY-4.0 license metadata, schema field definitions, and 1 representative high-trap question each across SSC CGL, RRB NTPC, IBPS/SBI PO Banking, CAT, and UPSC Prelims.",
        "responses": {
          "200": {
            "description": "Open Benchmark metadata and 5 representative cross-exam diagnostic items.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "dataset": { "type": "string" },
                    "version": { "type": "string" },
                    "license": { "type": "string" },
                    "licenseUrl": { "type": "string" },
                    "canonicalUrl": { "type": "string" },
                    "markdownUrl": { "type": "string" },
                    "totalBenchmarkRows": { "type": "integer" },
                    "representativeRows": {
                      "type": "array",
                      "items": { "type": "object" }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}