{"openapi":"3.1.0","info":{"title":"compuute-scan-api","description":"HTTP + MCP wrapper around compuute-scan, the MCP-specific static security scanner. Designed for agent-callable consumption: idempotent retries, cache headers, OpenAPI spec, MCP tool exposure.","contact":{"name":"Compuute AB","url":"https://compuute.se/","email":"daniel@compuute.se"},"license":{"name":"MIT","url":"https://github.com/Compuute/compuute-scan-api/blob/main/LICENSE"},"version":"0.3.0"},"paths":{"/v1/scan":{"post":{"tags":["scan"],"summary":"Scan a public GitHub MCP-server repo with compuute-scan","description":"Clones a public GitHub repository and runs compuute-scan's L0+L1 static analysis (37 MCP-specific rules across 8 languages: TS/JS, Python, Go, Rust, C#, Java, Kotlin). Returns a structured summary with severity counts, a coarse 0-100 score, recommendation, and the 10 most severe findings inline.\n\n**Idempotency:** supply `Idempotency-Key` header (UUIDv4 recommended). Identical key returns the cached scan for 24h with no re-execution.\n\n**Caching:** responses are `Cache-Control: public, max-age=1800` with an `ETag`. Send `If-None-Match` on revisit for a 304 Not Modified.\n\n**Limits:** repo must be public, <200 MB, clone <60s, scan <120s.\n\n**When NOT to use:** for exploitability assessment of a specific code path (this is pattern matching — book a manual audit at compuute.se/audit for that). For private repos, use the on-prem CLI: `npx compuute-scan ./repo`.","operationId":"scan_endpoint_v1_scan_post","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Idempotency-Key"}},{"name":"If-None-Match","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"If-None-Match"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScanRequest"}}}},"responses":{"200":{"description":"Scan completed successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScanResponse"}}}},"304":{"description":"Not Modified — caller's ETag is current."},"413":{"description":"Repo exceeds 200 MB size limit."},"422":{"description":"Invalid GitHub URL or repo not found."},"502":{"description":"Scanner failure (compuute-scan returned no/bad JSON)."},"504":{"description":"Clone or scan timeout."}}}},"/v1/scan/info":{"get":{"tags":["scan"],"summary":"Scanner version + capabilities (for agents deciding whether to call /v1/scan)","description":"Reports the bundled compuute-scan version, supported languages, layers covered, and rate limits. Use this to decide whether the scanner meets your freshness/coverage criteria before calling /v1/scan.","operationId":"scan_info_v1_scan_info_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/scan/pay":{"post":{"tags":["scan-x402"],"summary":"Pay-per-scan via x402 (no API key required)","description":"Agent-callable scan endpoint billed per-call via x402 micropayments on Base L2 USDC. Current price: $0.10 per scan.\n\n**Flow:**\n1. POST without `X-Payment` header → 402 with x402 payment requirements.\n2. Agent pays via x402 facilitator (Coinbase) and obtains a signed receipt.\n3. POST with `X-Payment: <receipt>` header → server verifies, runs the scan, returns result.\n\n**When NOT to use:** if you already have a free-tier API key, use `/v1/scan` instead. This endpoint is for agents without accounts.","operationId":"scan_with_x402_v1_scan_pay_post","parameters":[{"name":"X-Payment","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Payment"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScanRequest"}}}},"responses":{"200":{"description":"Scan completed successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScanResponse"}}}},"402":{"description":"Payment required. Body contains x402 requirements."},"413":{"description":"Repo exceeds size limit."},"422":{"description":"Invalid GitHub URL or repo not found."},"503":{"description":"x402 not configured on this server."}}}},"/v1/health":{"get":{"tags":["health"],"summary":"Health","description":"Liveness probe + scanner-binary check.","operationId":"health_v1_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}}},"components":{"schemas":{"FindingSummary":{"properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Id"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"severity":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Severity"},"file":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"File"},"line":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Line"},"owasp":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Owasp"},"cwe":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cwe"}},"type":"object","title":"FindingSummary"},"Performance":{"properties":{"clone_seconds":{"type":"number","title":"Clone Seconds"},"scan_seconds":{"type":"number","title":"Scan Seconds"},"repo_size_bytes":{"type":"integer","title":"Repo Size Bytes"}},"type":"object","required":["clone_seconds","scan_seconds","repo_size_bytes"],"title":"Performance"},"ScanRequest":{"properties":{"repo_url":{"type":"string","maxLength":256,"minLength":20,"title":"Repo Url","description":"Public GitHub HTTPS URL. Only github.com is accepted in this version. Repo must be public and < 200 MB. Example: https://github.com/org/repo"}},"additionalProperties":false,"type":"object","required":["repo_url"],"title":"ScanRequest","description":"POST /v1/scan input.","examples":[{"repo_url":"https://github.com/Compuute/compuute-scan"},{"repo_url":"https://github.com/modelcontextprotocol/servers"}]},"ScanResponse":{"properties":{"repo_url":{"type":"string","title":"Repo Url"},"scanned_at":{"type":"string","title":"Scanned At","description":"UTC timestamp when the scan started."},"scanner":{"$ref":"#/components/schemas/ScannerInfo"},"summary":{"$ref":"#/components/schemas/SeveritySummary"},"score":{"type":"integer","maximum":100.0,"minimum":0.0,"title":"Score","description":"0-100, higher safer."},"recommendation":{"type":"string","title":"Recommendation"},"findings_count":{"type":"integer","title":"Findings Count"},"top_findings":{"items":{"$ref":"#/components/schemas/FindingSummary"},"type":"array","title":"Top Findings"},"l0_discovery":{"additionalProperties":true,"type":"object","title":"L0 Discovery"},"performance":{"$ref":"#/components/schemas/Performance"},"_disclaimer":{"type":"string","title":"Disclaimer","description":"Mandatory disclaimer: compuute-scan is a static analyzer. Findings indicate vulnerable patterns are *present*; exploitability requires manual dataflow review."}},"type":"object","required":["repo_url","scanned_at","scanner","summary","score","recommendation","findings_count","performance","_disclaimer"],"title":"ScanResponse","description":"POST /v1/scan response.\n\nStable schema. Agents may rely on field names. Top-level fields cover\nsummary + score + recommendation; `top_findings` is bounded to 10 for\npayload size — full findings list is a v2 enhancement.","examples":[{"_disclaimer":"PATTERN MATCH — compuute-scan is a static analyzer...","findings_count":5,"l0_discovery":{},"performance":{"clone_seconds":1.2,"repo_size_bytes":41234,"scan_seconds":0.5},"recommendation":"REVIEW — 3 high finding(s). Triage individually.","repo_url":"https://github.com/org/example-mcp","scanned_at":"2026-05-23T08:00:00+00:00","scanner":{"layers_covered":["L0","L1"],"name":"compuute-scan","version":"0.6.2"},"score":82,"summary":{"critical":0,"files_scanned":44,"high":3,"info":0,"low":0,"medium":2},"top_findings":[]}]},"ScannerInfo":{"properties":{"name":{"type":"string","title":"Name"},"version":{"type":"string","title":"Version"},"layers_covered":{"items":{"type":"string"},"type":"array","title":"Layers Covered"}},"type":"object","required":["name","version"],"title":"ScannerInfo"},"SeveritySummary":{"properties":{"critical":{"type":"integer","title":"Critical","default":0},"high":{"type":"integer","title":"High","default":0},"medium":{"type":"integer","title":"Medium","default":0},"low":{"type":"integer","title":"Low","default":0},"info":{"type":"integer","title":"Info","default":0},"files_scanned":{"type":"integer","title":"Files Scanned","default":0}},"type":"object","title":"SeveritySummary"}}}}