{"openapi":"3.0.3","info":{"title":"AEO Scanner API","description":"Free website AEO (Answer Engine Optimization) scoring API. Scan any URL and get a detailed report with fix code snippets.","version":"1.0.0","contact":{"name":"CodeCity","url":"https://aeo.codecity.com.tw"}},"servers":[{"url":"https://aeo.codecity.com.tw","description":"Production server"}],"paths":{"/api/scan":{"post":{"summary":"Scan a website for AEO score","description":"Scans the given URL, computes a weighted score across 9 AEO metrics, and returns ready-to-use fix code snippets.","operationId":"scanWebsite","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","description":"The URL to scan","example":"https://example.com"}}}}}},"responses":{"200":{"description":"Scan successful. Returns the full AEO score report.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","description":"Scan record ID"},"url":{"type":"string","description":"The scanned URL"},"score":{"type":"number","description":"Overall AEO score (0–100)"},"scores":{"type":"object","description":"Per-metric scores","properties":{"jsonLd":{"type":"number","description":"JSON-LD score (weight 30%)"},"llmsTxt":{"type":"number","description":"llms.txt score (weight 20%)"},"og":{"type":"number","description":"Open Graph score (weight 15%)"},"meta":{"type":"number","description":"Meta tags score (weight 10%)"},"faq":{"type":"number","description":"FAQ Schema score (weight 10%)"},"social":{"type":"number","description":"Social cards score (weight 5%)"},"contact":{"type":"number","description":"Contact info score (weight 5%)"},"image":{"type":"number","description":"Image alt text score (weight 5%)"},"content":{"type":"number","description":"Content structure score (weight 0%, informational)"}}},"snippets":{"type":"object","description":"Auto-generated fix code snippets","properties":{"jsonLd":{"type":"string","description":"JSON-LD structured data snippet"},"og":{"type":"string","description":"Open Graph meta tags snippet"},"faq":{"type":"string","description":"FAQ Schema snippet"},"llmsTxt":{"type":"string","description":"Suggested llms.txt content"}}},"scannedAt":{"type":"string","format":"date-time","description":"Timestamp of the scan"}}},"example":{"id":42,"url":"https://example.com","score":73.5,"scores":{"meta":90,"og":80,"content":70,"jsonLd":60,"image":75,"faq":50,"contact":80,"llmsTxt":0,"social":85},"scannedAt":"2026-03-13T10:00:00Z"}}}},"400":{"description":"Bad request — missing or invalid url field.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Invalid URL"}}}}}}}}},"/api/sites":{"get":{"summary":"List scanned sites","description":"Returns the leaderboard of scanned sites sorted by score. Supports pagination and search.","operationId":"listSites","parameters":[{"name":"page","in":"query","schema":{"type":"integer","default":1},"description":"Page number (1-based)"},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100},"description":"Results per page"},{"name":"q","in":"query","schema":{"type":"string"},"description":"Search keyword (filters by URL)"},{"name":"sort","in":"query","schema":{"type":"string","enum":["score","scanned_at"],"default":"score"},"description":"Sort field"}],"responses":{"200":{"description":"Successful response with site list","content":{"application/json":{"schema":{"type":"object","properties":{"sites":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"url":{"type":"string"},"score":{"type":"number"},"scannedAt":{"type":"string","format":"date-time"}}}},"total":{"type":"integer","description":"Total number of results"},"page":{"type":"integer"},"limit":{"type":"integer"}}}}}}}}},"/api/sites/{id}":{"get":{"summary":"Get a single site's detailed AEO scores","description":"Returns the full AEO score report for a specific site by ID.","operationId":"getSite","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"},"description":"Site ID"}],"responses":{"200":{"description":"Successful response with site detail","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"url":{"type":"string"},"score":{"type":"number"},"scores":{"type":"object"},"scannedAt":{"type":"string","format":"date-time"}}}}}},"404":{"description":"Site not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Site not found"}}}}}}}}},"/api/stats":{"get":{"summary":"Get global statistics","description":"Returns overall AEO Scanner statistics: total scans, average score, active AI crawlers, etc.","operationId":"getStats","responses":{"200":{"description":"Successful response with statistics","content":{"application/json":{"schema":{"type":"object","properties":{"totalScans":{"type":"integer","description":"Total number of scans performed"},"totalSites":{"type":"integer","description":"Total number of unique sites scanned"},"avgScore":{"type":"number","description":"Average AEO score across all sites"},"activeCrawlers":{"type":"integer","description":"Number of distinct AI crawlers active in the past 24 hours"}}},"example":{"totalScans":1250,"totalSites":843,"avgScore":61.3,"activeCrawlers":5}}}}}}}}}