{"openapi":"3.1.0","info":{"title":"ReadinessAPI","version":"0.1.0","description":"Run a deterministic ruleset that produces a heuristic OpenAPI agent-readiness score.","contact":{"name":"ReadinessAPI support"},"x-rules-version":"2026-07-17.2"},"servers":[{"url":"http://localhost:3000"}],"paths":{"/readyz":{"get":{"operationId":"getServiceReadiness","summary":"Check deployment readiness","description":"Use this lightweight operation to verify that required configuration, Redis, and the paid-audit integration are ready. It returns check names only and causes no state change, so confirmation is not required.","tags":["operations"],"responses":{"200":{"description":"The deployment is ready to serve free and paid audits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReadinessResponse"}}}},"503":{"description":"One or more required deployment checks are not ready.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReadinessResponse"}}}}}}},"/v1/openapi/score":{"post":{"operationId":"scoreOpenApiForAgents","summary":"Score an OpenAPI contract for agent readiness","description":"Use this free operation for a labeled heuristic readiness score, category metrics, applied score caps, and the five highest-priority findings. It only analyzes input and causes no external state change, so confirmation is not required.","tags":["audit"],"requestBody":{"required":true,"description":"Submit one OpenAPI 3.0 or 3.1 document as JSON or YAML text for a free deterministic readiness score.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScoreRequest"}}}},"responses":{"200":{"description":"Readiness score.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScoreResponse"}}}},"400":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"415":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/v1/openapi/audit":{"post":{"operationId":"auditOpenApiForAgents","summary":"Run a full paid agent-readiness audit","description":"Use this x402-protected operation for all findings, safe JSON Patch proposals, MCP tool candidates, and separate raw-input, semantic-input, and audit-result hashes. The audit causes no external state change beyond its explicit x402 payment, which the caller confirms before invocation.","tags":["audit"],"requestBody":{"required":true,"description":"Submit one OpenAPI 3.0 or 3.1 document and optional artifact controls for the paid deterministic audit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditRequest"}}}},"responses":{"200":{"description":"Complete rules-based audit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditResponse"}}}},"402":{"description":"Payment required through x402 v2.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"409":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}}},"components":{"schemas":{"ScoreRequest":{"type":"object","required":["specification"],"properties":{"specification":{"type":"string","maxLength":4194304}},"additionalProperties":false},"AuditRequest":{"allOf":[{"$ref":"#/components/schemas/ScoreRequest"},{"type":"object","properties":{"options":{"type":"object","properties":{"includeJsonPatch":{"type":"boolean","default":true},"includeMcpTools":{"type":"boolean","default":true},"includeOperationIds":{"type":"array","maxItems":500,"items":{"type":"string"}}},"additionalProperties":false}}}]},"Finding":{"type":"object","required":["id","rule_id","category","severity","location","message","impact","remediation","analysis_type","confidence","evidence"],"properties":{"id":{"type":"string"},"rule_id":{"type":"string"},"category":{"type":"string"},"severity":{"type":"string","enum":["critical","high","medium","low"]},"location":{"type":"string","description":"RFC 6901 JSON Pointer."},"message":{"type":"string"},"impact":{"type":"string"},"remediation":{"type":"string"},"analysis_type":{"type":"string","enum":["deterministic","heuristic","derived_behavior"]},"confidence":{"type":"number","minimum":0,"maximum":1},"evidence":{"type":"object","additionalProperties":true}},"additionalProperties":false},"ScoreResponse":{"type":"object","required":["raw_score","score","score_label","score_caps","classification","metrics","spec_summary","top_findings","rules_version","checks"],"properties":{"raw_score":{"type":"integer","minimum":0,"maximum":100,"description":"Weighted score before safety and validity gates."},"score":{"type":"integer","minimum":0,"maximum":100},"score_label":{"type":"string","const":"ReadinessAPI heuristic score"},"score_caps":{"type":"array","items":{"type":"object","required":["rule","cap","classification"],"properties":{"rule":{"type":"string"},"cap":{"type":"integer","minimum":0,"maximum":100},"classification":{"type":"string"}}}},"classification":{"type":"string","enum":["agent_ready","usable_with_warnings","needs_work","not_agent_ready","invalid"]},"metrics":{"type":"object","additionalProperties":{"type":"integer"}},"spec_summary":{"type":"object"},"critical_issue_count":{"type":"integer"},"high_issue_count":{"type":"integer"},"top_findings":{"type":"array","maxItems":5,"items":{"$ref":"#/components/schemas/Finding"}},"rules_version":{"type":"string"},"checks":{"type":"object","required":["total","applicable","passed","failed","not_applicable","findings_truncated"],"properties":{"total":{"type":"integer"},"applicable":{"type":"integer"},"passed":{"type":"integer"},"failed":{"type":"integer"},"not_applicable":{"type":"integer"},"findings_truncated":{"type":"boolean"}}},"next":{"type":"object"}}},"AuditResponse":{"allOf":[{"$ref":"#/components/schemas/ScoreResponse"},{"type":"object","required":["findings","patches","mcp","metadata","integrity"],"properties":{"findings":{"type":"array","items":{"$ref":"#/components/schemas/Finding"}},"patches":{"type":"array","items":{"type":"object","additionalProperties":true}},"mcp":{"type":"object"},"metadata":{"type":"object","required":["generated_at"],"properties":{"generated_at":{"type":"string","format":"date-time"}}},"integrity":{"type":"object","required":["raw_input_sha256","semantic_input_sha256","audit_result_sha256","rules_version"],"properties":{"raw_input_sha256":{"type":"string","pattern":"^[a-f0-9]{64}$"},"semantic_input_sha256":{"type":"string","pattern":"^[a-f0-9]{64}$"},"audit_result_sha256":{"type":"string","pattern":"^[a-f0-9]{64}$"},"rules_version":{"type":"string"}}}}}]},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string","format":"uuid"},"details":{}}}}},"ReadinessResponse":{"type":"object","required":["status","rules_version","checks"],"properties":{"status":{"type":"string","enum":["ready","not_ready"]},"rules_version":{"type":"string"},"checks":{"type":"object","required":["configuration","redis","payments"],"properties":{"configuration":{"type":"string","enum":["ok","invalid"]},"redis":{"type":"string","enum":["ok","missing","unavailable"]},"payments":{"type":"string","enum":["configured","disabled","invalid"]}},"additionalProperties":false}},"additionalProperties":false}},"responses":{"Error":{"description":"Error response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"tags":[{"name":"audit","description":"OpenAPI agent-readiness analysis."},{"name":"operations","description":"Non-sensitive service health and readiness checks."}]}