{"openapi":"3.1.0","info":{"title":"AnswerReady API","version":"0.6.4","description":"Scan any public website against an evidence-backed AEO, GEO, and SEO rubric, then inspect every score contribution and validated PlatPhorm enrichment result. Scores use rubric 2026-08-22.1."},"servers":[{"url":"https://answerready.platphormnews.com"}],"tags":[{"name":"Scoring","description":"Evidence-backed public site scoring."},{"name":"Platform","description":"Health, documentation, rubric, and MCP discovery."}],"paths":{"/api/scan":{"post":{"operationId":"createAnswerReadyScan","tags":["Scoring"],"summary":"Scan a public website","description":"Fetch a bounded public page and discovery resources, score every criterion from evidence, and validate external PlatPhorm enrichment inputs and outputs.","parameters":[{"name":"Accept","in":"header","required":false,"schema":{"type":"string"},"description":"Supports application/json and text/markdown with q-value negotiation."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"additionalProperties":false,"properties":{"url":{"type":"string","minLength":1,"maxLength":2048},"mode":{"type":"string","enum":["quick","standard","full","browser","network","developer"],"default":"standard"},"callerNetworkConsent":{"type":"boolean","default":false,"description":"Explicit consent for optional browser-measured caller-path metrics."},"clientMetrics":{"type":"object","maxProperties":50,"additionalProperties":true,"description":"Optional bounded caller-network context; accepted only with callerNetworkConsent=true and kept separate from target scoring."}}}}}},"responses":{"200":{"description":"Evidence-backed score","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScanSuccessResponse"}},"text/markdown":{"schema":{"type":"string"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"406":{"description":"Requested representation is not acceptable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Target could not be safely evaluated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/recent":{"get":{"operationId":"listRecentAnswerReadyScans","tags":["Scoring"],"summary":"List recent persisted scans","responses":{"200":{"description":"Recent public scan summaries"}}}},"/api/rubric":{"get":{"operationId":"getAnswerReadyRubric","tags":["Platform"],"summary":"Get the scoring rubric and evidence rules","responses":{"200":{"description":"Versioned 100-point rubric","content":{"application/json":{"schema":{"type":"object","required":["ok","data"],"properties":{"ok":{"const":true},"data":{"$ref":"#/components/schemas/RubricDocument"}},"additionalProperties":false}}}}}}},"/api/health":{"get":{"operationId":"getAnswerReadyHealth","tags":["Platform"],"summary":"Get public-safe health","responses":{"200":{"description":"Health summary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthSuccessResponse"}}}}}}},"/api/v1/health":{"get":{"operationId":"getVersionedAnswerReadyHealth","tags":["Platform"],"summary":"Get versioned public-safe health","responses":{"200":{"description":"Health summary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthSuccessResponse"}}}}}}},"/api/docs":{"get":{"operationId":"getAnswerReadyOpenApi","tags":["Platform"],"summary":"Get this OpenAPI document","responses":{"200":{"description":"OpenAPI JSON"}}}},"/api/mcp":{"get":{"operationId":"getAnswerReadyMcpMetadata","tags":["Platform"],"summary":"Get MCP transport metadata","responses":{"200":{"description":"MCP metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpMetadata"}}}}}},"post":{"operationId":"callAnswerReadyMcp","tags":["Platform"],"summary":"Call the AnswerReady JSON-RPC MCP server","requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/JsonRpcRequest"},{"type":"array","minItems":1,"maxItems":50,"items":{"$ref":"#/components/schemas/JsonRpcRequest"}}]}}}},"responses":{"200":{"description":"JSON-RPC response or batch","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/JsonRpcResponse"},{"type":"array","items":{"$ref":"#/components/schemas/JsonRpcResponse"}}]}}}},"204":{"description":"JSON-RPC notification produced no response"},"429":{"description":"MCP scan_site rate limit exceeded","headers":{"Retry-After":{"schema":{"type":"integer"}},"RateLimit-Limit":{"schema":{"type":"integer"}},"RateLimit-Remaining":{"schema":{"type":"integer"}}}}}}},"/api/v1/scans/{id}":{"get":{"operationId":"getAnswerReadyScanReport","summary":"Read a stored unified AnswerReady scan report","description":"Returns the canonical provider-normalized report as JSON or text/markdown according to Accept q-values.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Accept","in":"header","required":false,"schema":{"type":"string"},"description":"Supports application/json and text/markdown with q-value negotiation."}],"responses":{"200":{"description":"Unified scan report","content":{"application/json":{"schema":{"type":"object"}},"text/markdown":{"schema":{"type":"string"}}}},"404":{"description":"Structured report-not-found error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"406":{"description":"Requested representation is not acceptable"}}}},"/api/v1/scans/{id}/diff":{"get":{"operationId":"diffAnswerReadyScanReports","summary":"Compare two stored unified scans","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"against","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Normalized scan diff","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Missing comparison id"},"404":{"description":"Report not found"}}}}},"components":{"schemas":{"EvidenceRecord":{"type":"object","required":["source","method","observed","valid"],"properties":{"source":{"type":"string","format":"uri"},"method":{"type":"string","enum":["http","html-parse","derived","external-api"]},"observed":{"type":"string","minLength":1,"maxLength":1000},"valid":{"type":"boolean"},"statusCode":{"type":"integer","minimum":100,"maximum":599},"contentType":{"type":["string","null"],"maxLength":200},"provider":{"type":"string","maxLength":120}},"additionalProperties":false},"RubricCheck":{"type":"object","required":["id","label","categoryId","weight","rationale","fix","status","detail","evidence","pointsEarned","maxPoints","definedPoints","scoreImpact"],"properties":{"id":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"categoryId":{"type":"string","minLength":1},"weight":{"type":"number","minimum":0},"rationale":{"type":"string","minLength":1},"fix":{"type":"string","minLength":1},"status":{"type":"string","enum":["pass","warn","fail","skipped","not_applicable","unavailable","error"]},"detail":{"type":"string","minLength":1,"maxLength":2000},"evidence":{"type":"array","minItems":1,"maxItems":12,"items":{"$ref":"#/components/schemas/EvidenceRecord"}},"pointsEarned":{"type":"number","minimum":0},"maxPoints":{"type":"number","minimum":0},"definedPoints":{"type":"number","minimum":0},"scoreImpact":{"type":"string","enum":["scored","coverage_only"]}},"additionalProperties":false},"CategoryScore":{"type":"object","required":["id","name","description","weight","score","coverage","pointsEarned","maxPoints","definedPoints","checks"],"properties":{"id":{"type":"string","minLength":1},"name":{"type":"string","minLength":1},"description":{"type":"string","minLength":1},"weight":{"type":"number","minimum":0},"score":{"type":"integer","minimum":0,"maximum":100},"coverage":{"type":"integer","minimum":0,"maximum":100},"pointsEarned":{"type":"number","minimum":0},"maxPoints":{"type":"number","minimum":0},"definedPoints":{"type":"number","minimum":0},"checks":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/RubricCheck"}}},"additionalProperties":false},"PlatformComplianceAssessment":{"type":"object","required":["applicable","standard","status","score","passed","warnings","failed","observedAt","checks"],"properties":{"applicable":{"const":true},"standard":{"const":"PlatPhormNews Phase 1"},"status":{"type":"string","enum":["compliant","degraded","non_compliant"]},"score":{"type":"integer","minimum":0,"maximum":100},"passed":{"type":"integer","minimum":0},"warnings":{"type":"integer","minimum":0},"failed":{"type":"integer","minimum":0},"observedAt":{"type":"string","format":"date-time"},"checks":{"type":"array","minItems":1,"items":{"type":"object","required":["id","label","status","detail","evidence"],"properties":{"id":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"status":{"type":"string","enum":["pass","warn","fail"]},"detail":{"type":"string","minLength":1},"evidence":{"type":"array","minItems":1,"items":{"type":"string","minLength":1}}},"additionalProperties":false}}},"additionalProperties":false},"Enrichment":{"type":"object","required":["generatedAt","lenses"],"properties":{"generatedAt":{"type":"string","format":"date-time"},"lenses":{"type":"array","items":{"type":"object","required":["id","name","provider","providerUrl","status","score","summary","metrics"],"properties":{"id":{"type":"string","minLength":1},"name":{"type":"string","minLength":1},"provider":{"type":"string","minLength":1},"providerUrl":{"type":"string","format":"uri"},"status":{"type":"string","enum":["ok","degraded"]},"score":{"type":["integer","null"],"minimum":0,"maximum":100},"summary":{"type":"string","minLength":1},"metrics":{"type":"array","items":{"type":"object","required":["label","value"],"properties":{"label":{"type":"string","minLength":1},"value":{"type":"string"},"rating":{"type":"string","enum":["good","warn","poor"]}},"additionalProperties":false}},"validation":{"type":"object","required":["endpoint","input","output","observedAt","detail"],"properties":{"endpoint":{"type":"string","format":"uri"},"input":{"type":"string","enum":["valid","invalid"]},"output":{"type":"string","enum":["valid","invalid","unavailable"]},"observedAt":{"type":"string","format":"date-time"},"detail":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false}}},"additionalProperties":false},"ScanResult":{"type":"object","required":["url","finalUrl","fetchedAt","score","grade","coverage","applicablePoints","earnedPoints","totalDefinedPoints","passed","warned","failed","skipped","notApplicable","unavailable","errors","rubricVersion","evidenceCount","scoreVerified","summary","categories","meta","mode","unifiedScan"],"properties":{"id":{"type":"string","pattern":"^[a-z0-9]+$"},"url":{"type":"string","format":"uri"},"finalUrl":{"type":"string","format":"uri"},"fetchedAt":{"type":"string","format":"date-time"},"score":{"type":"integer","minimum":0,"maximum":100},"grade":{"type":"string","enum":["A","B","C","D","F"]},"coverage":{"type":"integer","minimum":0,"maximum":100},"applicablePoints":{"type":"number","minimum":0},"earnedPoints":{"type":"number","minimum":0},"totalDefinedPoints":{"type":"number","minimum":0},"passed":{"type":"integer","minimum":0},"warned":{"type":"integer","minimum":0},"failed":{"type":"integer","minimum":0},"skipped":{"type":"integer","minimum":0},"notApplicable":{"type":"integer","minimum":0},"unavailable":{"type":"integer","minimum":0},"errors":{"type":"integer","minimum":0},"rubricVersion":{"type":"string","minLength":1},"evidenceCount":{"type":"integer","minimum":1},"scoreVerified":{"type":"boolean"},"summary":{"type":"string","minLength":1},"mode":{"type":"string","enum":["quick","standard","full","browser","network","developer"]},"categories":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/CategoryScore"}},"meta":{"type":"object","required":["title","description","responseTimeMs","statusCode","wordCount","lang"],"properties":{"title":{"type":["string","null"]},"description":{"type":["string","null"]},"responseTimeMs":{"type":"integer","minimum":0},"statusCode":{"type":"integer","minimum":100,"maximum":599},"wordCount":{"type":"integer","minimum":0},"lang":{"type":["string","null"]}},"additionalProperties":false},"platformCompliance":{"$ref":"#/components/schemas/PlatformComplianceAssessment"},"enrichment":{"$ref":"#/components/schemas/Enrichment"},"unifiedScan":{"type":"object","description":"Canonical provider-normalized scan envelope; see /api/v1/scans/{id} for the stable stored representation."}},"additionalProperties":false},"RubricDocument":{"type":"object","required":["id","version","scoreRange","statusFactors","outcomeModel","evidenceRequired","evidenceRule","categories"],"properties":{"id":{"const":"answerready-evidence-rubric"},"version":{"type":"string","minLength":1},"scoreRange":{"type":"object","required":["minimum","maximum"],"properties":{"minimum":{"const":0},"maximum":{"const":100}},"additionalProperties":false},"statusFactors":{"type":"object","required":["pass","warn","fail"],"properties":{"pass":{"const":1},"warn":{"const":0.5},"fail":{"const":0}},"additionalProperties":false},"outcomeModel":{"type":"object","required":["scored","unscored","score","coverage"],"properties":{"scored":{"type":"array","items":{"type":"string","enum":["pass","warn","fail"]}},"unscored":{"type":"array","items":{"type":"string","enum":["skipped","not_applicable","unavailable","error"]}},"score":{"type":"string","minLength":1},"coverage":{"type":"string","minLength":1}},"additionalProperties":false},"evidenceRequired":{"const":true},"evidenceRule":{"type":"string","minLength":1},"categories":{"type":"array","minItems":1,"items":{"type":"object","required":["id","name","description","weight","criteria"],"properties":{"id":{"type":"string","minLength":1},"name":{"type":"string","minLength":1},"description":{"type":"string","minLength":1},"weight":{"type":"number","exclusiveMinimum":0},"criteria":{"type":"array","minItems":1,"items":{"type":"object","required":["id","label","categoryId","weight","rationale","fix"],"properties":{"id":{"type":"string","minLength":1},"label":{"type":"string","minLength":1},"categoryId":{"type":"string","minLength":1},"weight":{"type":"number","exclusiveMinimum":0},"rationale":{"type":"string","minLength":1},"fix":{"type":"string","minLength":1}},"additionalProperties":false}}},"additionalProperties":false}}},"additionalProperties":false},"HealthDocument":{"type":"object","required":["service","version","environment","status","timestamp","uptime","database","cache","mcp","trace","routeComplianceScore","routeCompliance","routeApplicability","observabilityComplianceScore","discoveryStatus","rssStatus","sitemapStatus","llmsStatus","openapiStatus","trustedDomainStatus","lastNetworkSyncAt","lastSitemapSyncAt","lastFeedSyncAt","vercelMetadataCaptured","rubric"],"properties":{"service":{"const":"platphorm-answer-ready"},"version":{"type":"string","minLength":1},"environment":{"type":"string","minLength":1},"status":{"type":"string","enum":["healthy","degraded"]},"timestamp":{"type":"string","format":"date-time"},"uptime":{"type":"integer","minimum":0},"database":{"type":"object","required":["status","detail"],"properties":{"status":{"type":"string","enum":["operational","configured_unverified","not_configured"]},"detail":{"type":"string"}},"additionalProperties":false},"cache":{"type":"object","required":["status","detail"],"properties":{"status":{"type":"string","enum":["operational","configured_unverified","not_configured"]},"detail":{"type":"string"}},"additionalProperties":false},"mcp":{"type":"object","required":["status","transport"],"properties":{"status":{"const":"operational"},"transport":{"type":"string","format":"uri"}},"additionalProperties":false},"trace":{"type":"object","required":["status","traceEnabled","traceExportEnabled","traceContextAccepted","traceContextPropagated","lastTraceExportAt","spansEmittedLast24h","propagationTestStatus","redactionStatus"],"properties":{"status":{"type":"string","enum":["operational","degraded"]},"traceEnabled":{"type":"boolean"},"traceExportEnabled":{"type":"boolean"},"traceContextAccepted":{"type":"boolean"},"traceContextPropagated":{"type":"boolean"},"lastTraceExportAt":{"type":["string","null"],"format":"date-time"},"spansEmittedLast24h":{"type":["integer","null"],"minimum":0},"propagationTestStatus":{"type":"string"},"redactionStatus":{"type":"string"}},"additionalProperties":false},"routeComplianceScore":{"type":"integer","minimum":0,"maximum":100},"routeCompliance":{"type":"object","required":["evidenceSource","supportedGroups","requiredGroups"],"properties":{"evidenceSource":{"const":"declared-route-registry"},"supportedGroups":{"type":"integer","minimum":0},"requiredGroups":{"type":"integer","minimum":1}},"additionalProperties":false},"routeApplicability":{"type":"object","required":["notApplicable"],"properties":{"notApplicable":{"type":"array","items":{"type":"object","required":["route","status","reason"],"properties":{"route":{"type":"string","pattern":"^/"},"status":{"const":"not_applicable"},"reason":{"type":"string","minLength":1}},"additionalProperties":false}}},"additionalProperties":false},"observabilityComplianceScore":{"type":"integer","minimum":0,"maximum":100},"discoveryStatus":{"type":"string"},"rssStatus":{"type":"string"},"sitemapStatus":{"type":"string"},"llmsStatus":{"type":"string"},"openapiStatus":{"type":"string"},"trustedDomainStatus":{"type":"string"},"lastNetworkSyncAt":{"type":["string","null"],"format":"date-time"},"lastSitemapSyncAt":{"type":["string","null"],"format":"date-time"},"lastFeedSyncAt":{"type":["string","null"],"format":"date-time"},"vercelMetadataCaptured":{"type":"boolean"},"rubric":{"type":"object","required":["version","criteria","evidenceRequired"],"properties":{"version":{"type":"string"},"criteria":{"type":"integer","minimum":1},"evidenceRequired":{"const":true}},"additionalProperties":false}},"additionalProperties":false},"HealthSuccessResponse":{"type":"object","required":["ok","data"],"properties":{"ok":{"const":true},"data":{"$ref":"#/components/schemas/HealthDocument"}},"additionalProperties":false},"ScanSuccessResponse":{"type":"object","required":["ok","data","meta"],"properties":{"ok":{"const":true},"data":{"$ref":"#/components/schemas/ScanResult"},"meta":{"type":"object","required":["remediationPrompt","consultationPrompt"],"properties":{"remediationPrompt":{"type":"string"},"consultationPrompt":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"ErrorResponse":{"type":"object","required":["ok","error"],"properties":{"ok":{"const":false},"error":{"type":"object","required":["code","message","details"],"properties":{"code":{"type":"string","minLength":1},"message":{"type":"string","minLength":1},"type":{"type":"string","format":"uri"},"title":{"type":"string","minLength":1},"status":{"type":"integer","minimum":400,"maximum":599},"detail":{"type":"string","minLength":1},"resolution":{"type":"string","minLength":1},"requestId":{"type":"string","minLength":1},"details":{"type":"object"}},"additionalProperties":false}},"additionalProperties":false},"JsonRpcRequest":{"type":"object","required":["jsonrpc","method"],"properties":{"jsonrpc":{"const":"2.0"},"id":{"type":["string","number","null"]},"method":{"type":"string","minLength":1},"params":{}},"additionalProperties":false},"JsonRpcResponse":{"type":"object","required":["jsonrpc","id"],"properties":{"jsonrpc":{"const":"2.0"},"id":{"type":["string","number","null"]},"result":{},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"integer"},"message":{"type":"string"},"data":{}},"additionalProperties":false}},"oneOf":[{"required":["result"]},{"required":["error"]}],"additionalProperties":false},"McpMetadata":{"type":"object","required":["name","title","version","description","protocol","transport","capabilities","authentication","usage"],"properties":{"name":{"type":"string"},"title":{"type":"string"},"version":{"type":"string"},"description":{"type":"string"},"protocol":{"const":"json-rpc-2.0"},"transport":{"type":"object","required":["type","url"],"properties":{"type":{"const":"streamable-http"},"url":{"type":"string","format":"uri"}},"additionalProperties":false},"capabilities":{"type":"object","required":["tools","resources","prompts"],"properties":{"tools":{"type":"boolean"},"resources":{"type":"boolean"},"prompts":{"type":"boolean"}},"additionalProperties":false},"authentication":{"type":"object","required":["publicReadOnly","protectedMutations"],"properties":{"publicReadOnly":{"type":"boolean"},"protectedMutations":{"const":"PLATPHORM_API_KEY"}},"additionalProperties":false},"usage":{"type":"object","required":["method","contentType","methods"],"properties":{"method":{"const":"POST"},"contentType":{"const":"application/json"},"methods":{"type":"array","minItems":8,"uniqueItems":true,"items":{"type":"string"}}},"additionalProperties":false}},"additionalProperties":false}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Use PLATPHORM_API_KEY for future protected operations."},"platphormApiKey":{"type":"apiKey","in":"header","name":"X-PlatPhorm-API-Key","description":"Use PLATPHORM_API_KEY for future protected operations."}}}}