{
  "openapi": "3.1.0",
  "info": {
    "title": "ParikshaIndex",
    "description": "Indian government exams and jobs from official sources: status, last dates, vacancies, eligibility and the official notification PDFs, each with its ParikshaIndex page.",
    "version": "1.0.0"
  },
  "servers": [{ "url": "https://parikshaindex.com" }],
  "paths": {
    "/api/search": {
      "get": {
        "operationId": "searchExams",
        "summary": "Find exams, recruiting bodies, state job pages and official notices",
        "description": "Search in English or Hindi, e.g. 'ssc gd answer key 2026', 'rrb ntpc', 'bihar govt jobs', 'up police constable result'. Stage words (result, admit card, answer key, cut off, syllabus, notification, vacancy) and a year narrow the results. Exams come with a `details` URL; call getExam with the last part of it.",
        "parameters": [
          { "name": "q", "in": "query", "required": true, "schema": { "type": "string" }, "description": "What the user asked about: exam or body name, optionally a stage and a year" }
        ],
        "responses": {
          "200": {
            "description": "Best matches first (at most 10)",
            "content": { "application/json": { "schema": {
              "type": "object",
              "properties": {
                "results": { "type": "array", "items": {
                  "type": "object",
                  "properties": {
                    "type": { "type": "string", "enum": ["exam", "commission", "state", "notice"] },
                    "name": { "type": "string" },
                    "name_hi": { "type": "string" },
                    "page": { "type": "string", "description": "The ParikshaIndex page to link the user to" },
                    "details": { "type": "string", "description": "Exams only: JSON with status, dates, facts and documents" },
                    "status": { "type": "string" },
                    "exam": { "type": "string" },
                    "date": { "type": "string" }
                  }
                } }
              }
            } } }
          }
        }
      }
    },
    "/api/exam/{slug}.json": {
      "get": {
        "operationId": "getExam",
        "summary": "Current status, key facts and newest official documents of one exam",
        "parameters": [
          { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "From searchExams: the part of `details` between /api/exam/ and .json, e.g. ssc-cgl" }
        ],
        "responses": {
          "200": {
            "description": "The exam",
            "content": { "application/json": { "schema": {
              "type": "object",
              "properties": {
                "name": { "type": "string" },
                "official_name": { "type": "string" },
                "conducted_by": { "type": "string" },
                "page": { "type": "string", "description": "The exam's ParikshaIndex page" },
                "status": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "date": { "type": ["string", "null"] }, "tentative": { "type": "boolean" } } },
                "sections": { "type": "object", "additionalProperties": { "type": "string" }, "description": "ParikshaIndex pages for results, admit cards, answer keys, cut-offs, notifications…" },
                "facts": { "type": "object", "description": "Curated from official documents, each with its source URL: vacancies, age, fee, qualification, pay levels, dates, stages" },
                "documents": { "type": "array", "description": "Newest official documents first", "items": {
                  "type": "object",
                  "properties": {
                    "title": { "type": "string" },
                    "kind": { "type": "string" },
                    "date": { "type": ["string", "null"] },
                    "last_date": { "type": "string", "description": "Application last date read from the PDF" },
                    "pdf": { "type": ["string", "null"], "description": "Official PDF on the government site" },
                    "page": { "type": "string", "description": "ParikshaIndex page for this document" }
                  }
                } },
                "updated": { "type": "string" }
              }
            } } }
          },
          "404": { "description": "No such exam; search again" }
        }
      }
    }
  }
}