{
  "openapi": "3.1.0",
  "info": {
    "title": "AEO Scanner API",
    "version": "2.2.0",
    "description": "Scan any website for AI search engine visibility. Returns triple scores (AEO + GEO + Agent Readiness), AI Identity Card with Mention Readiness score, business profile detection, competitive gap analysis, and copy-paste fix code. 64+ checks across 12 categories. Quick scan is free (rate limited). Audit, compare, and fix endpoints are paid via x402 protocol (USDC on Base or Solana) — no API keys needed.",
    "contact": {
      "name": "Convrgent",
      "email": "support@convrgent.ai",
      "url": "https://convrgent.ai"
    },
    "x-guidance": "Start with scan_site (POST /api/aeo/scan) — it's free and returns triple scores (AEO + GEO + Agent Readiness), AI Identity Card, and business profile. Use the business profile to decide which scores matter most. For detailed breakdown, call audit (POST /api/aeo/audit, $1). For generated fix code with score projections, call fix (POST /api/aeo/fix, $5). After applying fixes, rescan to verify improvement."
  },
  "servers": [
    {
      "url": "https://scan.convrgent.ai",
      "description": "Production (free scan, x402 pay-per-call for audit/fix)"
    }
  ],
  "paths": {
    "/api/aeo/scan": {
      "post": {
        "summary": "Quick scan — triple score + AI Identity Card",
        "description": "Crawls up to 3 pages, runs 64+ checks across 12 categories, returns AEO + GEO + Agent scores, AI Identity Card, business profile detection, and top 5 issues. Free (rate limited: 20/hour per IP, 5 per URL per day).",
        "operationId": "scanSite",
        "security": [{ "siwx": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["url"],
                "properties": {
                  "url": {
                    "type": "string",
                    "description": "The website URL to scan",
                    "example": "https://example.com"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Scan completed successfully",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/QuickScanResult" }
              }
            }
          },
          "400": { "description": "Invalid URL or private/local address" },
          "429": { "description": "Rate limited" }
        }
      }
    },
    "/api/aeo/audit": {
      "post": {
        "summary": "Full audit — 64+ checks with per-page breakdown",
        "description": "Crawls up to 10 pages, full category breakdown for AEO + GEO + Agent, AI Identity Card, business profile, per-page scores. Cost: $1.00 via x402.",
        "operationId": "auditSite",
        "x-payment-info": {
          "price": { "mode": "fixed", "currency": "USD", "amount": "1.000000" },
          "protocols": [{ "x402": {} }]
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["url"],
                "properties": {
                  "url": {
                    "type": "string",
                    "example": "https://example.com"
                  },
                  "maxPages": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 10,
                    "default": 10,
                    "description": "Maximum pages to crawl"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Audit completed",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/FullScanResult" }
              }
            }
          },
          "400": { "description": "Invalid URL" },
          "402": { "description": "Payment required (x402 — USDC on Base or Solana)" }
        }
      }
    },
    "/api/aeo/fix": {
      "post": {
        "summary": "Full audit + generated fix code for every issue",
        "description": "Runs full audit and generates personalized fix code for every failing check. Includes score projections (quick wins vs full ceiling). Returns SKILL.md-compatible output that Claude Code can execute directly. Cost: $5.00 via x402.",
        "operationId": "fixSite",
        "x-payment-info": {
          "price": { "mode": "fixed", "currency": "USD", "amount": "5.000000" },
          "protocols": [{ "x402": {} }]
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["url"],
                "properties": {
                  "url": {
                    "type": "string",
                    "example": "https://example.com"
                  },
                  "maxPages": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 10,
                    "default": 10
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Fixes generated",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/FullScanResult" }
              }
            }
          },
          "402": { "description": "Payment required" }
        }
      }
    },
    "/api/aeo/compare": {
      "post": {
        "summary": "Competitive gap analysis — scan two sites, get overtake fix code",
        "description": "Scans your site and a competitor concurrently (5 pages each). Returns side-by-side scores, category-by-category winners, competitive gaps (what they have that you don't), and generated fix code to close the gaps. Cost: $3.00 via x402.",
        "operationId": "compareSites",
        "x-payment-info": {
          "price": { "mode": "fixed", "currency": "USD", "amount": "3.000000" },
          "protocols": [{ "x402": {} }]
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["url", "competitorUrl"],
                "properties": {
                  "url": { "type": "string", "description": "Your site URL" },
                  "competitorUrl": { "type": "string", "description": "Competitor site URL" },
                  "maxPages": { "type": "integer", "minimum": 1, "maximum": 5, "default": 5 }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Comparison completed",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ComparisonResult" }
              }
            }
          },
          "400": { "description": "Invalid URL, or url and competitorUrl are the same" },
          "402": { "description": "Payment required (x402 — USDC on Base or Solana)" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "siwx": {
        "type": "apiKey",
        "in": "header",
        "name": "SIGN-IN-WITH-X"
      }
    },
    "schemas": {
      "QuickScanResult": {
        "type": "object",
        "properties": {
          "product": { "type": "string", "example": "AEO" },
          "aeoScore": { "type": "integer", "minimum": 0, "maximum": 100, "description": "AI search visibility score" },
          "aeoGrade": { "type": "string", "enum": ["A", "B", "C", "D", "F"] },
          "geoScore": { "type": "integer", "minimum": 0, "maximum": 100, "description": "AI citation readiness score" },
          "geoGrade": { "type": "string", "enum": ["A", "B", "C", "D", "F"] },
          "agentScore": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Agent interaction readiness score" },
          "agentGrade": { "type": "string", "enum": ["A", "B", "C", "D", "F"] },
          "aiIdentityCard": { "$ref": "#/components/schemas/AiIdentityCard" },
          "businessProfile": { "$ref": "#/components/schemas/BusinessProfile" },
          "topIssues": { "type": "array", "items": { "$ref": "#/components/schemas/CheckResult" } },
          "pagesScanned": { "type": "integer" },
          "framework": { "type": "string", "description": "Detected framework (nextjs, wordpress, shopify, etc.)" },
          "scannedAt": { "type": "string", "format": "date-time" }
        }
      },
      "FullScanResult": {
        "type": "object",
        "properties": {
          "product": { "type": "string" },
          "id": { "type": "string", "example": "scan_1774989898848_a2ak98" },
          "url": { "type": "string", "format": "uri" },
          "scannedAt": { "type": "string", "format": "date-time" },
          "aeoScore": { "type": "integer" },
          "aeoGrade": { "type": "string" },
          "categories": { "type": "array", "description": "AEO category breakdown", "items": { "$ref": "#/components/schemas/CategoryScore" } },
          "geoReadiness": {
            "type": "object",
            "properties": {
              "score": { "type": "integer" },
              "grade": { "type": "string" },
              "categories": { "type": "array", "items": { "$ref": "#/components/schemas/CategoryScore" } }
            }
          },
          "agentReadiness": {
            "type": "object",
            "properties": {
              "score": { "type": "integer" },
              "grade": { "type": "string" },
              "categories": { "type": "array", "items": { "$ref": "#/components/schemas/CategoryScore" } }
            }
          },
          "aiIdentityCard": { "$ref": "#/components/schemas/AiIdentityCard" },
          "businessProfile": { "$ref": "#/components/schemas/BusinessProfile" },
          "pageResults": { "type": "array", "description": "Per-page score breakdown" },
          "topIssues": { "type": "array", "items": { "$ref": "#/components/schemas/CheckResult" } },
          "fixes": { "type": "array", "items": { "$ref": "#/components/schemas/GeneratedFix" }, "description": "Only in /fix response" },
          "scoreProjection": { "$ref": "#/components/schemas/ScoreProjection", "description": "Only in /fix response" },
          "pagesScanned": { "type": "integer" },
          "framework": { "type": "string" }
        }
      },
      "AiIdentityCard": {
        "type": "object",
        "description": "How AI currently perceives this brand — extracted from on-site signals",
        "properties": {
          "brandName": { "type": "string", "description": "Brand name as AI would reference it" },
          "summary": { "type": "string", "description": "One-line summary AI would use to describe the brand" },
          "category": { "type": "string", "description": "Category/industry AI would place this brand in" },
          "confidence": { "type": "string", "enum": ["high", "medium", "low", "unclear"] },
          "citableClaims": { "type": "array", "items": { "type": "string" }, "description": "Key claims AI could cite" },
          "verifiedPresence": { "type": "array", "items": { "type": "string" }, "description": "Platforms with verified presence" },
          "gaps": { "type": "array", "items": { "type": "string" }, "description": "What's missing to strengthen the identity" }
        }
      },
      "BusinessProfile": {
        "type": "object",
        "description": "Detected business type — determines which scores matter most",
        "properties": {
          "profile": { "type": "string", "enum": ["commerce", "saas", "media", "general"] },
          "label": { "type": "string", "example": "SaaS Product" },
          "confidence": { "type": "string", "enum": ["high", "medium", "low"] }
        }
      },
      "CategoryScore": {
        "type": "object",
        "properties": {
          "category": { "type": "string" },
          "label": { "type": "string" },
          "score": { "type": "integer" },
          "grade": { "type": "string" }
        }
      },
      "CheckResult": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "category": { "type": "string" },
          "passed": { "type": "boolean" },
          "severity": { "type": "string", "enum": ["critical", "warning", "info"] },
          "message": { "type": "string" },
          "score": { "type": "integer" }
        }
      },
      "GeneratedFix": {
        "type": "object",
        "properties": {
          "checkId": { "type": "string", "example": "org-schema" },
          "title": { "type": "string" },
          "description": { "type": "string" },
          "code": { "type": "string", "description": "Copy-paste fix code" },
          "language": { "type": "string", "enum": ["json", "html", "text", "xml", "markdown"] },
          "priority": { "type": "string", "enum": ["critical", "high", "medium", "low"] },
          "impactEstimate": { "type": "string", "example": "+5-10 pts (Structured Data)" },
          "scoreType": { "type": "string", "enum": ["aeo", "agent", "geo", "both", "all"] },
          "placement": { "type": "string" }
        }
      },
      "ScoreProjection": {
        "type": "object",
        "description": "Two-tier projection: quick wins (critical+high) vs full implementation ceiling",
        "properties": {
          "currentAeo": { "type": "integer" },
          "currentGeo": { "type": "integer" },
          "currentAgent": { "type": "integer" },
          "projectedAeoCriticalHigh": { "type": "integer", "description": "AEO after critical+high fixes" },
          "projectedGeoCriticalHigh": { "type": "integer", "description": "GEO after critical+high fixes" },
          "projectedAgentCriticalHigh": { "type": "integer", "description": "Agent after critical+high fixes" },
          "projectedAeo": { "type": "integer", "description": "AEO ceiling after all fixes" },
          "projectedGeo": { "type": "integer", "description": "GEO ceiling after all fixes" },
          "projectedAgent": { "type": "integer", "description": "Agent ceiling after all fixes" }
        }
      },
      "ComparisonResult": {
        "type": "object",
        "description": "Side-by-side AEO comparison with competitive gap analysis and overtake fix code",
        "properties": {
          "product": { "type": "string", "example": "AEO" },
          "type": { "type": "string", "example": "comparison" },
          "you": {
            "type": "object",
            "description": "Scores and identity for your site",
            "properties": {
              "url": { "type": "string", "format": "uri" },
              "aeoScore": { "type": "integer" },
              "aeoGrade": { "type": "string" },
              "geoScore": { "type": "integer" },
              "agentScore": { "type": "integer" }
            }
          },
          "competitor": {
            "type": "object",
            "description": "Scores and identity for the competitor site",
            "properties": {
              "url": { "type": "string", "format": "uri" },
              "aeoScore": { "type": "integer" },
              "aeoGrade": { "type": "string" },
              "geoScore": { "type": "integer" },
              "agentScore": { "type": "integer" }
            }
          },
          "categoryWinners": {
            "type": "array",
            "description": "Per-category winner breakdown",
            "items": { "type": "object" }
          },
          "gaps": {
            "type": "array",
            "description": "Checks the competitor passes that you fail",
            "items": { "type": "object" }
          },
          "overtakeFixes": {
            "type": "array",
            "description": "Generated fix code to close each gap",
            "items": { "$ref": "#/components/schemas/GeneratedFix" }
          },
          "projectedAfterFixes": {
            "type": "object",
            "description": "Your projected scores after applying all overtake fixes"
          }
        }
      }
    }
  }
}