{"openapi":"3.1.0","info":{"title":"SEOIQ API","version":"1.0.0","description":"Run SEO \/ AEO \/ GEO website audits and competitor analyses, and read full reports, findings and ready-made fixes. Access must be approved per account; create keys on the API page of your SEOIQ account. Scans and analyses spend credits and run in the background: start one, then poll until status is \"completed\". Docs: https:\/\/www.seoiq.co.uk\/docs\/api"},"servers":[{"url":"https:\/\/www.seoiq.co.uk\/api\/v1"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"API key: seoiq_\u2026"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"}}}}},"paths":{"\/me":{"get":{"operationId":"getAccount","summary":"Account, credit balance and pricing","responses":{"200":{"description":"Account","content":{"application\/json":{"schema":{"type":"object"}}}},"401":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"403":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"429":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}}}}},"\/sites":{"get":{"operationId":"listSites","summary":"Sites you have scanned, with the latest scan","parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"Paged sites","content":{"application\/json":{"schema":{"type":"object"}}}},"401":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"403":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"429":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}}}}},"\/scans":{"get":{"operationId":"listScans","summary":"Your scans, newest first","parameters":[{"name":"site","in":"query","schema":{"type":"string"},"description":"URL or name fragment"},{"name":"status","in":"query","schema":{"type":"string","enum":["pending","running","completed","failed"]}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"Paged scans","content":{"application\/json":{"schema":{"type":"object"}}}},"401":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"403":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"429":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}}}},"post":{"operationId":"startScan","summary":"Start a scan (spends credits)","requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","example":"https:\/\/example.co.uk"},"sections":{"type":"array","items":{"type":"string","enum":["technical","onpage","content_quality","aeo","geo","ai","performance","accessibility"]},"description":"Omit for a full scan"}}}}}},"responses":{"200":{"description":"Scan started (or the one already running)","content":{"application\/json":{"schema":{"type":"object"}}}},"402":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"409":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"422":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"401":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"403":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"429":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}}}}},"\/scans\/{id}":{"get":{"operationId":"getScan","summary":"Scan status, progress, scores and section summaries","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Scan","content":{"application\/json":{"schema":{"type":"object"}}}},"404":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"401":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"403":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"429":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}}}}},"\/scans\/{id}\/findings":{"get":{"operationId":"getFindings","summary":"Every finding with recommendation, evidence and fix content","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}},{"name":"severity","in":"query","schema":{"type":"string","enum":["critical","high","medium","low","info"]}},{"name":"section","in":"query","schema":{"type":"string","enum":["technical","onpage","content_quality","aeo","geo","ai","performance","accessibility"]}}],"responses":{"200":{"description":"Findings","content":{"application\/json":{"schema":{"type":"object"}}}},"404":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"409":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"401":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"403":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"429":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}}}}},"\/scans\/{id}\/report":{"get":{"operationId":"getScanReport","summary":"Full report as Markdown","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Markdown report","content":{"text\/markdown":{"schema":{"type":"string"}}}},"404":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"409":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"401":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"403":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"429":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}}}}},"\/competitors":{"get":{"operationId":"listCompetitorAnalyses","summary":"Your competitor analyses","parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"Paged analyses","content":{"application\/json":{"schema":{"type":"object"}}}},"401":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"403":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"429":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}}}},"post":{"operationId":"startCompetitorAnalysis","summary":"Start a competitor analysis (paid accounts, spends credits)","requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","example":"example.co.uk"},"keywords":{"type":"array","items":{"type":"string"},"maxItems":10},"location":{"type":"string","example":"Leeds, UK"},"competitors":{"type":"array","items":{"type":"string"},"maxItems":10},"client_type":{"type":"string","enum":["provider","platform"]},"auto_discover":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Analysis started","content":{"application\/json":{"schema":{"type":"object"}}}},"402":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"422":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"401":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"403":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"429":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}}}}},"\/competitors\/{id}":{"get":{"operationId":"getCompetitorAnalysis","summary":"Analysis status and results","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Analysis","content":{"application\/json":{"schema":{"type":"object"}}}},"404":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"401":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"403":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"429":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}}}}},"\/competitors\/{id}\/report":{"get":{"operationId":"getCompetitorReport","summary":"Full competitor report as Markdown","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Markdown report","content":{"text\/markdown":{"schema":{"type":"string"}}}},"404":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"409":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"401":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"403":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"429":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}}}}},"\/competitors\/suggest":{"post":{"operationId":"suggestCompetitors","summary":"Suggest keywords, location and competitors (paid accounts, spends credits)","requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","example":"example.co.uk"},"keywords":{"type":"array","items":{"type":"string"},"maxItems":10},"location":{"type":"string","example":"Leeds, UK"},"competitors":{"type":"array","items":{"type":"string"},"maxItems":10},"client_type":{"type":"string","enum":["provider","platform"]}}}}}},"responses":{"200":{"description":"Suggestion queued","content":{"application\/json":{"schema":{"type":"object"}}}},"402":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"401":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"403":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"429":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}}}}},"\/competitors\/suggest\/{id}":{"get":{"operationId":"getCompetitorSuggestion","summary":"Suggestion status and result","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Suggestion","content":{"application\/json":{"schema":{"type":"object"}}}},"404":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"401":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"403":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}},"429":{"description":"Error","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"}}}}}}}}}