{
  "openapi": "3.1.0",
  "info": {
    "title": "Answer Checkup API",
    "version": "0.1.0",
    "description": "AI visibility scan and reports. AI-generated answers, measured via each engine's API (default: OpenAI API with web search and Perplexity API; Gemini API without live search when enabled). Paid endpoints (coming soon) use x402 v2 (HTTP 402, PAYMENT-REQUIRED / PAYMENT-SIGNATURE headers).",
    "contact": {
      "name": "Answer Checkup",
      "email": "hello@answercheckup.com",
      "url": "https://answercheckup.com/"
    },
    "license": {
      "name": "Proprietary"
    }
  },
  "servers": [
    {
      "url": "https://answercheckup.com"
    }
  ],
  "security": [],
  "paths": {
    "/v1/scan": {
      "post": {
        "operationId": "scanSite",
        "summary": "Free AI readiness scan",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "url"
                ],
                "properties": {
                  "url": {
                    "type": "string",
                    "example": "https://example.com"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Scan result with score (0 to 100), checks and fixes",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ScanResult"
                }
              }
            }
          },
          "400": {
            "description": "Invalid URL"
          },
          "429": {
            "description": "Rate limit (free scan: per network and per scanned domain, per hour). See retry-after.",
            "headers": {
              "retry-after": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait"
              }
            }
          }
        }
      },
      "get": {
        "operationId": "scanSiteGet",
        "summary": "Free AI readiness scan (GET form)",
        "parameters": [
          {
            "name": "url",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "https://example.com"
          }
        ],
        "responses": {
          "200": {
            "description": "Scan result with score (0 to 100), checks and fixes",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ScanResult"
                }
              }
            }
          },
          "400": {
            "description": "Invalid URL"
          },
          "429": {
            "description": "Rate limit (free scan: per network and per scanned domain, per hour). See retry-after.",
            "headers": {
              "retry-after": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait"
              }
            }
          }
        }
      }
    },
    "/v1/report": {
      "post": {
        "operationId": "createReport",
        "summary": "Coming soon: paid AI visibility report (x402, USDC). $1 for size 5, $2 for size 10.",
        "description": "Coming soon: paid reports are not open yet. Call without payment to receive HTTP 402 with a base64 JSON PAYMENT-REQUIRED header (x402 v2, scheme exact). Retry with a PAYMENT-SIGNATURE header. Payment is settled only if the report generates successfully.",
        "x-payment-info": {
          "protocol": "x402",
          "scheme": "exact",
          "prices": {
            "5": "$1.00",
            "10": "$2.00"
          },
          "asset": "USDC",
          "status": "coming-soon"
        },
        "parameters": [
          {
            "name": "PAYMENT-SIGNATURE",
            "in": "header",
            "required": false,
            "description": "x402 v2 payment payload (base64 JSON). Omit on the first call to receive the 402 challenge.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "url",
                  "brand",
                  "size"
                ],
                "properties": {
                  "url": {
                    "type": "string",
                    "description": "Website URL of the business",
                    "example": "https://example.com"
                  },
                  "brand": {
                    "type": "string",
                    "description": "Brand or business name as buyers would say it",
                    "example": "Example Co"
                  },
                  "size": {
                    "type": "integer",
                    "enum": [
                      5,
                      10
                    ],
                    "description": "Number of prompts. 5 costs $1, 10 costs $2 (USDC via x402, coming soon)."
                  },
                  "prompts": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "maxLength": 300
                    },
                    "maxItems": 10,
                    "description": "Optional buyer questions. Missing ones are generated from brand and category."
                  },
                  "category": {
                    "type": "string",
                    "description": "Optional category, e.g. 'CRM for dentists'. Improves generated prompts."
                  },
                  "competitors": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "maxItems": 3,
                    "description": "Optional competitor names for share of mentions"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Report generated and payment settled",
            "headers": {
              "PAYMENT-RESPONSE": {
                "schema": {
                  "type": "string"
                },
                "description": "base64 JSON settlement receipt"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReportResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input (checked before any payment)"
          },
          "402": {
            "description": "Payment required. The PAYMENT-REQUIRED header holds the x402 v2 requirements (base64 JSON).",
            "headers": {
              "PAYMENT-REQUIRED": {
                "schema": {
                  "type": "string"
                },
                "description": "base64 JSON: x402Version 2, accepts[] with scheme exact, network, amount (USDC, 6 decimals), asset, payTo"
              }
            }
          },
          "409": {
            "description": "This payment has already been used"
          },
          "502": {
            "description": "Report generation failed. Payment was not settled."
          }
        }
      }
    },
    "/v1/reports/{id}": {
      "get": {
        "operationId": "getReport",
        "summary": "Fetch a stored report by its private id (expires after 30 days)",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Report JSON"
          },
          "404": {
            "description": "Not found or expired"
          }
        }
      }
    },
    "/v1/pricing": {
      "get": {
        "operationId": "getPricing",
        "summary": "Machine-readable pricing",
        "responses": {
          "200": {
            "description": "Pricing JSON"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ScanResult": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string"
          },
          "score": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          },
          "grade": {
            "type": "string"
          },
          "checks": {
            "type": "object"
          },
          "scoreBreakdown": {
            "type": "object"
          },
          "fixes": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "priority": {
                  "type": "string",
                  "enum": [
                    "high",
                    "medium",
                    "low"
                  ]
                },
                "area": {
                  "type": "string"
                },
                "fix": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "ReportResponse": {
        "type": "object",
        "properties": {
          "reportUrl": {
            "type": "string",
            "description": "Private link, valid 30 days"
          },
          "report": {
            "type": "object"
          }
        }
      }
    }
  }
}