{
  "openapi": "3.1.0",
  "info": {
    "title": "Curiquiz Machine API & AI Benchmark",
    "version": "1.0.0",
    "description": "Curiquiz provides programmatic access to 1352 human-curated multiple-choice trivia questions across 8 categories, and an automated Ground-Truth AI Model Benchmark. Monetized via HTTP 402 (x402 micropayments) on Base Mainnet.",
    "contact": {
      "name": "Curiquiz Support",
      "url": "https://curiquiz.com/contact"
    }
  },
  "servers": [
    {
      "url": "https://curiquiz.com",
      "description": "Production Server"
    }
  ],
  "paths": {
    "/api/quizzes": {
      "get": {
        "summary": "Full Quiz Bundle",
        "description": "Fetches all 1352 questions across 8 categories. Cost: $0.20 USDC on Base Mainnet. Add ?sample=true for a free 10-question sample.",
        "parameters": [
          {
            "name": "sample",
            "in": "query",
            "schema": {
              "type": "boolean"
            },
            "description": "Set to true to receive 10 random questions free of charge."
          }
        ],
        "responses": {
          "200": {
            "description": "Full structured quiz dataset"
          },
          "402": {
            "description": "Payment Required via x402 protocol"
          }
        }
      }
    },
    "/api/quizzes/{category}": {
      "get": {
        "summary": "Per-Category Quiz Bundle",
        "description": "Fetches questions for a single category (~150-302 questions). Cost: $0.05 USDC on Base Mainnet. Add ?sample=true for 5 free questions.",
        "parameters": [
          {
            "name": "category",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "art",
                "cinema",
                "common",
                "geography",
                "history",
                "music",
                "science",
                "sports"
              ]
            },
            "description": "Category slug"
          },
          {
            "name": "sample",
            "in": "query",
            "schema": {
              "type": "boolean"
            },
            "description": "Set to true for a free 5-question sample."
          }
        ],
        "responses": {
          "200": {
            "description": "Category questions payload"
          },
          "402": {
            "description": "Payment Required via x402 protocol"
          }
        }
      }
    },
    "/api/benchmark": {
      "post": {
        "summary": "Start AI Benchmark Session",
        "description": "Generates an evaluation set of questions (answers withheld) with an encrypted sessionToken. Gated by x402 on Base. Pass ?sample=true for a free 5-question test run.",
        "parameters": [
          {
            "name": "tier",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "quick",
                "standard",
                "hardcore"
              ],
              "default": "standard"
            },
            "description": "Benchmark tier: quick (20 Qs, 0.15 USDC), standard (50 Qs, 0.30 USDC), hardcore (50 Qs, 0.40 USDC)"
          },
          {
            "name": "sample",
            "in": "query",
            "schema": {
              "type": "boolean"
            },
            "description": "Set to true for a free 5-question trial session."
          }
        ],
        "responses": {
          "200": {
            "description": "Benchmark questions and encrypted sessionToken"
          },
          "402": {
            "description": "Payment Required via x402 protocol"
          }
        }
      }
    },
    "/api/benchmark/submit": {
      "post": {
        "summary": "Submit Benchmark Answers for Grading",
        "description": "Submits agent answers alongside the sessionToken. Returns accuracy %, category breakdown, calibration/hallucination risk, and cryptographic attestation.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "sessionToken",
                  "answers"
                ],
                "properties": {
                  "sessionToken": {
                    "type": "string"
                  },
                  "agentName": {
                    "type": "string"
                  },
                  "answers": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "required": [
                        "id",
                        "selectedIndex"
                      ],
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "selectedIndex": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Graded evaluation report with cryptographic proof"
          },
          "400": {
            "description": "Malformed submission request"
          },
          "403": {
            "description": "Invalid or expired sessionToken"
          }
        }
      }
    },
    "/api/benchmark/verify": {
      "post": {
        "summary": "Verify Benchmark Attestation",
        "description": "Verifies the cryptographic signature of an issued evaluation report.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "payload",
                  "signature"
                ],
                "properties": {
                  "payload": {
                    "type": "object"
                  },
                  "signature": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Verification status { valid: boolean }"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "x402Payment": {
        "type": "apiKey",
        "name": "X-Payment",
        "in": "header",
        "description": "x402 payment header with signed transaction payload for Base Mainnet. Recipient: 0x89C573537177A981f4BC9e27c5c17F44e93320C7, Asset: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913."
      }
    }
  }
}
