{"openapi":"3.1.0","info":{"title":"SAF-SiteScan-Agent API","version":"1.0.0","description":"Scan any website and get 12 marketing, SEO, and security reports with AI-generated insights and prioritized action items. Built to be called by AI agents. Get an API key at /account/keys."},"servers":[{"url":"https://sitescan.pedroganco.ai"}],"security":[{"bearerAuth":[]}],"paths":{"/api/v1/scans":{"get":{"operationId":"listScans","summary":"List the scans you've run","description":"Lists scans created with the calling API key, newest first (id, domain, status, date, average score). Organization tokens (account scope) list every scan in the account. Use for 'show me the scans I've done'.","parameters":[{"name":"domain","in":"query","required":false,"schema":{"type":"string"},"description":"Filter to scans whose domain contains this text."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"},"description":"Max scans to return (default 100, max 500)."}],"responses":{"200":{"description":"Scan list","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object"}}}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/api/v1/scan":{"post":{"operationId":"startScan","summary":"Start a website scan","description":"Starts an asynchronous scan of a URL. Returns a scan id immediately; the scan takes 30-90s. Poll getScan with the id until status is 'completed'.","x-openai-isConsequential":false,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","description":"Website URL or bare domain, e.g. 'example.com'."},"scanPath":{"type":"boolean","description":"Scan the exact page path, not just the domain root. Default false."}}}}}},"responses":{"202":{"description":"Scan started","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string"},"domain":{"type":"string"},"status":{"type":"string"}}}}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/api/v1/scan/sync":{"post":{"operationId":"scanAndWait","summary":"Scan and wait for results","description":"Starts a scan and waits up to `wait` seconds (default 20, max 55) for it to complete, then returns the full status. If still running, returns 202 with the current status and id so you can keep polling getScan.","x-openai-isConsequential":false,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","description":"Website URL or bare domain."},"scanPath":{"type":"boolean","description":"Scan the exact page path. Default false."},"wait":{"type":"integer","description":"Max seconds to wait (default 20, max 55)."}}}}}},"responses":{"200":{"description":"Scan completed","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string"},"domain":{"type":"string"},"status":{"type":"string","enum":["running","completed"]},"created_at":{"type":"string"},"completed_at":{"type":["string","null"]},"progress":{"type":"object","properties":{"completed":{"type":"integer"},"total":{"type":"integer"}}},"reports":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"status":{"type":"string","enum":["pending","running","completed","failed"]},"score":{"type":["integer","null"]},"grade":{"type":["string","null"]},"summary":{"type":["string","null"]}}}}}}}}}}},"202":{"description":"Still running","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string"},"domain":{"type":"string"},"status":{"type":"string","enum":["running","completed"]},"created_at":{"type":"string"},"completed_at":{"type":["string","null"]},"progress":{"type":"object","properties":{"completed":{"type":"integer"},"total":{"type":"integer"}}},"reports":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"status":{"type":"string","enum":["pending","running","completed","failed"]},"score":{"type":["integer","null"]},"grade":{"type":["string","null"]},"summary":{"type":["string","null"]}}}}}}}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/api/v1/scan/{id}":{"get":{"operationId":"getScan","summary":"Get scan status and report scores","description":"Returns the scan status plus each report's score, grade, and one-line summary. Use getReport for one report's full data.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The scan id."}],"responses":{"200":{"description":"Scan status","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string"},"domain":{"type":"string"},"status":{"type":"string","enum":["running","completed"]},"created_at":{"type":"string"},"completed_at":{"type":["string","null"]},"progress":{"type":"object","properties":{"completed":{"type":"integer"},"total":{"type":"integer"}}},"reports":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"status":{"type":"string","enum":["pending","running","completed","failed"]},"score":{"type":["integer","null"]},"grade":{"type":["string","null"]},"summary":{"type":["string","null"]}}}}}}}}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/api/v1/scan/{id}/report/{type}":{"get":{"operationId":"getReport","summary":"Get one report's full data","description":"Returns the complete structured data for a single report of a scan.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The scan id."},{"name":"type","in":"path","required":true,"description":"Report type.","schema":{"type":"string","enum":["geo","seo","brand","tag","wcag","keywords","cookies","business","lighthouse","tech","runtime","martech"]}}],"responses":{"200":{"description":"Report data","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object"}}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/api/v1/scan/{id}/summary":{"get":{"operationId":"getScanSummary","summary":"Get the AI executive summary and action report","description":"Returns the cached AI executive summary and prioritized action items. Returns 202 with generating:true until ready (shortly after the scan completes).","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The scan id."}],"responses":{"200":{"description":"Summary ready","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object"}}}}}},"202":{"description":"Still generating","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object"}}}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}},"/api/v1/reports":{"get":{"operationId":"listReportTypes","summary":"List the 12 report types","description":"Returns the report types a scan produces, each with a label and description.","responses":{"200":{"description":"Report catalog","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object"}}}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Your SAF-SiteScan API key (sk_live_...), created at /account/keys."}}}}