{"openapi":"3.1.0","info":{"title":"AgentLens API","version":"0.1.0","description":"Agent-readiness scanning. Scores come from a static pre-check — evidence about a site's agent-facing surface. Behavioural measurement is the audit (real agent runs), at /audit."},"servers":[{"url":"https://agent-chi-lime.vercel.app"}],"components":{"securitySchemes":{"none":{"type":"http","scheme":"bearer","description":"No authentication is required for any endpoint in v1. This scheme is declared so clients know auth is genuinely absent rather than undocumented."}},"schemas":{"Error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Stable machine-readable error code. Branch on this, not on message."},"message":{"type":"string"},"next_action":{"type":"object","description":"A request that recovers from this error, usable verbatim.","properties":{"method":{"type":"string","enum":["GET","POST"]},"endpoint":{"type":"string"},"body":{"type":"object"},"retry_after_s":{"type":"number"}}}}}}},"paths":{"/api/scan":{"post":{"summary":"Run an agent-readiness pre-check for a URL or domain","description":"Scans the target (~10s) and stores the result. Returns the full ScanResult. Rate limited to 10/min/IP. Results fresher than 5 minutes are served from cache unless ?force=1.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","description":"Domain, URL, or MCP endpoint URL."}}}}}},"responses":{"200":{"description":"The scan result (schema agentlens.scan/1).","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"MISSING_URL, INVALID_JSON or INVALID_TARGET.","content":{"application/json":{"schema":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Stable machine-readable error code. Branch on this, not on message."},"message":{"type":"string"},"next_action":{"type":"object","description":"A request that recovers from this error, usable verbatim.","properties":{"method":{"type":"string","enum":["GET","POST"]},"endpoint":{"type":"string"},"body":{"type":"object"},"retry_after_s":{"type":"number"}}}}}}}},"429":{"description":"RATE_LIMITED — retry_after_s says when.","content":{"application/json":{"schema":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Stable machine-readable error code. Branch on this, not on message."},"message":{"type":"string"},"next_action":{"type":"object","description":"A request that recovers from this error, usable verbatim.","properties":{"method":{"type":"string","enum":["GET","POST"]},"endpoint":{"type":"string"},"body":{"type":"object"},"retry_after_s":{"type":"number"}}}}}}}},"502":{"description":"SCAN_FAILED or SCAN_SERVICE_UNREACHABLE.","content":{"application/json":{"schema":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Stable machine-readable error code. Branch on this, not on message."},"message":{"type":"string"},"next_action":{"type":"object","description":"A request that recovers from this error, usable verbatim.","properties":{"method":{"type":"string","enum":["GET","POST"]},"endpoint":{"type":"string"},"body":{"type":"object"},"retry_after_s":{"type":"number"}}}}}}}}}}},"/api/score/{domain}":{"get":{"summary":"Fetch the stored scan result for a domain","parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Stored result plus scan history.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"INVALID_DOMAIN.","content":{"application/json":{"schema":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Stable machine-readable error code. Branch on this, not on message."},"message":{"type":"string"},"next_action":{"type":"object","description":"A request that recovers from this error, usable verbatim.","properties":{"method":{"type":"string","enum":["GET","POST"]},"endpoint":{"type":"string"},"body":{"type":"object"},"retry_after_s":{"type":"number"}}}}}}}},"404":{"description":"DOMAIN_NOT_SCANNED — next_action contains the POST that triggers the scan.","content":{"application/json":{"schema":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Stable machine-readable error code. Branch on this, not on message."},"message":{"type":"string"},"next_action":{"type":"object","description":"A request that recovers from this error, usable verbatim.","properties":{"method":{"type":"string","enum":["GET","POST"]},"endpoint":{"type":"string"},"body":{"type":"object"},"retry_after_s":{"type":"number"}}}}}}}}}}},"/api/badge/{domain}":{"get":{"summary":"SVG badge for a domain's score","parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"image/svg+xml badge.","content":{"image/svg+xml":{}}},"400":{"description":"INVALID_DOMAIN.","content":{"application/json":{"schema":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Stable machine-readable error code. Branch on this, not on message."},"message":{"type":"string"},"next_action":{"type":"object","description":"A request that recovers from this error, usable verbatim.","properties":{"method":{"type":"string","enum":["GET","POST"]},"endpoint":{"type":"string"},"body":{"type":"object"},"retry_after_s":{"type":"number"}}}}}}}},"404":{"description":"Not-scanned badge (also SVG).","content":{"image/svg+xml":{}}}}}},"/api/leaderboard":{"get":{"summary":"Domains ranked by agent-readiness scan score","parameters":[{"name":"category","in":"query","required":false,"schema":{"type":"string"},"description":"One of the closed category list; omit for the global board."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"default":200}}],"responses":{"200":{"description":"Ranked entries with scan score, grade and category, from the static pre-check.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"UNKNOWN_CATEGORY — next_action shows a valid call.","content":{"application/json":{"schema":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Stable machine-readable error code. Branch on this, not on message."},"message":{"type":"string"},"next_action":{"type":"object","description":"A request that recovers from this error, usable verbatim.","properties":{"method":{"type":"string","enum":["GET","POST"]},"endpoint":{"type":"string"},"body":{"type":"object"},"retry_after_s":{"type":"number"}}}}}}}}}}},"/api/waitlist":{"post":{"summary":"Join the journey / monitor waitlist","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email"},"domain":{"type":"string"},"source":{"type":"string","enum":["journey","monitor"]}}}}}},"responses":{"200":{"description":"Joined.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}}}}}},"400":{"description":"INVALID_EMAIL or INVALID_JSON.","content":{"application/json":{"schema":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Stable machine-readable error code. Branch on this, not on message."},"message":{"type":"string"},"next_action":{"type":"object","description":"A request that recovers from this error, usable verbatim.","properties":{"method":{"type":"string","enum":["GET","POST"]},"endpoint":{"type":"string"},"body":{"type":"object"},"retry_after_s":{"type":"number"}}}}}}}},"429":{"description":"RATE_LIMITED.","content":{"application/json":{"schema":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Stable machine-readable error code. Branch on this, not on message."},"message":{"type":"string"},"next_action":{"type":"object","description":"A request that recovers from this error, usable verbatim.","properties":{"method":{"type":"string","enum":["GET","POST"]},"endpoint":{"type":"string"},"body":{"type":"object"},"retry_after_s":{"type":"number"}}}}}}}}}}},"/api/audit/plan":{"post":{"summary":"Generate an audit test plan (free preview; pay to run it)","description":"Generates a scenario plan for an MCP server, SDK, or CLI: a standard pack for the target type plus scenarios derived from docs_url, validated against the real harness. Returns the plan preview, price, and the checkout next_action. Can take minutes for MCP targets (a live tool-discovery handshake runs).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["target"],"properties":{"target":{"type":"object","required":["type","source"],"properties":{"type":{"type":"string","enum":["mcp","sdk","cli"]},"source":{"type":"object","required":["value"],"properties":{"value":{"type":"string","description":"npm/PyPI package or streamable-HTTP MCP URL"},"kind":{"type":"string","enum":["url","npm","pypi","binary"]},"install_cmd":{"type":"string"}}},"docs_url":{"type":"string","format":"uri"},"binary":{"type":"string"},"env":{"type":"array","description":"Credential env var NAMES the target needs (never values)","items":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"description":{"type":"string"}}}}}}}}}}},"responses":{"200":{"description":"Plan preview with audit_id, price_usd, and checkout next_action.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"INVALID_TARGET or INVALID_JSON.","content":{"application/json":{"schema":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Stable machine-readable error code. Branch on this, not on message."},"message":{"type":"string"},"next_action":{"type":"object","description":"A request that recovers from this error, usable verbatim.","properties":{"method":{"type":"string","enum":["GET","POST"]},"endpoint":{"type":"string"},"body":{"type":"object"},"retry_after_s":{"type":"number"}}}}}}}},"422":{"description":"PLAN_GENERATION_FAILED.","content":{"application/json":{"schema":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Stable machine-readable error code. Branch on this, not on message."},"message":{"type":"string"},"next_action":{"type":"object","description":"A request that recovers from this error, usable verbatim.","properties":{"method":{"type":"string","enum":["GET","POST"]},"endpoint":{"type":"string"},"body":{"type":"object"},"retry_after_s":{"type":"number"}}}}}}}},"429":{"description":"RATE_LIMITED.","content":{"application/json":{"schema":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Stable machine-readable error code. Branch on this, not on message."},"message":{"type":"string"},"next_action":{"type":"object","description":"A request that recovers from this error, usable verbatim.","properties":{"method":{"type":"string","enum":["GET","POST"]},"endpoint":{"type":"string"},"body":{"type":"object"},"retry_after_s":{"type":"number"}}}}}}}}}}},"/api/audit/checkout":{"post":{"summary":"Create the Stripe Checkout session for a drafted audit","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["audit_id","email"],"properties":{"audit_id":{"type":"string"},"email":{"type":"string","format":"email"}}}}}},"responses":{"200":{"description":"checkout_url to open; the audit status link arrives by email after payment.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"INVALID_AUDIT_ID or INVALID_EMAIL.","content":{"application/json":{"schema":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Stable machine-readable error code. Branch on this, not on message."},"message":{"type":"string"},"next_action":{"type":"object","description":"A request that recovers from this error, usable verbatim.","properties":{"method":{"type":"string","enum":["GET","POST"]},"endpoint":{"type":"string"},"body":{"type":"object"},"retry_after_s":{"type":"number"}}}}}}}},"404":{"description":"AUDIT_NOT_FOUND.","content":{"application/json":{"schema":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Stable machine-readable error code. Branch on this, not on message."},"message":{"type":"string"},"next_action":{"type":"object","description":"A request that recovers from this error, usable verbatim.","properties":{"method":{"type":"string","enum":["GET","POST"]},"endpoint":{"type":"string"},"body":{"type":"object"},"retry_after_s":{"type":"number"}}}}}}}},"409":{"description":"ALREADY_PURCHASED.","content":{"application/json":{"schema":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Stable machine-readable error code. Branch on this, not on message."},"message":{"type":"string"},"next_action":{"type":"object","description":"A request that recovers from this error, usable verbatim.","properties":{"method":{"type":"string","enum":["GET","POST"]},"endpoint":{"type":"string"},"body":{"type":"object"},"retry_after_s":{"type":"number"}}}}}}}}}}}}}