{
  "openapi": "3.1.0",
  "info": {
    "title": "AIEO API",
    "version": "0.0.1",
    "summary": "AI-search-readiness scans as JSON or Markdown, built for agents as much as browsers.",
    "description": "Every scan AIEO runs returns the same v2 ScanReport shape: an overall score, four weighted group scores, a flat list of individual checks, a top-5 fix list ranked by recoverable points, and a security posture badge. Responses are public (CORS open) and rate-limited per IP per hour via Cloudflare KV.",
    "contact": {
      "name": "AIEO",
      "url": "https://aieo.fyi",
      "email": "hello@aieo.fyi"
    },
    "license": {
      "name": "Report data: public, no licence required to read your own scan."
    }
  },
  "servers": [
    {
      "url": "https://aieo.fyi",
      "description": "Production"
    }
  ],
  "tags": [
    {
      "name": "scan",
      "description": "Run a scan and get a report."
    },
    {
      "name": "report",
      "description": "Read back a previously persisted report."
    }
  ],
  "paths": {
    "/api/agent-scan": {
      "get": {
        "operationId": "agentScan",
        "tags": [
          "scan"
        ],
        "summary": "Scan a domain",
        "description": "Runs a full AIEO scan for a domain and returns the v2 report as JSON, or as Markdown with ?format=md. A successful scan is persisted to KV for 7 days (fail-open: storage errors are noted in meta.warnings, never fail the scan). Rate limited per IP per hour — 12/hour by default, 20/hour with ?source=compare.",
        "parameters": [
          {
            "name": "domain",
            "in": "query",
            "required": true,
            "description": "Bare domain to scan, e.g. example.com (a scheme, if present, is stripped).",
            "schema": {
              "type": "string"
            },
            "example": "example.com"
          },
          {
            "name": "format",
            "in": "query",
            "required": false,
            "description": "\"json\" or \"md\" explicitly selects the response format. Otherwise Accept weights select JSON or Markdown; ties and unsupported preferences return JSON.",
            "schema": {
              "type": "string",
              "enum": [
                "json",
                "md"
              ]
            }
          },
          {
            "name": "budget",
            "in": "query",
            "required": false,
            "description": "Set to 1 to read the caller’s remaining rate-limit budget without spending a scan.",
            "schema": {
              "type": "string",
              "enum": [
                "1"
              ]
            }
          },
          {
            "name": "source",
            "in": "query",
            "required": false,
            "description": "Set to \"compare\" to use the /compare rate-limit bucket (20/hour) instead of the default agent bucket (12/hour).",
            "schema": {
              "type": "string",
              "enum": [
                "compare"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A completed scan report, or a rate-limit budget probe when ?budget=1 is set.",
            "headers": {
              "X-RateLimit-Limit": {
                "description": "Requests allowed in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Reset": {
                "description": "Unix timestamp in seconds when the window resets. The JSON rateLimit.resetAt field uses ISO-8601.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "The v2 scan report: every v1 field the scanner has always returned, plus catalogue-enriched checks, groups, topFixes and a rate-limit snapshot.",
                  "properties": {
                    "version": {
                      "type": "integer",
                      "enum": [
                        2
                      ]
                    },
                    "domain": {
                      "type": "string"
                    },
                    "scannedAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "id": {
                      "type": "string",
                      "nullable": true,
                      "description": "Null when the report could not be persisted (no KV binding, or a storage error)."
                    },
                    "reportUrl": {
                      "type": "string",
                      "format": "uri",
                      "nullable": true
                    },
                    "expiresAt": {
                      "type": "string",
                      "format": "date-time",
                      "nullable": true
                    },
                    "scores": {
                      "type": "object",
                      "properties": {
                        "overall": {
                          "type": "integer"
                        },
                        "traditionalSEO": {
                          "type": "integer"
                        },
                        "aiDiscoverability": {
                          "type": "integer"
                        },
                        "schemaCoverage": {
                          "type": "integer"
                        },
                        "agentInteraction": {
                          "type": "integer"
                        }
                      }
                    },
                    "groups": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "label": {
                            "type": "string"
                          },
                          "question": {
                            "type": "string"
                          },
                          "weight": {
                            "type": "integer"
                          },
                          "score": {
                            "type": "integer"
                          },
                          "checkIds": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          }
                        },
                        "required": [
                          "id",
                          "label",
                          "question",
                          "weight",
                          "score",
                          "checkIds"
                        ]
                      }
                    },
                    "checks": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "group": {
                            "type": "string",
                            "enum": [
                              "traditionalSEO",
                              "aiDiscoverability",
                              "schemaCoverage",
                              "agentInteraction",
                              "security"
                            ]
                          },
                          "category": {
                            "type": "string"
                          },
                          "title": {
                            "type": "string"
                          },
                          "severity": {
                            "type": "string",
                            "enum": [
                              "pass",
                              "warn",
                              "fail",
                              "info"
                            ]
                          },
                          "scoreMode": {
                            "type": "string",
                            "enum": [
                              "scored",
                              "informative",
                              "notApplicable"
                            ]
                          },
                          "detail": {
                            "type": "string"
                          },
                          "fix": {
                            "type": "string",
                            "nullable": true
                          },
                          "why": {
                            "type": "string"
                          },
                          "learnMoreUrl": {
                            "type": "string",
                            "format": "uri"
                          },
                          "scope": {
                            "type": "string",
                            "enum": [
                              "page",
                              "site"
                            ]
                          },
                          "pageUrl": {
                            "type": "string",
                            "format": "uri"
                          },
                          "order": {
                            "type": "integer"
                          },
                          "pointsRecoverable": {
                            "type": "number"
                          },
                          "pagesAffected": {
                            "type": "integer"
                          }
                        },
                        "required": [
                          "id",
                          "group",
                          "category",
                          "title",
                          "severity",
                          "scoreMode",
                          "detail",
                          "why",
                          "learnMoreUrl",
                          "scope",
                          "order",
                          "pointsRecoverable"
                        ]
                      }
                    },
                    "summary": {
                      "type": "object",
                      "properties": {
                        "pass": {
                          "type": "integer"
                        },
                        "warn": {
                          "type": "integer"
                        },
                        "fail": {
                          "type": "integer"
                        },
                        "info": {
                          "type": "integer"
                        },
                        "total": {
                          "type": "integer"
                        }
                      }
                    },
                    "topFixes": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "title": {
                            "type": "string"
                          },
                          "severity": {
                            "type": "string",
                            "enum": [
                              "warn",
                              "fail"
                            ]
                          },
                          "fix": {
                            "type": "string"
                          },
                          "group": {
                            "type": "string"
                          },
                          "pageUrl": {
                            "type": "string",
                            "format": "uri"
                          },
                          "pointsRecoverable": {
                            "type": "number"
                          },
                          "pagesAffected": {
                            "type": "integer"
                          }
                        },
                        "required": [
                          "id",
                          "title",
                          "severity",
                          "fix",
                          "group",
                          "pointsRecoverable",
                          "pagesAffected"
                        ]
                      },
                      "maxItems": 5
                    },
                    "security": {
                      "type": "object",
                      "properties": {
                        "grade": {
                          "type": "string"
                        },
                        "score": {
                          "type": "integer"
                        },
                        "checks": {
                          "type": "integer"
                        },
                        "items": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "group": {
                                "type": "string",
                                "enum": [
                                  "traditionalSEO",
                                  "aiDiscoverability",
                                  "schemaCoverage",
                                  "agentInteraction",
                                  "security"
                                ]
                              },
                              "category": {
                                "type": "string"
                              },
                              "title": {
                                "type": "string"
                              },
                              "severity": {
                                "type": "string",
                                "enum": [
                                  "pass",
                                  "warn",
                                  "fail",
                                  "info"
                                ]
                              },
                              "scoreMode": {
                                "type": "string",
                                "enum": [
                                  "scored",
                                  "informative",
                                  "notApplicable"
                                ]
                              },
                              "detail": {
                                "type": "string"
                              },
                              "fix": {
                                "type": "string",
                                "nullable": true
                              },
                              "why": {
                                "type": "string"
                              },
                              "learnMoreUrl": {
                                "type": "string",
                                "format": "uri"
                              },
                              "scope": {
                                "type": "string",
                                "enum": [
                                  "page",
                                  "site"
                                ]
                              },
                              "pageUrl": {
                                "type": "string",
                                "format": "uri"
                              },
                              "order": {
                                "type": "integer"
                              },
                              "pointsRecoverable": {
                                "type": "number"
                              },
                              "pagesAffected": {
                                "type": "integer"
                              }
                            },
                            "required": [
                              "id",
                              "group",
                              "category",
                              "title",
                              "severity",
                              "scoreMode",
                              "detail",
                              "why",
                              "learnMoreUrl",
                              "scope",
                              "order",
                              "pointsRecoverable"
                            ]
                          }
                        }
                      }
                    },
                    "rateLimit": {
                      "type": "object",
                      "properties": {
                        "limit": {
                          "type": "integer"
                        },
                        "remaining": {
                          "type": "integer"
                        },
                        "resetAt": {
                          "type": "string",
                          "format": "date-time"
                        }
                      },
                      "required": [
                        "limit",
                        "remaining",
                        "resetAt"
                      ]
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "scriptsScanned": {
                          "type": "integer"
                        },
                        "durationMs": {
                          "type": "number"
                        },
                        "warnings": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  },
                  "required": [
                    "version",
                    "domain",
                    "scannedAt",
                    "id",
                    "reportUrl",
                    "expiresAt",
                    "scores",
                    "groups",
                    "checks",
                    "summary",
                    "topFixes",
                    "security",
                    "rateLimit",
                    "meta"
                  ]
                }
              },
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid domain.",
            "headers": {
              "X-RateLimit-Limit": {
                "description": "Requests allowed in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Reset": {
                "description": "Unix timestamp in seconds when the window resets. The JSON rateLimit.resetAt field uses ISO-8601.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "id": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Rate limit reached for this IP and bucket.",
            "headers": {
              "X-RateLimit-Limit": {
                "description": "Requests allowed in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Reset": {
                "description": "Unix timestamp in seconds when the window resets. The JSON rateLimit.resetAt field uses ISO-8601.",
                "schema": {
                  "type": "integer"
                }
              },
              "Retry-After": {
                "description": "Seconds to wait before retrying. Sent only on a 429 response.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "error": {
                          "type": "string"
                        },
                        "id": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "error"
                      ]
                    },
                    {
                      "type": "object",
                      "properties": {
                        "rateLimit": {
                          "type": "object",
                          "properties": {
                            "limit": {
                              "type": "integer"
                            },
                            "remaining": {
                              "type": "integer"
                            },
                            "resetAt": {
                              "type": "string",
                              "format": "date-time"
                            }
                          },
                          "required": [
                            "limit",
                            "remaining",
                            "resetAt"
                          ]
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "500": {
            "description": "The scan failed unexpectedly.",
            "headers": {
              "X-RateLimit-Limit": {
                "description": "Requests allowed in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Remaining": {
                "description": "Requests left in the current window.",
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Reset": {
                "description": "Unix timestamp in seconds when the window resets. The JSON rateLimit.resetAt field uses ISO-8601.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "id": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      },
      "head": {
        "operationId": "agentScanHead",
        "tags": [
          "scan"
        ],
        "summary": "Headers only, same as GET.",
        "responses": {
          "200": {
            "description": "Headers only."
          }
        }
      }
    },
    "/api/demo": {
      "post": {
        "operationId": "demoScan",
        "tags": [
          "scan"
        ],
        "summary": "Scan a domain (instant, no email)",
        "description": "Same engine and v2 report contract as /api/agent-scan. Body: { \"domain\": \"example.com\" }. Rate limited 10/IP/hour. Persists the report to KV for 7 days on success.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "domain": {
                    "type": "string"
                  }
                },
                "required": [
                  "domain"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "A completed scan report.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "The v2 scan report: every v1 field the scanner has always returned, plus catalogue-enriched checks, groups, topFixes and a rate-limit snapshot.",
                  "properties": {
                    "version": {
                      "type": "integer",
                      "enum": [
                        2
                      ]
                    },
                    "domain": {
                      "type": "string"
                    },
                    "scannedAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "id": {
                      "type": "string",
                      "nullable": true,
                      "description": "Null when the report could not be persisted (no KV binding, or a storage error)."
                    },
                    "reportUrl": {
                      "type": "string",
                      "format": "uri",
                      "nullable": true
                    },
                    "expiresAt": {
                      "type": "string",
                      "format": "date-time",
                      "nullable": true
                    },
                    "scores": {
                      "type": "object",
                      "properties": {
                        "overall": {
                          "type": "integer"
                        },
                        "traditionalSEO": {
                          "type": "integer"
                        },
                        "aiDiscoverability": {
                          "type": "integer"
                        },
                        "schemaCoverage": {
                          "type": "integer"
                        },
                        "agentInteraction": {
                          "type": "integer"
                        }
                      }
                    },
                    "groups": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "label": {
                            "type": "string"
                          },
                          "question": {
                            "type": "string"
                          },
                          "weight": {
                            "type": "integer"
                          },
                          "score": {
                            "type": "integer"
                          },
                          "checkIds": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          }
                        },
                        "required": [
                          "id",
                          "label",
                          "question",
                          "weight",
                          "score",
                          "checkIds"
                        ]
                      }
                    },
                    "checks": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "group": {
                            "type": "string",
                            "enum": [
                              "traditionalSEO",
                              "aiDiscoverability",
                              "schemaCoverage",
                              "agentInteraction",
                              "security"
                            ]
                          },
                          "category": {
                            "type": "string"
                          },
                          "title": {
                            "type": "string"
                          },
                          "severity": {
                            "type": "string",
                            "enum": [
                              "pass",
                              "warn",
                              "fail",
                              "info"
                            ]
                          },
                          "scoreMode": {
                            "type": "string",
                            "enum": [
                              "scored",
                              "informative",
                              "notApplicable"
                            ]
                          },
                          "detail": {
                            "type": "string"
                          },
                          "fix": {
                            "type": "string",
                            "nullable": true
                          },
                          "why": {
                            "type": "string"
                          },
                          "learnMoreUrl": {
                            "type": "string",
                            "format": "uri"
                          },
                          "scope": {
                            "type": "string",
                            "enum": [
                              "page",
                              "site"
                            ]
                          },
                          "pageUrl": {
                            "type": "string",
                            "format": "uri"
                          },
                          "order": {
                            "type": "integer"
                          },
                          "pointsRecoverable": {
                            "type": "number"
                          },
                          "pagesAffected": {
                            "type": "integer"
                          }
                        },
                        "required": [
                          "id",
                          "group",
                          "category",
                          "title",
                          "severity",
                          "scoreMode",
                          "detail",
                          "why",
                          "learnMoreUrl",
                          "scope",
                          "order",
                          "pointsRecoverable"
                        ]
                      }
                    },
                    "summary": {
                      "type": "object",
                      "properties": {
                        "pass": {
                          "type": "integer"
                        },
                        "warn": {
                          "type": "integer"
                        },
                        "fail": {
                          "type": "integer"
                        },
                        "info": {
                          "type": "integer"
                        },
                        "total": {
                          "type": "integer"
                        }
                      }
                    },
                    "topFixes": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "title": {
                            "type": "string"
                          },
                          "severity": {
                            "type": "string",
                            "enum": [
                              "warn",
                              "fail"
                            ]
                          },
                          "fix": {
                            "type": "string"
                          },
                          "group": {
                            "type": "string"
                          },
                          "pageUrl": {
                            "type": "string",
                            "format": "uri"
                          },
                          "pointsRecoverable": {
                            "type": "number"
                          },
                          "pagesAffected": {
                            "type": "integer"
                          }
                        },
                        "required": [
                          "id",
                          "title",
                          "severity",
                          "fix",
                          "group",
                          "pointsRecoverable",
                          "pagesAffected"
                        ]
                      },
                      "maxItems": 5
                    },
                    "security": {
                      "type": "object",
                      "properties": {
                        "grade": {
                          "type": "string"
                        },
                        "score": {
                          "type": "integer"
                        },
                        "checks": {
                          "type": "integer"
                        },
                        "items": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "group": {
                                "type": "string",
                                "enum": [
                                  "traditionalSEO",
                                  "aiDiscoverability",
                                  "schemaCoverage",
                                  "agentInteraction",
                                  "security"
                                ]
                              },
                              "category": {
                                "type": "string"
                              },
                              "title": {
                                "type": "string"
                              },
                              "severity": {
                                "type": "string",
                                "enum": [
                                  "pass",
                                  "warn",
                                  "fail",
                                  "info"
                                ]
                              },
                              "scoreMode": {
                                "type": "string",
                                "enum": [
                                  "scored",
                                  "informative",
                                  "notApplicable"
                                ]
                              },
                              "detail": {
                                "type": "string"
                              },
                              "fix": {
                                "type": "string",
                                "nullable": true
                              },
                              "why": {
                                "type": "string"
                              },
                              "learnMoreUrl": {
                                "type": "string",
                                "format": "uri"
                              },
                              "scope": {
                                "type": "string",
                                "enum": [
                                  "page",
                                  "site"
                                ]
                              },
                              "pageUrl": {
                                "type": "string",
                                "format": "uri"
                              },
                              "order": {
                                "type": "integer"
                              },
                              "pointsRecoverable": {
                                "type": "number"
                              },
                              "pagesAffected": {
                                "type": "integer"
                              }
                            },
                            "required": [
                              "id",
                              "group",
                              "category",
                              "title",
                              "severity",
                              "scoreMode",
                              "detail",
                              "why",
                              "learnMoreUrl",
                              "scope",
                              "order",
                              "pointsRecoverable"
                            ]
                          }
                        }
                      }
                    },
                    "rateLimit": {
                      "type": "object",
                      "properties": {
                        "limit": {
                          "type": "integer"
                        },
                        "remaining": {
                          "type": "integer"
                        },
                        "resetAt": {
                          "type": "string",
                          "format": "date-time"
                        }
                      },
                      "required": [
                        "limit",
                        "remaining",
                        "resetAt"
                      ]
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "scriptsScanned": {
                          "type": "integer"
                        },
                        "durationMs": {
                          "type": "number"
                        },
                        "warnings": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  },
                  "required": [
                    "version",
                    "domain",
                    "scannedAt",
                    "id",
                    "reportUrl",
                    "expiresAt",
                    "scores",
                    "groups",
                    "checks",
                    "summary",
                    "topFixes",
                    "security",
                    "rateLimit",
                    "meta"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid domain.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "id": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "429": {
            "description": "Rate limit reached.",
            "headers": {
              "Retry-After": {
                "description": "Seconds to wait before retrying. Sent only on a 429 response.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "properties": {
                        "error": {
                          "type": "string"
                        },
                        "id": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "error"
                      ]
                    },
                    {
                      "type": "object",
                      "properties": {
                        "rateLimit": {
                          "type": "object",
                          "properties": {
                            "limit": {
                              "type": "integer"
                            },
                            "remaining": {
                              "type": "integer"
                            },
                            "resetAt": {
                              "type": "string",
                              "format": "date-time"
                            }
                          },
                          "required": [
                            "limit",
                            "remaining",
                            "resetAt"
                          ]
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/report/{id}": {
      "get": {
        "operationId": "getReport",
        "tags": [
          "report"
        ],
        "summary": "Read a persisted report",
        "description": "Reads back a report saved by a prior /api/agent-scan or /api/demo call. Not rate limited — no scan runs. Ids are 12 lowercase Crockford base32 characters and expire after 7 days.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[0-9a-hjkmnp-tv-z]{12}$"
            }
          },
          {
            "name": "format",
            "in": "query",
            "required": false,
            "description": "\"json\" or \"md\" explicitly selects the response format. Otherwise Accept weights select JSON or Markdown; ties and unsupported preferences return JSON.",
            "schema": {
              "type": "string",
              "enum": [
                "json",
                "md"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The stored report.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "The v2 scan report: every v1 field the scanner has always returned, plus catalogue-enriched checks, groups, topFixes and a rate-limit snapshot.",
                  "properties": {
                    "version": {
                      "type": "integer",
                      "enum": [
                        2
                      ]
                    },
                    "domain": {
                      "type": "string"
                    },
                    "scannedAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "id": {
                      "type": "string",
                      "nullable": true,
                      "description": "Null when the report could not be persisted (no KV binding, or a storage error)."
                    },
                    "reportUrl": {
                      "type": "string",
                      "format": "uri",
                      "nullable": true
                    },
                    "expiresAt": {
                      "type": "string",
                      "format": "date-time",
                      "nullable": true
                    },
                    "scores": {
                      "type": "object",
                      "properties": {
                        "overall": {
                          "type": "integer"
                        },
                        "traditionalSEO": {
                          "type": "integer"
                        },
                        "aiDiscoverability": {
                          "type": "integer"
                        },
                        "schemaCoverage": {
                          "type": "integer"
                        },
                        "agentInteraction": {
                          "type": "integer"
                        }
                      }
                    },
                    "groups": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "label": {
                            "type": "string"
                          },
                          "question": {
                            "type": "string"
                          },
                          "weight": {
                            "type": "integer"
                          },
                          "score": {
                            "type": "integer"
                          },
                          "checkIds": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          }
                        },
                        "required": [
                          "id",
                          "label",
                          "question",
                          "weight",
                          "score",
                          "checkIds"
                        ]
                      }
                    },
                    "checks": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "group": {
                            "type": "string",
                            "enum": [
                              "traditionalSEO",
                              "aiDiscoverability",
                              "schemaCoverage",
                              "agentInteraction",
                              "security"
                            ]
                          },
                          "category": {
                            "type": "string"
                          },
                          "title": {
                            "type": "string"
                          },
                          "severity": {
                            "type": "string",
                            "enum": [
                              "pass",
                              "warn",
                              "fail",
                              "info"
                            ]
                          },
                          "scoreMode": {
                            "type": "string",
                            "enum": [
                              "scored",
                              "informative",
                              "notApplicable"
                            ]
                          },
                          "detail": {
                            "type": "string"
                          },
                          "fix": {
                            "type": "string",
                            "nullable": true
                          },
                          "why": {
                            "type": "string"
                          },
                          "learnMoreUrl": {
                            "type": "string",
                            "format": "uri"
                          },
                          "scope": {
                            "type": "string",
                            "enum": [
                              "page",
                              "site"
                            ]
                          },
                          "pageUrl": {
                            "type": "string",
                            "format": "uri"
                          },
                          "order": {
                            "type": "integer"
                          },
                          "pointsRecoverable": {
                            "type": "number"
                          },
                          "pagesAffected": {
                            "type": "integer"
                          }
                        },
                        "required": [
                          "id",
                          "group",
                          "category",
                          "title",
                          "severity",
                          "scoreMode",
                          "detail",
                          "why",
                          "learnMoreUrl",
                          "scope",
                          "order",
                          "pointsRecoverable"
                        ]
                      }
                    },
                    "summary": {
                      "type": "object",
                      "properties": {
                        "pass": {
                          "type": "integer"
                        },
                        "warn": {
                          "type": "integer"
                        },
                        "fail": {
                          "type": "integer"
                        },
                        "info": {
                          "type": "integer"
                        },
                        "total": {
                          "type": "integer"
                        }
                      }
                    },
                    "topFixes": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "title": {
                            "type": "string"
                          },
                          "severity": {
                            "type": "string",
                            "enum": [
                              "warn",
                              "fail"
                            ]
                          },
                          "fix": {
                            "type": "string"
                          },
                          "group": {
                            "type": "string"
                          },
                          "pageUrl": {
                            "type": "string",
                            "format": "uri"
                          },
                          "pointsRecoverable": {
                            "type": "number"
                          },
                          "pagesAffected": {
                            "type": "integer"
                          }
                        },
                        "required": [
                          "id",
                          "title",
                          "severity",
                          "fix",
                          "group",
                          "pointsRecoverable",
                          "pagesAffected"
                        ]
                      },
                      "maxItems": 5
                    },
                    "security": {
                      "type": "object",
                      "properties": {
                        "grade": {
                          "type": "string"
                        },
                        "score": {
                          "type": "integer"
                        },
                        "checks": {
                          "type": "integer"
                        },
                        "items": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "group": {
                                "type": "string",
                                "enum": [
                                  "traditionalSEO",
                                  "aiDiscoverability",
                                  "schemaCoverage",
                                  "agentInteraction",
                                  "security"
                                ]
                              },
                              "category": {
                                "type": "string"
                              },
                              "title": {
                                "type": "string"
                              },
                              "severity": {
                                "type": "string",
                                "enum": [
                                  "pass",
                                  "warn",
                                  "fail",
                                  "info"
                                ]
                              },
                              "scoreMode": {
                                "type": "string",
                                "enum": [
                                  "scored",
                                  "informative",
                                  "notApplicable"
                                ]
                              },
                              "detail": {
                                "type": "string"
                              },
                              "fix": {
                                "type": "string",
                                "nullable": true
                              },
                              "why": {
                                "type": "string"
                              },
                              "learnMoreUrl": {
                                "type": "string",
                                "format": "uri"
                              },
                              "scope": {
                                "type": "string",
                                "enum": [
                                  "page",
                                  "site"
                                ]
                              },
                              "pageUrl": {
                                "type": "string",
                                "format": "uri"
                              },
                              "order": {
                                "type": "integer"
                              },
                              "pointsRecoverable": {
                                "type": "number"
                              },
                              "pagesAffected": {
                                "type": "integer"
                              }
                            },
                            "required": [
                              "id",
                              "group",
                              "category",
                              "title",
                              "severity",
                              "scoreMode",
                              "detail",
                              "why",
                              "learnMoreUrl",
                              "scope",
                              "order",
                              "pointsRecoverable"
                            ]
                          }
                        }
                      }
                    },
                    "rateLimit": {
                      "type": "object",
                      "properties": {
                        "limit": {
                          "type": "integer"
                        },
                        "remaining": {
                          "type": "integer"
                        },
                        "resetAt": {
                          "type": "string",
                          "format": "date-time"
                        }
                      },
                      "required": [
                        "limit",
                        "remaining",
                        "resetAt"
                      ]
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "scriptsScanned": {
                          "type": "integer"
                        },
                        "durationMs": {
                          "type": "number"
                        },
                        "warnings": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  },
                  "required": [
                    "version",
                    "domain",
                    "scannedAt",
                    "id",
                    "reportUrl",
                    "expiresAt",
                    "scores",
                    "groups",
                    "checks",
                    "summary",
                    "topFixes",
                    "security",
                    "rateLimit",
                    "meta"
                  ]
                }
              },
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "Malformed report id.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "id": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "404": {
            "description": "Unknown or expired report id.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "id": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          },
          "503": {
            "description": "Report storage is not configured on this deployment.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "id": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "error"
                  ]
                }
              }
            }
          }
        }
      },
      "head": {
        "operationId": "getReportHead",
        "tags": [
          "report"
        ],
        "summary": "Headers only, same as GET.",
        "responses": {
          "200": {
            "description": "Headers only."
          }
        }
      }
    }
  }
}