{"openapi":"3.1.0","info":{"title":"PlatPhorm AgentReady API","version":"2026.2","description":"Independent, bounded, evidence-backed agent-readiness scanner. Public scans are read-only; 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/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"}}}}}}},"/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 caller measurements supplied only after explicit consent."},"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"],"properties":{"url":{"type":"string","format":"uri"},"status":{"type":"integer"},"type":{"type":"string"}}}},"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"}}},"ScanLocatorResponse":{"type":"object","required":["data","meta"],"properties":{"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":["data","meta"],"properties":{"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":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"meta":{"type":"object","additionalProperties":true}}}}}}