{"openapi":"3.1.0","info":{"title":"LumeLogix SEO Scanner API","version":"1.1.0","description":"Free GET API for website SEO, local search, and AI readiness scores. Examples in this document are synthetic examples, not scan results. Always fetch a live score. No API key required.","contact":{"name":"LumeLogix","url":"https://lumelogix.com"}},"servers":[{"url":"https://lumelogix.com","description":"Production server"}],"paths":{"/ai-score/{domain}.txt":{"get":{"operationId":"getScoreText","summary":"Get a website AI readiness score as plain text","description":"Same scan, score and timestamp as /api/v1/public/score, rendered as text/plain for AI assistants. 202 with a retry line while a scan runs.","parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string","example":"example.com"}}],"responses":{"200":{"description":"Score (or a scan error) as plain text","content":{"text/plain":{"schema":{"type":"string"}}}},"202":{"description":"Scan in progress; retry after Retry-After seconds","content":{"text/plain":{"schema":{"type":"string"}}}},"400":{"description":"Invalid or non-public domain","content":{"text/plain":{"schema":{"type":"string"}}}},"429":{"description":"Rate limited","content":{"text/plain":{"schema":{"type":"string"}}}}}}},"/api/v1/public/score":{"get":{"operationId":"getScore","summary":"Get a website AI readiness score","description":"Preferred endpoint for AI agents. One GET, no API key, no POST. Returns a cached free result when one is less than 24 hours old (including partial scans). Otherwise starts a scan and returns 202 pending. Query format=json|html|text or Accept to choose JSON, server-rendered HTML or plain text of the same record. Examples are synthetic examples, not scan results.","parameters":[{"name":"url","in":"query","required":false,"description":"Domain or URL to score","schema":{"type":"string","example":"example.com"}},{"name":"domain","in":"query","required":false,"description":"Alias for url","schema":{"type":"string","example":"example.com"}},{"name":"format","in":"query","required":false,"description":"Force json or html","schema":{"type":"string","enum":["json","html"]}}],"responses":{"200":{"description":"Completed live result (synthetic example, not a scan result)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScoreSuccess"},"examples":{"synthetic":{"summary":"Synthetic example, not a scan result","value":{"status":"complete","domain":"example.com","score":12,"rating":"needs work","scanned_at":"2020-01-01T00:00:00.000Z","cached":true,"pillars":{"ai_readiness":10,"technical_seo":11,"local_seo":12},"top_fixes":[{"priority":1,"check_id":"EX-001","issue":"Synthetic example issue (not a scan result)","why":"Field shape only.","severity":"medium","scope":"page","page_url":"https://example.com/","affected_urls":["https://example.com/"],"evidence":["https://example.com/ (example)"],"recommendation":"Fetch a live score.","code":null,"source":null}],"locked_findings_count":3,"result_id":"aud_EXAMPLE","result_url":"https://lumelogix.com/score/example.com","report_url":"https://lumelogix.com/report/aud_EXAMPLE","source":"LumeLogix live scan"}}}},"text/html":{"schema":{"type":"string"}}}},"202":{"description":"Scan running (synthetic example, not a scan result)","headers":{"Retry-After":{"schema":{"type":"integer","example":8}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScorePending"},"examples":{"synthetic":{"summary":"Synthetic example, not a scan result","value":{"status":"pending","retry_after_seconds":8,"retry_url":"https://lumelogix.com/api/v1/public/score?url=example.com"}}}}}},"400":{"description":"Invalid domain (synthetic example, not a scan result)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScoreError"},"examples":{"synthetic":{"summary":"Synthetic example, not a scan result","value":{"status":"error","error":"Invalid domain. Provide a public website like example.com."}}}}}}}}},"/api/v1/public/scan":{"post":{"operationId":"startScan","summary":"Start a website scan (optional; prefer GET /score)","description":"Agents should use GET /api/v1/public/score instead. This POST remains for older clients. Examples are synthetic examples, not scan results.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","example":"https://example.com"},"apiKey":{"type":"string"}}}}}},"responses":{"202":{"description":"Scan started (synthetic example, not a scan result)","content":{"application/json":{"schema":{"type":"object","properties":{"jobId":{"type":"string","example":"aud_EXAMPLE","description":"Synthetic example, not a scan result"},"status":{"type":"string"},"pollUrl":{"type":"string","example":"https://lumelogix.com/api/v1/public/scan/aud_EXAMPLE"},"estimatedCompletionSeconds":{"type":"integer","example":30}}}}}},"400":{"description":"Invalid URL or request"},"429":{"description":"Rate limit exceeded"},"503":{"description":"Service temporarily unavailable"}}}},"/api/v1/public/scan/{jobId}":{"get":{"operationId":"getScanResult","summary":"Get scan result by job id","parameters":[{"name":"jobId","in":"path","required":true,"schema":{"type":"string","example":"aud_EXAMPLE","description":"Synthetic example, not a scan result"}}],"responses":{"200":{"description":"Scan result"},"404":{"description":"Job not found"}}}},"/api/v1/public/scan/cached":{"get":{"operationId":"getCachedScan","summary":"Get cached recent scan summary","parameters":[{"name":"url","in":"query","required":false,"schema":{"type":"string","example":"https://example.com"}},{"name":"domain","in":"query","required":false,"schema":{"type":"string","example":"example.com"}}],"responses":{"200":{"description":"Cache check result"},"400":{"description":"Invalid URL"}}}}},"components":{"schemas":{"ScoreSuccess":{"type":"object","description":"Synthetic example, not a scan result","properties":{"status":{"type":"string","enum":["complete"]},"domain":{"type":"string","example":"example.com","description":"Synthetic example, not a scan result"},"score":{"type":"number","nullable":true,"example":12,"description":"EXAMPLE score — synthetic example, not a scan result"},"rating":{"type":"string","example":"needs work","description":"Lowercase band: strong, good, needs work, blocked"},"scanned_at":{"type":"string","format":"date-time","example":"2020-01-01T00:00:00.000Z"},"cached":{"type":"boolean"},"pillars":{"type":"object","properties":{"ai_readiness":{"type":"number","nullable":true,"example":10},"technical_seo":{"type":"number","nullable":true,"example":11},"local_seo":{"type":"number","nullable":true,"example":12}}},"top_fixes":{"type":"array","maxItems":5,"items":{"type":"object","properties":{"priority":{"type":"integer","example":1},"check_id":{"type":"string","example":"EX-001"},"issue":{"type":"string","example":"Synthetic example issue (not a scan result)"},"why":{"type":"string"},"severity":{"type":"string","nullable":true,"enum":["critical","high","medium","low","info"]},"scope":{"type":"string","enum":["site","page"],"description":"'page' when specific pages are affected; 'site' for site-wide settings (page_url is then null)"},"page_url":{"type":"string","format":"uri","nullable":true,"example":"https://example.com/","description":"First affected page as an absolute URL, or null for site-wide issues"},"affected_urls":{"type":"array","items":{"type":"string","format":"uri"},"maxItems":5},"evidence":{"type":"array","items":{"type":"string"},"maxItems":3,"description":"What the scanner observed, verbatim"},"recommendation":{"type":"string","description":"The specific change to make"},"code":{"type":"string","nullable":true,"description":"Ready-to-use code or configuration, when one helps"},"source":{"type":"string","format":"uri","nullable":true,"description":"Published guidance the check is based on"}}}},"locked_findings_count":{"type":"integer","example":3},"result_id":{"type":"string","example":"aud_EXAMPLE","description":"Synthetic example, not a scan result"},"result_url":{"type":"string","example":"https://lumelogix.com/score/example.com"},"report_url":{"type":"string","example":"https://lumelogix.com/report/aud_EXAMPLE"},"source":{"type":"string","enum":["LumeLogix live scan"]}}},"ScorePending":{"type":"object","description":"Synthetic example, not a scan result","properties":{"status":{"type":"string","enum":["pending"]},"retry_after_seconds":{"type":"integer","example":8},"retry_url":{"type":"string","example":"https://lumelogix.com/api/v1/public/score?url=example.com"}}},"ScoreError":{"type":"object","description":"Synthetic example, not a scan result. Never includes a score.","properties":{"status":{"type":"string","enum":["error"]},"error":{"type":"string","example":"Invalid domain. Provide a public website like example.com."},"domain":{"type":"string"},"result_id":{"type":"string"},"source":{"type":"string"}}}}}}