{"openapi":"3.1.0","info":{"title":"AgentReserve API","version":"1.0.0","description":"Public, versioned API for AgentReserve — submit MCP server scans, fetch scored reports, list directory entries, export reports, and manage webhooks."},"servers":[{"url":"https://agentreserve.dev"}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","description":"AgentReserve API key, format `ar_live_<32 hex>`. Send it as `Authorization: Bearer <key>`."}},"schemas":{"Envelope":{"type":"object","required":["data","meta"],"properties":{"data":{},"meta":{"type":"object","required":["requestId","generatedAt"],"properties":{"requestId":{"type":"string","description":"Echoed from the X-AgentReserve-Request-Id header if present, otherwise generated server-side."},"generatedAt":{"type":"string","format":"date-time"}}}}},"Error":{"type":"object","required":["error","meta"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"meta":{"$ref":"#/components/schemas/Envelope/properties/meta"}}},"ScanSubmission":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","maxLength":2048},"force":{"type":"boolean","default":false,"description":"Bypass the cache window and run a fresh probe."},"scanSource":{"type":"string","enum":["web","api","cli","ci","github_action"]}}}}},"security":[{"ApiKeyAuth":[]}],"paths":{"/api/v1/scans":{"post":{"summary":"Submit a scan","description":"Probe an MCP server URL and return a scored report. Cached results may be returned within the reuse window.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScanSubmission"}}}},"responses":{"200":{"description":"Scan accepted (and possibly served from cache)."},"401":{"description":"Missing or invalid API key."},"429":{"description":"Hourly scan quota exceeded."}}}},"/api/v1/scans/{id}":{"get":{"summary":"Get a scan + report","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Scan + report (when finished)."},"404":{"description":"Scan not found."}}}},"/api/v1/scans/{id}/export":{"get":{"summary":"Export a scored report","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"format","in":"query","required":false,"schema":{"type":"string","enum":["json","csv","pdf"]}}],"responses":{"200":{"description":"Export bytes (or v1 envelope for JSON)."},"402":{"description":"Tier required (PDF on free tier)."}}}},"/api/v1/servers":{"get":{"summary":"List servers","parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":1}},{"name":"pageSize","in":"query","schema":{"type":"integer","minimum":1}},{"name":"verdict","in":"query","schema":{"type":"string","enum":["allow","review","block","unknown"]}},{"name":"risk","in":"query","schema":{"type":"string","enum":["low","medium","high","critical","unknown"]}},{"name":"grade","in":"query","schema":{"type":"string","pattern":"^[A-F][+-]?$"}},{"name":"dcr","in":"query","schema":{"type":"string","enum":["yes","no"]}},{"name":"recency","in":"query","schema":{"type":"integer","description":"Last N days"}},{"name":"sort","in":"query","schema":{"type":"string","enum":["score","recency","popularity"]}},{"name":"q","in":"query","schema":{"type":"string","description":"Hostname contains"}}],"responses":{"200":{"description":"Paginated server list."}}}},"/api/v1/servers/{hostname}":{"get":{"summary":"Get a server's latest report","parameters":[{"name":"hostname","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Server + latest scored report."},"404":{"description":"Server not found."}}}},"/api/v1/trust":{"get":{"summary":"D3.1 — free, public Trust API. Latest scan, tier, score, machine-readable rule failures, and a content-addressed (optionally HMAC-signed) attestation.","security":[],"parameters":[{"name":"server","in":"query","required":true,"schema":{"type":"string"},"description":"Hostname (`example.com`) or full URL (`https://example.com/mcp`). Lowercased."}],"responses":{"200":{"description":"Trust envelope with report + attestation."},"400":{"description":"Missing or unparseable `server`."},"404":{"description":"No scan recorded for this server."},"429":{"description":"Per-IP rate limit exceeded."}}}},"/api/v1/threat-feed.rss":{"get":{"summary":"D3.7 — free public RSS feed of newly-flagged-malicious or compromised MCP servers.","security":[],"responses":{"200":{"description":"RSS 2.0 XML.","content":{"application/rss+xml":{}}}}}},"/api/v1/threat-feed.stix":{"get":{"summary":"D3.7 — same threat feed as STIX 2.1 bundle for SIEM/TIP ingest.","security":[],"responses":{"200":{"description":"STIX 2.1 bundle JSON.","content":{"application/stix+json":{}}}}}}}}