{
  "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",
          "coreScore",
          "coreGrade",
          "coreCoverage",
          "coreScoreVerified",
          "coreSummary",
          "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,
            "description": "Primary complete-suite score across normalized AnswerReady and downstream checks."
          },
          "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
          },
          "coreScore": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100,
            "description": "Preserved AnswerReady AEO/GEO/SEO core-rubric score."
          },
          "coreGrade": {
            "type": "string",
            "enum": [
              "A",
              "B",
              "C",
              "D",
              "F"
            ]
          },
          "coreCoverage": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          },
          "coreScoreVerified": {
            "type": "boolean"
          },
          "coreSummary": {
            "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
          },
          "discoveryTool": {
            "const": "answerready:tool:get_info"
          },
          "apiToolPattern": {
            "const": "answerready:api:*"
          },
          "apiProjection": {
            "const": "Every documented OpenAPI operation is exposed as an executable MCP tool definition."
          },
          "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."
      }
    }
  }
}