{"openapi":"3.1.0","info":{"title":"PlatPhorm AgentReady API","version":"2026.3","description":"Independent, bounded, evidence-backed agent-readiness scanner. Public scans are read-only and bounded; throttled responses expose Retry-After and RateLimit-* guidance. The AnswerReady full-report route is protected with PLATPHORM_API_KEY."},"servers":[{"url":"https://agentready.platphormnews.com"}],"tags":[{"name":"scans","description":"Create and retrieve complete scan reports."}],"paths":{"/api/health":{"get":{"operationId":"getHealth","summary":"Get service health","responses":{"200":{"description":"Healthy service envelope"},"503":{"description":"Degraded service envelope"}}}},"/api/v1/health":{"get":{"operationId":"getVersionedHealth","summary":"Get versioned service health","responses":{"200":{"description":"Healthy service envelope"},"503":{"description":"Degraded service envelope"}}}},"/api/mcp":{"get":{"operationId":"getMcpMetadata","summary":"Get AgentReady MCP metadata","responses":{"200":{"description":"MCP capability metadata"}}},"post":{"operationId":"handleMcpJsonRpc","summary":"Handle MCP JSON-RPC 2.0 requests","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["jsonrpc","method"],"properties":{"jsonrpc":{"type":"string","const":"2.0"},"id":{"oneOf":[{"type":"string"},{"type":"number"},{"type":"null"}]},"method":{"type":"string"},"params":{"type":"object","additionalProperties":true}}}}}},"responses":{"200":{"description":"JSON-RPC result or error"},"400":{"description":"JSON-RPC parse error"}}}},"/api/v1/scans":{"post":{"tags":["scans"],"operationId":"createPublicScan","summary":"Run a bounded public-safe scan","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TestRequest"}}}},"responses":{"201":{"description":"Scan locator","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScanLocatorResponse"}}}},"400":{"description":"Invalid URL or scan failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Protected attestation requires PLATPHORM_API_KEY","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Public scan rate limit exceeded; retry after the documented delay.","headers":{"Retry-After":{"schema":{"type":"integer"}},"RateLimit-Limit":{"schema":{"type":"integer"}},"RateLimit-Remaining":{"schema":{"type":"integer"}},"RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/answerready/test":{"post":{"tags":["scans"],"operationId":"runAnswerReadyFullReport","summary":"Run the complete AgentReady report for AnswerReady","description":"Returns findings, bounded evidence, applicability, coverage, remediation prompt, and trace metadata.","security":[{"bearerAuth":[]},{"platphormApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TestRequest"}}}},"responses":{"201":{"description":"Complete report","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FullReportResponse"}}}},"401":{"description":"Missing or invalid shared platform key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/scans/{id}":{"get":{"tags":["scans"],"operationId":"getScanReport","summary":"Retrieve a persisted public-safe report","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Persisted report envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersistedReportResponse"}}}},"404":{"description":"Report not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"PLATPHORM_API_KEY","description":"Shared platform key; never expose it in browser code or reports."},"platphormApiKey":{"type":"apiKey","in":"header","name":"X-PlatPhorm-API-Key","description":"Shared platform key accepted for protected cross-site calls."}},"schemas":{"TestRequest":{"type":"object","required":["url"],"additionalProperties":false,"properties":{"url":{"type":"string","format":"uri","description":"Public HTTP(S) URL. Credentials, custom ports, private hosts, and unsafe redirects are rejected."},"clientMetrics":{"type":"object","additionalProperties":true,"description":"Optional bounded BrowserOps caller-path measurements supplied only after explicit consent; excluded from the primary target score."},"sharedResources":{"type":"array","maxItems":32,"description":"Protected AnswerReady-to-AgentReady evidence reuse. Bounded same-target public resource artifacts; never include credentials or secrets.","items":{"type":"object","required":["path","status","text"],"properties":{"path":{"type":"string"},"status":{"type":"integer","minimum":0,"maximum":599},"contentType":{"type":"string"},"text":{"type":"string","maxLength":250000}}}},"sharedScanContext":{"type":"object","description":"Protected provenance for reused AnswerReady artifacts. The report preserves scan identity, normalized target, W3C traceparent, and SHA-256 references without duplicating artifact bodies.","required":["scanId","normalizedUrl","artifactRefs"],"properties":{"scanId":{"type":"string"},"normalizedUrl":{"type":"string","format":"uri"},"traceparent":{"type":"string"},"artifactRefs":{"type":"array","maxItems":32,"items":{"type":"object","required":["path","status","sha256","source"],"properties":{"path":{"type":"string"},"status":{"type":"integer"},"contentType":{"type":"string"},"sha256":{"type":"string"},"source":{"type":"string","enum":["answerready"]}}}}}},"authorization":{"type":"object","additionalProperties":false,"properties":{"attested":{"type":"boolean"},"verificationToken":{"type":"string","maxLength":256,"writeOnly":true}}}}},"RequestEvidence":{"type":"object","required":["url","method"],"properties":{"url":{"type":"string","format":"uri"},"method":{"type":"string"},"responseStatus":{"type":"integer","nullable":true},"contentType":{"type":"string"},"excerpt":{"type":"string","description":"Bounded, redacted excerpt."},"standards":{"type":"array","items":{"type":"string"}},"reproduce":{"type":"string"}}},"Finding":{"type":"object","required":["category","ruleId","title","status","weight","points","detail"],"properties":{"category":{"type":"string"},"ruleId":{"type":"string"},"title":{"type":"string"},"status":{"type":"string","enum":["pass","warn","fail","unmeasured","not_applicable","unable_to_verify"]},"weight":{"type":"number","minimum":0},"points":{"type":"number","minimum":0},"detail":{"type":"string"},"evidence":{"type":"object","additionalProperties":true},"protocolEvidence":{"type":"array","items":{"$ref":"#/components/schemas/RequestEvidence"}},"confidence":{"type":"string","enum":["high","medium","low"]},"reproduce":{"type":"string"},"severity":{"type":"string","enum":["info","low","medium","high","critical"]},"remediation":{"type":"string"}}},"AgentEvidence":{"type":"object","required":["id","kind","sourceUrl","method","observedAt","summary","confidence"],"properties":{"id":{"type":"string"},"kind":{"type":"string"},"sourceUrl":{"type":"string","format":"uri"},"method":{"type":"string"},"observedAt":{"type":"string","format":"date-time"},"status":{"type":"integer"},"contentType":{"type":"string"},"summary":{"type":"string"},"confidence":{"type":"string","enum":["high","medium","low"]},"reproduce":{"type":"string"}}},"ScanReport":{"type":"object","required":["scanner","rubricVersion","suiteVersion","target","url","finalUrl","score","grade","findings","evidence","resources","coverage","applicability","authorizedSecurity","traceId","scannedAt"],"properties":{"scanner":{"type":"object","required":["name","version"],"properties":{"name":{"type":"string"},"version":{"type":"string"}}},"rubricVersion":{"type":"string"},"suiteVersion":{"type":"string"},"target":{"type":"object","required":["submittedUrl","normalizedUrl","finalUrl"],"properties":{"submittedUrl":{"type":"string","format":"uri"},"normalizedUrl":{"type":"string","format":"uri"},"finalUrl":{"type":"string","format":"uri"}}},"url":{"type":"string","format":"uri"},"finalUrl":{"type":"string","format":"uri"},"title":{"type":"string"},"score":{"type":"number","minimum":0,"maximum":100},"grade":{"type":"string"},"summary":{"type":"string"},"remediationPrompt":{"type":"string","description":"Generated prompt for the highest-impact observed fixes."},"recommendations":{"type":"array","items":{"type":"string"}},"findings":{"type":"array","items":{"$ref":"#/components/schemas/Finding"}},"evidence":{"type":"array","items":{"$ref":"#/components/schemas/AgentEvidence"}},"resources":{"type":"array","items":{"type":"object","required":["url","status","type","source"],"properties":{"url":{"type":"string","format":"uri"},"status":{"type":"integer"},"type":{"type":"string"},"source":{"type":"string","enum":["origin","shared_scan_context"]}}}},"categoryScores":{"type":"object","additionalProperties":{"type":["number","null"]}},"coverage":{"type":"object","required":["measured","unmeasured","notApplicable","unableToVerify","total"],"properties":{"measured":{"type":"integer"},"unmeasured":{"type":"integer"},"notApplicable":{"type":"integer"},"unableToVerify":{"type":"integer"},"total":{"type":"integer"}}},"applicability":{"type":"object","required":["notApplicable","unableToVerify"],"properties":{"notApplicable":{"type":"array","items":{"type":"string"}},"unableToVerify":{"type":"array","items":{"type":"string"}}}},"clientMetrics":{"type":"object","additionalProperties":true},"authorizedSecurity":{"type":"boolean"},"traceId":{"type":"string"},"scannedAt":{"type":"string","format":"date-time"},"sharedScanContext":{"type":"object","description":"AnswerReady provenance for bounded reused artifacts.","properties":{"scanId":{"type":"string"},"normalizedUrl":{"type":"string","format":"uri"},"traceparent":{"type":"string"},"artifactRefs":{"type":"array","maxItems":32}}},"reportCompleteness":{"type":"string","enum":["complete","findings_only"],"description":"Protected AnswerReady response contract state; findings_only never fabricates omitted report fields."},"reportMissingFields":{"type":"array","items":{"type":"string"}}}},"ScanLocatorResponse":{"type":"object","required":["ok","data","meta"],"properties":{"ok":{"type":"boolean","const":true},"data":{"type":"object","required":["id","status","score","grade","reportUrl","resultUrl"],"properties":{"id":{"type":"string"},"status":{"type":"string"},"score":{"type":"number"},"grade":{"type":"string"},"reportUrl":{"type":"string"},"resultUrl":{"type":"string"}}},"meta":{"type":"object","additionalProperties":true}}},"FullReportResponse":{"type":"object","required":["ok","data","meta"],"properties":{"ok":{"type":"boolean","const":true},"data":{"$ref":"#/components/schemas/ScanReport"},"meta":{"type":"object","additionalProperties":true}}},"PersistedReportResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","additionalProperties":true,"description":"Persisted scan record with the complete report under data.report."}}},"ErrorResponse":{"type":"object","required":["ok","error"],"properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","required":["code","message","details"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}}},"meta":{"type":"object","additionalProperties":true}}}}}}