{"openapi":"3.1.0","info":{"title":"SiteIntel API","version":"1.0.0","description":"SiteIntel is a continuous security and compliance posture intelligence platform for UK SMBs. This API surface lets AI agents query scans, retrieve findings, generate JSON-LD reports, and subscribe to webhooks.","contact":{"name":"SiteIntel","url":"https://siteintel.uk"},"license":{"name":"Proprietary","url":"https://siteintel.uk/legal"}},"servers":[{"url":"https://siteintel.uk","description":"production"},{"url":"http://localhost:3000","description":"local dev"}],"tags":[{"name":"Scans","description":"Trigger and read security scans"},{"name":"Reports","description":"Generate human-readable HTML/PDF and machine-readable JSON-LD reports"},{"name":"Compare","description":"Compare two scans of the same domain over time"},{"name":"Webhooks","description":"Subscribe to events on score / finding changes"},{"name":"Spec","description":"Self-describing endpoints (OpenAPI, JSON-LD context)"}],"paths":{"/api/scan":{"post":{"tags":["Scans"],"summary":"Trigger a new scan","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["domain"],"properties":{"domain":{"type":"string","description":"Domain to scan, e.g. example.com","example":"example.com"},"email":{"type":"string","format":"email","description":"Optional email for completion notification"}}}}}},"responses":{"200":{"description":"Scan queued","content":{"application/json":{"schema":{"type":"object","properties":{"scanId":{"type":"string"},"domain":{"type":"string"},"status":{"type":"string","enum":["QUEUED","RUNNING","COMPLETED"]}}}}}},"429":{"description":"Rate-limit exceeded"}}}},"/api/scan/{id}":{"get":{"tags":["Scans"],"summary":"Get scan status + full results","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Scan ID returned from POST /api/scan"}],"responses":{"200":{"description":"Scan record (status, scores, findings, intelligence)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Scan"}}}},"404":{"description":"Not found"}}}},"/api/scan/{id}/jsonld":{"get":{"tags":["Reports"],"summary":"JSON-LD twin of the scan (agent-readable)","description":"Returns the scan as Schema.org-compatible JSON-LD with SiteIntel extension namespace. Intended consumers: AI agents, MCP servers, security automation pipelines, procurement-review tooling.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"JSON-LD document","content":{"application/ld+json":{"schema":{"type":"object"}}}}}}},"/api/scan/{id}/report":{"get":{"tags":["Reports"],"summary":"HTML or PDF report","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"format","in":"query","required":false,"schema":{"type":"string","enum":["html","pdf"]}}],"responses":{"200":{"description":"HTML or PDF report body"}}}},"/api/scan/{id}/diff":{"get":{"tags":["Compare"],"summary":"Diff this scan against a previous scan of the same domain","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"against","in":"query","required":false,"schema":{"type":"string"},"description":"Optional previous scanId; defaults to most recent prior scan of same domain"}],"responses":{"200":{"description":"Scan diff document"}}}},"/api/openapi":{"get":{"tags":["Spec"],"summary":"This OpenAPI 3.1 spec","responses":{"200":{"description":"OpenAPI document","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/mcp":{"get":{"tags":["Spec"],"summary":"Model Context Protocol (MCP) server descriptor","description":"Returns the SiteIntel MCP server manifest so AI assistants can register SiteIntel as a tool. See Anthropic's MCP spec for details.","responses":{"200":{"description":"MCP descriptor"}}}}},"components":{"schemas":{"Scan":{"type":"object","properties":{"id":{"type":"string"},"domain":{"type":"string"},"status":{"type":"string","enum":["QUEUED","RUNNING","SYNTHESIZING","RENDERING","COMPLETED","FAILED","HALTED"]},"mode":{"type":"string","enum":["PUBLIC_PASSIVE","AUTHORISED_STANDARD","AUTHORISED_DEEP"]},"grade":{"type":"string"},"scoreOverall":{"type":"number","description":"Legacy 0-100 score"},"startedAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time"},"checks":{"type":"array","items":{"$ref":"#/components/schemas/CheckResult"}},"intelligence":{"$ref":"#/components/schemas/Intelligence"}}},"CheckResult":{"type":"object","properties":{"checkKey":{"type":"string"},"category":{"type":"string","enum":["security","performance","seo","accessibility","tech-debt","ux"]},"status":{"type":"string","enum":["ok","warn","fail","skipped","error"]},"points":{"type":"integer","minimum":0,"maximum":100},"findings":{"type":"array","items":{"$ref":"#/components/schemas/Finding"}}}},"Finding":{"type":"object","properties":{"severity":{"type":"string","enum":["critical","high","medium","low","info"]},"code":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"recommendation":{"type":"string"},"cveIds":{"type":"array","items":{"type":"string"}},"isKev":{"type":"boolean"},"businessImpact":{"type":"object","properties":{"whatThisMeans":{"type":"string"},"customerView":{"type":"string"},"ifExploited":{"type":"string"},"regulatorView":{"type":"string"}}}}},"Intelligence":{"type":"object","description":"Cross-check synthesised intelligence: hero score, budget memo, compliance posture, evidence cascades","properties":{"heroScore":{"type":"object","description":"Single-dominant-number 0-1000 score with grade band + sub-scores"},"budgetMemo":{"type":"object","description":"Per-cluster £-range remediation plan with methodology"},"compliancePosture":{"type":"object","description":"Per-regime compliance score + control gaps"},"evidenceCascades":{"type":"array","description":"Discovery chains showing how findings connect"}}}}}}