{
  "openapi": "3.1.0",
  "info": {
    "title": "GetMyCert Question API",
    "version": "1.0.0",
    "description": "Pay-per-use IT certification practice questions using the x402 payment protocol.\n\n## x402 Payment Flow\n\nThis API uses the [x402 protocol](https://x402.org) for autonomous agent payments over HTTP:\n\n1. Make a GET request to `/api/v1/x402` without any payment header.\n2. Receive a `402 Payment Required` response containing the payment specification (amount, network, recipient address).\n3. Construct a payment on Base mainnet using USDC.\n4. Retry the request with the `X-PAYMENT` header containing your payment proof.\n5. Receive questions in response.\n\nNo API key or account required. Agents pay autonomously per request.\n\n**Pricing:**\n- 10 questions: $0.01 USDC\n- 25 questions: $0.02 USDC\n- 50 questions: $0.04 USDC\n\n**Network:** Base Mainnet (chain ID 8453)\n\n**Contact:** api@getmycert.com",
    "contact": {
      "name": "GetMyCert API Support",
      "email": "api@getmycert.com",
      "url": "https://getmycert.com/developers"
    }
  },
  "servers": [
    {
      "url": "https://getmycert.com",
      "description": "Production server"
    }
  ],
  "paths": {
    "/api/v1/x402": {
      "get": {
        "operationId": "getX402Questions",
        "summary": "Get practice questions via x402 payment",
        "description": "Returns randomized IT certification practice questions. Requires x402 payment. On first call without payment, returns 402 with payment spec. Retry with X-PAYMENT header to receive questions.",
        "parameters": [
          {
            "name": "certification",
            "in": "query",
            "required": true,
            "description": "Certification slug identifier",
            "schema": {
              "type": "string",
              "enum": [
                "aws-ai-practitioner",
                "aws-cloud-practitioner",
                "aws-solutions-architect",
                "aws-solutions-architect-pro",
                "azure-administrator",
                "azure-ai-fundamentals",
                "azure-security-engineer",
                "azure-solutions-architect",
                "cisco-ccna",
                "cissp",
                "comptia-a-plus-core1",
                "comptia-a-plus-core2",
                "comptia-cysa-plus",
                "comptia-network-plus",
                "comptia-pentest-plus",
                "comptia-security-plus",
                "gcp-cloud-architect",
                "gcp-digital-leader",
                "gcp-ml-engineer",
                "kubernetes-cka",
                "kubernetes-ckad",
                "pmi-capm",
                "pmp",
                "salesforce-admin",
                "scrum-psm1",
                "terraform-associate"
              ],
              "example": "comptia-security-plus"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": true,
            "description": "Number of questions to return. Must match a supported pricing tier.",
            "schema": {
              "type": "integer",
              "enum": [10, 25, 50],
              "example": 10
            }
          },
          {
            "name": "difficulty",
            "in": "query",
            "required": false,
            "description": "Filter questions by difficulty level",
            "schema": {
              "type": "string",
              "enum": ["easy", "medium", "hard"],
              "example": "medium"
            }
          },
          {
            "name": "include_answer",
            "in": "query",
            "required": false,
            "description": "Include correct answer and explanation in response",
            "schema": {
              "type": "boolean",
              "default": false,
              "example": true
            }
          },
          {
            "name": "X-PAYMENT",
            "in": "header",
            "required": false,
            "description": "x402 payment proof header. Base64-encoded payment payload. Required on retry after receiving 402.",
            "schema": {
              "type": "string",
              "example": "eyJ0eXBlIjoiZXZtLTExNTUiLCAicGF5bG9hZCI6IHsiZnJvbSI6ICIweDEyM..."
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Questions returned successfully",
            "headers": {
              "X-Payment-Response": {
                "description": "Confirmation of payment receipt",
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QuestionsResponse"
                },
                "example": {
                  "meta": {
                    "certification": "comptia-security-plus",
                    "limit": 10,
                    "difficulty": "medium",
                    "include_answer": true,
                    "payment_verified": true,
                    "price_paid_usdc": "0.01"
                  },
                  "questions": [
                    {
                      "id": "q_7392",
                      "question": "Which type of attack involves an adversary intercepting and potentially altering communications between two parties?",
                      "options": {
                        "A": "Phishing",
                        "B": "Man-in-the-Middle (MitM)",
                        "C": "SQL Injection",
                        "D": "Denial of Service"
                      },
                      "difficulty": "medium",
                      "domain": "Threats, Attacks and Vulnerabilities",
                      "answer": "B",
                      "explanation": "A Man-in-the-Middle attack occurs when an attacker secretly intercepts and potentially alters the communication between two parties who believe they are communicating directly with each other."
                    }
                  ]
                }
              }
            }
          },
          "402": {
            "description": "Payment required. Response body contains x402 payment specification. Construct payment on Base mainnet and retry with X-PAYMENT header.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/X402PaymentRequired"
                },
                "example": {
                  "x402Version": 1,
                  "error": "Payment required",
                  "accepts": [
                    {
                      "scheme": "exact",
                      "network": "base-mainnet",
                      "maxAmountRequired": "10000",
                      "resource": "https://getmycert.com/api/v1/x402?certification=comptia-security-plus&limit=10",
                      "description": "10 practice questions for comptia-security-plus",
                      "mimeType": "application/json",
                      "payTo": "0xYourPaymentAddress",
                      "maxTimeoutSeconds": 300,
                      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
                      "extra": {
                        "name": "USDC",
                        "version": "2"
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Bad request — missing or invalid parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Invalid limit. Must be 10, 25, or 50.",
                  "code": "INVALID_PARAMS"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        },
        "security": [
          {
            "x402Payment": []
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "QuestionsResponse": {
        "type": "object",
        "required": ["meta", "questions"],
        "properties": {
          "meta": {
            "type": "object",
            "properties": {
              "certification": { "type": "string" },
              "limit": { "type": "integer" },
              "difficulty": { "type": "string", "nullable": true },
              "include_answer": { "type": "boolean" },
              "payment_verified": { "type": "boolean" },
              "price_paid_usdc": { "type": "string" }
            }
          },
          "questions": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Question"
            }
          }
        }
      },
      "Question": {
        "type": "object",
        "required": ["id", "question", "options", "difficulty", "domain"],
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique question identifier",
            "example": "q_7392"
          },
          "question": {
            "type": "string",
            "description": "The question text"
          },
          "options": {
            "type": "object",
            "description": "Answer options keyed by letter A-D",
            "additionalProperties": { "type": "string" },
            "example": {
              "A": "Phishing",
              "B": "Man-in-the-Middle (MitM)",
              "C": "SQL Injection",
              "D": "Denial of Service"
            }
          },
          "difficulty": {
            "type": "string",
            "enum": ["easy", "medium", "hard"]
          },
          "domain": {
            "type": "string",
            "description": "Exam domain or topic area"
          },
          "answer": {
            "type": "string",
            "description": "Correct answer letter. Only present when include_answer=true.",
            "nullable": true,
            "example": "B"
          },
          "explanation": {
            "type": "string",
            "description": "Explanation of the correct answer. Only present when include_answer=true.",
            "nullable": true
          }
        }
      },
      "X402PaymentRequired": {
        "type": "object",
        "description": "x402 payment specification returned with 402 status. Agent must construct and submit payment, then retry.",
        "required": ["x402Version", "error", "accepts"],
        "properties": {
          "x402Version": {
            "type": "integer",
            "example": 1
          },
          "error": {
            "type": "string",
            "example": "Payment required"
          },
          "accepts": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "scheme": { "type": "string", "example": "exact" },
                "network": { "type": "string", "example": "base-mainnet" },
                "maxAmountRequired": { "type": "string", "description": "Amount in USDC smallest unit (6 decimals). 10000 = $0.01 USDC", "example": "10000" },
                "resource": { "type": "string", "description": "The full URL being paid for" },
                "description": { "type": "string" },
                "mimeType": { "type": "string", "example": "application/json" },
                "payTo": { "type": "string", "description": "Payment recipient wallet address on Base mainnet" },
                "maxTimeoutSeconds": { "type": "integer", "example": 300 },
                "asset": { "type": "string", "description": "USDC contract address on Base mainnet", "example": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" },
                "extra": {
                  "type": "object",
                  "properties": {
                    "name": { "type": "string", "example": "USDC" },
                    "version": { "type": "string", "example": "2" }
                  }
                }
              }
            }
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": { "type": "string" },
          "code": { "type": "string" }
        }
      }
    },
    "securitySchemes": {
      "x402Payment": {
        "type": "http",
        "scheme": "x402",
        "description": "x402 micropayment protocol. No API key required. On first request, the server returns 402 with payment specification. Submit payment on Base mainnet (USDC), then retry with the X-PAYMENT header containing base64-encoded payment proof. See https://x402.org for protocol details and SDK support."
      }
    }
  }
}