{
  "openapi": "3.1.0",
  "info": {
    "title": "CertScroll Question Bank & Agent Evaluation API",
    "version": "1.0.0",
    "description": "Official Agent-to-Agent REST API and MCP Question Engine for CertScroll (study.wanessalabs.com). Provides 2,050 syllabus-cited AI certification questions across 10 certification tracks, 45 core concepts, and 4 cognitive difficulty tiers with built-in answer grading, domain blueprinting, and evaluation masking.",
    "contact": {
      "name": "Wanessa Labs",
      "url": "https://www.wanessalabs.com"
    },
    "license": {
      "name": "Proprietary / Wanessa Labs"
    }
  },
  "servers": [
    {
      "url": "https://study.wanessalabs.com/api/v1",
      "description": "Production Cloudflare Pages API"
    },
    {
      "url": "http://localhost:4321/api/v1",
      "description": "Local Development Server"
    }
  ],
  "tags": [
    {
      "name": "Questions",
      "description": "Query and retrieve syllabus-grounded certification questions"
    },
    {
      "name": "Grading",
      "description": "Evaluate agent submissions and return rationale & leaf citations"
    },
    {
      "name": "Exams",
      "description": "Generate domain-weighted stratified blueprint mock exam batches"
    },
    {
      "name": "Concepts",
      "description": "Retrieve core AI knowledge graphs and concept blueprints"
    },
    {
      "name": "Certifications",
      "description": "Certification syllabi, domains, and weighting blueprints"
    },
    {
      "name": "Analytics",
      "description": "Matrix coverage and cognitive ladder statistics"
    }
  ],
  "paths": {
    "/questions": {
      "get": {
        "tags": [
          "Questions"
        ],
        "summary": "List and filter questions from the question bank",
        "description": "Retrieve a paginated list of verified certification questions filtered by cert, domain, concept, difficulty, and review tier. Supports blind evaluation masking via `maskAnswers=true`.",
        "operationId": "listQuestions",
        "parameters": [
          {
            "name": "cert",
            "in": "query",
            "description": "Filter by certification ID (e.g., `aws-mla-c01`, `anthropic-claude-certified-architect`, `nvidia-nca-genl`)",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "domain",
            "in": "query",
            "description": "Filter by specific domain slug within the cert syllabus",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "concept",
            "in": "query",
            "description": "Filter by shared core AI concept slug (e.g., `rag-chunking`, `lora`, `temperature`, `agent-loop`)",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "difficulty",
            "in": "query",
            "description": "Cognitive difficulty ladder level",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "recall",
                "discrimination",
                "application",
                "diagnosis"
              ]
            }
          },
          {
            "name": "reviewTier",
            "in": "query",
            "description": "Filter by provenance review tier: `read` (human verified) or `derived` (synthetically generated from reviewed concept)",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "read",
                "derived"
              ]
            }
          },
          {
            "name": "scope",
            "in": "query",
            "description": "`cert` (cert-specific questions) or `shared` (cross-cert foundation questions)",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "cert",
                "shared"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Number of questions to return (1-100, default 20)",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 20,
              "minimum": 1,
              "maximum": 100
            }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Pagination offset (default 0)",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 0,
              "minimum": 0
            }
          },
          {
            "name": "maskAnswers",
            "in": "query",
            "description": "When true, omits correctIndex, explanation, and reviewer metadata for blind evaluation test harnesses",
            "required": false,
            "schema": {
              "type": "boolean",
              "default": false
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated questions list successfully retrieved",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QuestionsListResponse"
                }
              }
            }
          }
        }
      }
    },
    "/questions/{id}": {
      "get": {
        "tags": [
          "Questions"
        ],
        "summary": "Get a single question by ID",
        "description": "Fetch detailed question stem, 4 options, official syllabus leaf source, and explanation.",
        "operationId": "getQuestionById",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Unique question slug ID",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "maskAnswer",
            "in": "query",
            "required": false,
            "description": "When true, masks correct answer key",
            "schema": {
              "type": "boolean",
              "default": false
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Question found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicQuestionItem"
                }
              }
            }
          },
          "404": {
            "description": "Question not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/grade": {
      "post": {
        "tags": [
          "Grading"
        ],
        "summary": "Grade an agent submission and receive syllabus rationale",
        "description": "Submit an agent choice (0-3) and optional reasoning for a question. Returns pass/fail result, correct index, official leaf spine citation, and in-depth explanation.",
        "operationId": "gradeQuestion",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GradeRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Submission evaluated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GradeResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid option index or payload",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Question not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/mock-exam": {
      "post": {
        "tags": [
          "Exams"
        ],
        "summary": "Generate a domain-stratified mock exam batch",
        "description": "Generate a calibrated mock exam batch (15, 25, or 50 questions) weighted by published domain percentages and stratified across the 4 cognitive tiers.",
        "operationId": "generateMockExam",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MockExamRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Mock exam batch generated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MockExamResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid question count or parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Certification not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/certs": {
      "get": {
        "tags": [
          "Certifications"
        ],
        "summary": "List all supported certification tracks",
        "description": "Get all 10 certifications with syllabus domains, weights, and provider details.",
        "operationId": "listCerts",
        "responses": {
          "200": {
            "description": "List of certifications",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Cert"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/certs/{id}": {
      "get": {
        "tags": [
          "Certifications"
        ],
        "summary": "Get certification syllabus blueprint and domain weights",
        "description": "Get detailed syllabus blueprint, domain weighting, and available question count.",
        "operationId": "getCertBlueprint",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Certification blueprint retrieved",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CertWithQuestions"
                }
              }
            }
          },
          "404": {
            "description": "Certification not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/concepts": {
      "get": {
        "tags": [
          "Concepts"
        ],
        "summary": "List all 45 core AI concepts",
        "description": "Get all shared core AI concepts, alias vocabularies, definitions, and cert linkages.",
        "operationId": "listConcepts",
        "responses": {
          "200": {
            "description": "List of concepts",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Concept"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/concepts/{slug}": {
      "get": {
        "tags": [
          "Concepts"
        ],
        "summary": "Get concept blueprint and knowledge graph node",
        "description": "Retrieve concept definition, exam relevance, connected question count, and difficulty coverage.",
        "operationId": "getConceptBlueprint",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Concept blueprint node retrieved",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConceptBlueprintResponse"
                }
              }
            }
          },
          "404": {
            "description": "Concept not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/matrix": {
      "get": {
        "tags": [
          "Analytics"
        ],
        "summary": "Get 100% matrix coverage and difficulty breakdown",
        "description": "Live statistics across all 765 reachable cells, cognitive tiers, and certifications.",
        "operationId": "getMatrixCoverage",
        "responses": {
          "200": {
            "description": "Matrix analytics payload",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MatrixCoverageResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "MaskedQuestionOption": {
        "type": "object",
        "properties": {
          "index": {
            "type": "integer",
            "minimum": 0,
            "maximum": 3
          },
          "text": {
            "type": "string"
          }
        },
        "required": [
          "index",
          "text"
        ]
      },
      "PublicQuestionItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "cert": {
            "type": "string"
          },
          "domain": {
            "type": "string"
          },
          "stem": {
            "type": "string"
          },
          "options": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/MaskedQuestionOption"
            },
            "minItems": 4,
            "maxItems": 4
          },
          "conceptIds": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "difficulty": {
            "type": "string",
            "enum": [
              "recall",
              "discrimination",
              "application",
              "diagnosis"
            ]
          },
          "scope": {
            "type": "string",
            "enum": [
              "cert",
              "shared"
            ]
          },
          "reviewTier": {
            "type": "string",
            "enum": [
              "read",
              "derived"
            ]
          },
          "source": {
            "type": "string"
          },
          "scenarioId": {
            "type": "string"
          },
          "scenarioStep": {
            "type": "integer"
          },
          "correctIndex": {
            "type": "integer",
            "minimum": 0,
            "maximum": 3
          },
          "explanation": {
            "type": "string"
          },
          "reviewedBy": {
            "type": "string"
          },
          "reviewedOn": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "cert",
          "domain",
          "stem",
          "options",
          "conceptIds",
          "difficulty",
          "scope",
          "reviewTier",
          "source"
        ]
      },
      "QuestionsListResponse": {
        "type": "object",
        "properties": {
          "total": {
            "type": "integer"
          },
          "limit": {
            "type": "integer"
          },
          "offset": {
            "type": "integer"
          },
          "hasMore": {
            "type": "boolean"
          },
          "filters": {
            "type": "object",
            "properties": {
              "cert": {
                "type": "string"
              },
              "domain": {
                "type": "string"
              },
              "concept": {
                "type": "string"
              },
              "difficulty": {
                "type": "string"
              },
              "reviewTier": {
                "type": "string"
              },
              "scope": {
                "type": "string"
              }
            }
          },
          "questions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PublicQuestionItem"
            }
          }
        },
        "required": [
          "total",
          "limit",
          "offset",
          "hasMore",
          "filters",
          "questions"
        ]
      },
      "GradeRequest": {
        "type": "object",
        "properties": {
          "questionId": {
            "type": "string"
          },
          "selectedOption": {
            "type": "integer",
            "minimum": 0,
            "maximum": 3
          },
          "agentReasoning": {
            "type": "string"
          }
        },
        "required": [
          "questionId",
          "selectedOption"
        ]
      },
      "GradeResponse": {
        "type": "object",
        "properties": {
          "questionId": {
            "type": "string"
          },
          "isCorrect": {
            "type": "boolean"
          },
          "correctIndex": {
            "type": "integer"
          },
          "selectedOption": {
            "type": "integer"
          },
          "explanation": {
            "type": "string"
          },
          "sourceCitation": {
            "type": "string"
          },
          "difficulty": {
            "type": "string"
          },
          "conceptIds": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "feedback": {
            "type": "string"
          },
          "evaluationMetadata": {
            "type": "object",
            "properties": {
              "reviewTier": {
                "type": "string"
              },
              "reviewedBy": {
                "type": "string"
              },
              "reviewedOn": {
                "type": "string"
              },
              "hasReasoningProvided": {
                "type": "boolean"
              },
              "timestamp": {
                "type": "string"
              }
            },
            "required": [
              "reviewTier",
              "hasReasoningProvided",
              "timestamp"
            ]
          }
        },
        "required": [
          "questionId",
          "isCorrect",
          "correctIndex",
          "selectedOption",
          "explanation",
          "sourceCitation",
          "difficulty",
          "conceptIds",
          "feedback",
          "evaluationMetadata"
        ]
      },
      "MockExamRequest": {
        "type": "object",
        "properties": {
          "certId": {
            "type": "string"
          },
          "questionCount": {
            "type": "integer",
            "enum": [
              15,
              25,
              50
            ],
            "default": 25
          },
          "maskAnswers": {
            "type": "boolean",
            "default": true
          }
        },
        "required": [
          "certId"
        ]
      },
      "MockExamResponse": {
        "type": "object",
        "properties": {
          "certId": {
            "type": "string"
          },
          "certName": {
            "type": "string"
          },
          "provider": {
            "type": "string"
          },
          "totalQuestions": {
            "type": "integer"
          },
          "blueprintWeighting": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "domainId": {
                  "type": "string"
                },
                "domainName": {
                  "type": "string"
                },
                "targetCount": {
                  "type": "integer"
                },
                "actualCount": {
                  "type": "integer"
                }
              },
              "required": [
                "domainId",
                "domainName",
                "targetCount",
                "actualCount"
              ]
            }
          },
          "difficultyBreakdown": {
            "type": "object",
            "properties": {
              "recall": {
                "type": "integer"
              },
              "discrimination": {
                "type": "integer"
              },
              "application": {
                "type": "integer"
              },
              "diagnosis": {
                "type": "integer"
              }
            },
            "required": [
              "recall",
              "discrimination",
              "application",
              "diagnosis"
            ]
          },
          "questions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PublicQuestionItem"
            }
          }
        },
        "required": [
          "certId",
          "certName",
          "provider",
          "totalQuestions",
          "blueprintWeighting",
          "difficultyBreakdown",
          "questions"
        ]
      },
      "Cert": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "provider": {
            "type": "string"
          },
          "cluster": {
            "type": "string",
            "enum": [
              "A",
              "B",
              "C"
            ]
          },
          "level": {
            "type": "string"
          },
          "domains": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "weight": {
                  "type": "integer"
                }
              },
              "required": [
                "id",
                "name"
              ]
            }
          },
          "url": {
            "type": "string"
          },
          "note": {
            "type": "string"
          },
          "access": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "name",
          "provider",
          "cluster",
          "level",
          "domains",
          "url",
          "note",
          "access"
        ]
      },
      "CertWithQuestions": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Cert"
          },
          {
            "type": "object",
            "properties": {
              "totalQuestions": {
                "type": "integer"
              }
            },
            "required": [
              "totalQuestions"
            ]
          }
        ]
      },
      "Concept": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "term": {
            "type": "string"
          },
          "aliases": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "definition": {
            "type": "string"
          },
          "examRelevance": {
            "type": "string"
          },
          "certs": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "related": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "id",
          "term",
          "aliases",
          "definition",
          "examRelevance",
          "certs",
          "related"
        ]
      },
      "ConceptBlueprintResponse": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "term": {
            "type": "string"
          },
          "aliases": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "definition": {
            "type": "string"
          },
          "examRelevance": {
            "type": "string"
          },
          "certs": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "relatedConcepts": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "term": {
                  "type": "string"
                }
              },
              "required": [
                "id",
                "term"
              ]
            }
          },
          "connectedQuestionsCount": {
            "type": "integer"
          },
          "difficultyCoverage": {
            "type": "object",
            "properties": {
              "recall": {
                "type": "integer"
              },
              "discrimination": {
                "type": "integer"
              },
              "application": {
                "type": "integer"
              },
              "diagnosis": {
                "type": "integer"
              }
            },
            "required": [
              "recall",
              "discrimination",
              "application",
              "diagnosis"
            ]
          }
        },
        "required": [
          "id",
          "term",
          "aliases",
          "definition",
          "examRelevance",
          "certs",
          "relatedConcepts",
          "connectedQuestionsCount",
          "difficultyCoverage"
        ]
      },
      "MatrixCoverageResponse": {
        "type": "object",
        "properties": {
          "totalQuestions": {
            "type": "integer"
          },
          "totalConcepts": {
            "type": "integer"
          },
          "totalCerts": {
            "type": "integer"
          },
          "reachableCells": {
            "type": "integer"
          },
          "filledCells": {
            "type": "integer"
          },
          "coveragePercentage": {
            "type": "number"
          },
          "byDifficulty": {
            "type": "object",
            "properties": {
              "recall": {
                "type": "integer"
              },
              "discrimination": {
                "type": "integer"
              },
              "application": {
                "type": "integer"
              },
              "diagnosis": {
                "type": "integer"
              }
            },
            "required": [
              "recall",
              "discrimination",
              "application",
              "diagnosis"
            ]
          },
          "byCert": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "certId": {
                  "type": "string"
                },
                "certName": {
                  "type": "string"
                },
                "totalQuestions": {
                  "type": "integer"
                },
                "domainCount": {
                  "type": "integer"
                }
              },
              "required": [
                "certId",
                "certName",
                "totalQuestions",
                "domainCount"
              ]
            }
          }
        },
        "required": [
          "totalQuestions",
          "totalConcepts",
          "totalCerts",
          "reachableCells",
          "filledCells",
          "coveragePercentage",
          "byDifficulty",
          "byCert"
        ]
      },
      "ApiErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              },
              "details": {}
            },
            "required": [
              "code",
              "message"
            ]
          }
        },
        "required": [
          "error"
        ]
      }
    }
  }
}