"openapi": "3.1.0"
"x-insights-counts":
  "qualityTestsAvailable": 2415
  "executableSuites": 7
  "visibleMethodologySuites": 14
  "methodologyChecks": 185
  "mcpTools": 59
  "rankingProfiles": 12
  "locales": 10
  "publicRoutes": 69
  "protectedRoutes": 10
  "discoveryArtifacts": 20
  "testRegistryVersion": "insights-quality-2026-05-10.2"
"info":
  "title": "PlatPhorm Insights API"
  "version": "3.0.1"
  "description": "AI-First web performance analysis API. Part of the PlatPhorm News Network. Includes advanced AI-era scoring for SEO, AEO, and GEO optimization."
  "contact":
    "name": "PlatPhorm News Network"
    "url": "https://platphormnews.com"
    "email": "api@platphormnews.com"
  "license":
    "name": "MIT"
    "url": "https://opensource.org/licenses/MIT"
  "x-mcp-endpoints":
    - "https://insights.platphormnews.com/api/mcp"
    - "https://mcp.platphormnews.com"
"servers":
  -
    "url": "https://insights.platphormnews.com"
    "description": "Production"
"paths":
  "/api/v1/analyze":
    "post":
      "summary": "Analyze URL"
      "description": "Run a comprehensive performance, accessibility, SEO, and best practices analysis on a URL. Includes AI-era scoring for readability, searchability, answerability, and audience fit."
      "operationId": "analyzeUrl"
      "tags":
        - "Analysis"
      "requestBody":
        "required": true
        "content":
          "application/json":
            "schema":
              "type": "object"
              "required":
                - "url"
              "properties":
                "url":
                  "type": "string"
                  "format": "uri"
                  "description": "URL to analyze"
                "strategy":
                  "type": "string"
                  "enum":
                    - "mobile"
                    - "desktop"
                    - "both"
                  "default": "both"
                "categories":
                  "type": "array"
                  "items":
                    "type": "string"
                    "enum":
                      - "performance"
                      - "accessibility"
                      - "seo"
                      - "best-practices"
                      - "core-web-vitals"
                      - "security"
                      - "carbon"
                      - "sustainability"
                      - "i18n"
                      - "readability"
                      - "searchability"
                      - "answerability"
                      - "audience"
                      - "aeo"
                      - "geo"
                      - "ai-readiness"
                      - "discovery"
                      - "route-compliance"
                      - "sitemap-feed"
                      - "structured-data"
                      - "mcp-api"
                      - "traceability"
                      - "mobile-responsive"
                      - "pwa"
                      - "content-utility"
                      - "trust-privacy"
                      - "agent-policy"
                "locale":
                  "type": "string"
                  "default": "en"
                "includeAI":
                  "type": "boolean"
                  "default": true
                  "description": "Include AI-powered recommendations"
                "includeCarbon":
                  "type": "boolean"
                  "default": true
                  "description": "Include carbon footprint analysis"
                "includeSecurity":
                  "type": "boolean"
                  "default": true
                  "description": "Include security headers analysis"
                "includeAdvancedScoring":
                  "type": "boolean"
                  "default": true
                  "description": "Include AI-era scoring (readability, searchability, answerability, audience)"
      "responses":
        "200":
          "description": "Analysis completed successfully"
          "content":
            "application/json":
              "schema":
                "$ref": "#/components/schemas/AnalysisResponse"
        "400":
          "description": "Invalid request"
        "429":
          "description": "Rate limit exceeded"
        "500":
          "description": "Analysis failed"
  "/api/v1/results/{id}":
    "get":
      "summary": "Get Analysis Results"
      "description": "Retrieve results of a previously run analysis."
      "operationId": "getResults"
      "tags":
        - "Analysis"
      "parameters":
        -
          "name": "id"
          "in": "path"
          "required": true
          "schema":
            "type": "string"
      "responses":
        "200":
          "description": "Analysis results"
        "404":
          "description": "Analysis not found"
  "/api/v1/compare":
    "post":
      "summary": "Compare URLs"
      "description": "Compare performance metrics across multiple URLs."
      "operationId": "compareUrls"
      "tags":
        - "Comparison"
      "requestBody":
        "required": true
        "content":
          "application/json":
            "schema":
              "type": "object"
              "required":
                - "urls"
              "properties":
                "urls":
                  "type": "array"
                  "items":
                    "type": "string"
                    "format": "uri"
                  "minItems": 2
                  "maxItems": 5
                "strategy":
                  "type": "string"
                  "enum":
                    - "mobile"
                    - "desktop"
                  "default": "mobile"
      "responses":
        "200":
          "description": "Comparison results"
        "400":
          "description": "Invalid request"
  "/api/v1/timeline":
    "get":
      "summary": "Public Analysis Timeline"
      "description": "Get the public timeline of all analyzed websites."
      "operationId": "getTimeline"
      "tags":
        - "Timeline"
      "parameters":
        -
          "name": "limit"
          "in": "query"
          "schema":
            "type": "integer"
            "default": 50
        -
          "name": "offset"
          "in": "query"
          "schema":
            "type": "integer"
            "default": 0
        -
          "name": "domain"
          "in": "query"
          "schema":
            "type": "string"
        -
          "name": "minScore"
          "in": "query"
          "schema":
            "type": "integer"
      "responses":
        "200":
          "description": "Timeline entries"
  "/api/v1/scoring/readability":
    "post":
      "summary": "Readability Score"
      "description": "Calculate readability metrics including Flesch-Kincaid, SMOG, Gunning Fog, and Coleman-Liau scores."
      "operationId": "getReadabilityScore"
      "tags":
        - "AI-Era Scoring"
      "requestBody":
        "required": true
        "content":
          "application/json":
            "schema":
              "type": "object"
              "required":
                - "url"
              "properties":
                "url":
                  "type": "string"
                  "format": "uri"
      "responses":
        "200":
          "description": "Readability scores"
          "content":
            "application/json":
              "schema":
                "$ref": "#/components/schemas/ReadabilityScore"
  "/api/v1/scoring/searchability":
    "post":
      "summary": "Searchability Score"
      "description": "Analyze content discoverability for search engines and AI systems."
      "operationId": "getSearchabilityScore"
      "tags":
        - "AI-Era Scoring"
      "requestBody":
        "required": true
        "content":
          "application/json":
            "schema":
              "type": "object"
              "required":
                - "url"
              "properties":
                "url":
                  "type": "string"
                  "format": "uri"
      "responses":
        "200":
          "description": "Searchability scores"
          "content":
            "application/json":
              "schema":
                "$ref": "#/components/schemas/SearchabilityScore"
  "/api/v1/scoring/answerability":
    "post":
      "summary": "Answerability Score"
      "description": "Measure content suitability for AI answer engines (ChatGPT, Perplexity, Google AI Overview)."
      "operationId": "getAnswerabilityScore"
      "tags":
        - "AI-Era Scoring"
      "requestBody":
        "required": true
        "content":
          "application/json":
            "schema":
              "type": "object"
              "required":
                - "url"
              "properties":
                "url":
                  "type": "string"
                  "format": "uri"
      "responses":
        "200":
          "description": "Answerability scores"
          "content":
            "application/json":
              "schema":
                "$ref": "#/components/schemas/AnswerabilityScore"
  "/api/v1/scoring/audience":
    "post":
      "summary": "Audience Score"
      "description": "Analyze content targeting and engagement signals for different user segments."
      "operationId": "getAudienceScore"
      "tags":
        - "AI-Era Scoring"
      "requestBody":
        "required": true
        "content":
          "application/json":
            "schema":
              "type": "object"
              "required":
                - "url"
              "properties":
                "url":
                  "type": "string"
                  "format": "uri"
      "responses":
        "200":
          "description": "Audience scores"
          "content":
            "application/json":
              "schema":
                "$ref": "#/components/schemas/AudienceScore"
  "/api/v1/llm-instructions":
    "post":
      "summary": "LLM Instructions"
      "description": "Generate comprehensive LLM-centric instruction set for website improvement."
      "operationId": "getLLMInstructions"
      "tags":
        - "AI-Era Scoring"
      "requestBody":
        "required": true
        "content":
          "application/json":
            "schema":
              "type": "object"
              "required":
                - "url"
              "properties":
                "url":
                  "type": "string"
                  "format": "uri"
      "responses":
        "200":
          "description": "LLM instruction set"
  "/api/v1/rankings":
    "get":
      "summary": "List public rankings"
      "description": "Deterministic public-safe rankings from completed analyses. Algorithm insights-ranking-2026-05-10.2."
      "operationId": "listRankings"
      "tags":
        - "Ranking"
      "parameters":
        -
          "name": "profile"
          "in": "query"
          "schema":
            "type": "string"
            "enum":
              - "default"
              - "public-web"
              - "platphorm-standard"
              - "seo-aeo-geo"
              - "agent-readiness"
              - "accessibility-first"
              - "performance-first"
              - "discovery-first"
              - "public-sector-ready"
              - "ecommerce-ready"
              - "developer-tool-ready"
              - "content-site-ready"
            "default": "default"
        -
          "name": "limit"
          "in": "query"
          "schema":
            "type": "integer"
            "default": 50
      "responses":
        "200":
          "description": "Ranking list"
  "/api/v1/rankings/{id}":
    "get":
      "summary": "Get ranking detail"
      "description": "Retrieve a ranking row by ranking ID or source analysis ID from the current public ranking window."
      "operationId": "getRanking"
      "tags":
        - "Ranking"
      "parameters":
        -
          "name": "id"
          "in": "path"
          "required": true
          "schema":
            "type": "string"
      "responses":
        "200":
          "description": "Ranking detail"
        "404":
          "description": "Ranking not found"
  "/api/v1/ranking-profiles":
    "get":
      "summary": "List ranking profiles"
      "description": "List deterministic ranking profiles and scoring weights."
      "operationId": "listRankingProfiles"
      "tags":
        - "Ranking"
      "responses":
        "200":
          "description": "Ranking profiles"
  "/api/v1/tests/registry":
    "get":
      "summary": "Get Phase 2 test registry"
      "description": "Canonical executable registry, version insights-quality-2026-05-10.2."
      "operationId": "getTestRegistry"
      "tags":
        - "Test Registry"
      "responses":
        "200":
          "description": "Test registry"
  "/api/v1/tests/{testId}":
    "get":
      "summary": "Get test definition"
      "description": "Retrieve a named, versioned quality test with deterministic evidence and remediation contract."
      "operationId": "getQualityTest"
      "tags":
        - "Test Registry"
      "parameters":
        -
          "name": "testId"
          "in": "path"
          "required": true
          "schema":
            "type": "string"
      "responses":
        "200":
          "description": "Quality test"
        "404":
          "description": "Test not found"
  "/api/v1/suites":
    "get":
      "summary": "List test suites"
      "description": "List executable suites and their test counts."
      "operationId": "listSuites"
      "tags":
        - "Test Registry"
      "responses":
        "200":
          "description": "Quality suites"
  "/api/v1/scoring/new-internet":
    "post":
      "summary": "Calculate New Internet Score"
      "description": "Explainable score across 22 Phase 2 dimensions using algorithm new-internet-score-2026-05-10.2. Requires a completed analysisId; scores are not fabricated from bare URLs."
      "operationId": "calculateNewInternetScore"
      "tags":
        - "AI-Era Scoring"
      "requestBody":
        "required": true
        "content":
          "application/json":
            "schema":
              "type": "object"
              "required":
                - "analysisId"
              "properties":
                "analysisId":
                  "type": "string"
      "responses":
        "200":
          "description": "New Internet Score"
        "400":
          "description": "analysisId required"
  "/api/v1/validate/sitemap":
    "post":
      "summary": "Validate sitemap"
      "description": "Bounded public-safe sitemap validation with no-dead-link checks over a capped sample."
      "operationId": "validateSitemap"
      "tags":
        - "Validation"
      "requestBody":
        "required": true
        "content":
          "application/json":
            "schema":
              "type": "object"
              "required":
                - "url"
              "properties":
                "url":
                  "type": "string"
                  "format": "uri"
      "responses":
        "200":
          "description": "Sitemap validation result"
  "/api/v1/validate/url":
    "post":
      "summary": "Validate public URL"
      "operationId": "validateUrl"
      "tags":
        - "Validation"
      "requestBody":
        "required": true
        "content":
          "application/json":
            "schema":
              "type": "object"
              "required":
                - "url"
              "properties":
                "url":
                  "type": "string"
                  "format": "uri"
      "responses":
        "200":
          "description": "URL validation result"
  "/api/v1/validate/routes":
    "post":
      "summary": "Validate route compliance"
      "operationId": "validateRoutes"
      "tags":
        - "Validation"
      "requestBody":
        "required": true
        "content":
          "application/json":
            "schema":
              "type": "object"
              "required":
                - "baseUrl"
              "properties":
                "baseUrl":
                  "type": "string"
                  "format": "uri"
                "routes":
                  "type": "array"
                  "items":
                    "type": "string"
      "responses":
        "200":
          "description": "Route validation result"
  "/api/v1/validate/feed":
    "post":
      "summary": "Validate RSS or Atom feed"
      "operationId": "validateFeed"
      "tags":
        - "Validation"
      "requestBody":
        "required": true
        "content":
          "application/json":
            "schema":
              "type": "object"
              "required":
                - "url"
              "properties":
                "url":
                  "type": "string"
                  "format": "uri"
      "responses":
        "200":
          "description": "Feed validation result"
  "/api/v1/validate/openapi":
    "post":
      "summary": "Validate OpenAPI"
      "operationId": "validateOpenApi"
      "tags":
        - "Validation"
      "requestBody":
        "required": true
        "content":
          "application/json":
            "schema":
              "type": "object"
              "required":
                - "url"
              "properties":
                "url":
                  "type": "string"
                  "format": "uri"
      "responses":
        "200":
          "description": "OpenAPI validation result"
  "/api/v1/validate/llms":
    "post":
      "summary": "Validate llms discovery document"
      "operationId": "validateLlms"
      "tags":
        - "Validation"
      "requestBody":
        "required": true
        "content":
          "application/json":
            "schema":
              "type": "object"
              "required":
                - "url"
              "properties":
                "url":
                  "type": "string"
                  "format": "uri"
      "responses":
        "200":
          "description": "llms validation result"
  "/api/v1/validate/mcp":
    "post":
      "summary": "Validate MCP JSON-RPC"
      "operationId": "validateMcp"
      "tags":
        - "Validation"
      "requestBody":
        "required": true
        "content":
          "application/json":
            "schema":
              "type": "object"
              "required":
                - "url"
              "properties":
                "url":
                  "type": "string"
                  "format": "uri"
      "responses":
        "200":
          "description": "MCP validation result"
  "/api/v1/validate/structured-data":
    "post":
      "summary": "Validate JSON-LD structured data"
      "operationId": "validateStructuredData"
      "tags":
        - "Validation"
      "requestBody":
        "required": true
        "content":
          "application/json":
            "schema":
              "type": "object"
              "required":
                - "url"
              "properties":
                "url":
                  "type": "string"
                  "format": "uri"
      "responses":
        "200":
          "description": "Structured-data validation result"
  "/api/v1/validate/agent-policy":
    "post":
      "summary": "Validate agent policy"
      "description": "Validate .well-known/agent-policy.json against canonical Insights agent policy insights-agent-policy-2026-05-16.1."
      "operationId": "validateAgentPolicy"
      "tags":
        - "Validation"
        - "Agent Policy"
      "requestBody":
        "required": true
        "content":
          "application/json":
            "schema":
              "type": "object"
              "required":
                - "url"
              "properties":
                "url":
                  "type": "string"
                  "format": "uri"
      "responses":
        "200":
          "description": "Agent policy validation result"
  "/api/v1/validate/robots":
    "post":
      "summary": "Validate robots.txt"
      "description": "Validate robots.txt alignment with public-safe discovery, protected path disallows, sitemap links, and agent policy pointers."
      "operationId": "validateRobots"
      "tags":
        - "Validation"
        - "Agent Policy"
      "requestBody":
        "required": true
        "content":
          "application/json":
            "schema":
              "type": "object"
              "required":
                - "url"
              "properties":
                "url":
                  "type": "string"
                  "format": "uri"
      "responses":
        "200":
          "description": "Robots validation result"
  "/api/v1/agent-policy":
    "get":
      "summary": "Get agent policy"
      "description": "Public-safe operational allow policy for AI agents, crawlers, fetchers, and MCP/API clients. Version insights-agent-policy-2026-05-16.1."
      "operationId": "getAgentPolicy"
      "tags":
        - "Agent Policy"
      "responses":
        "200":
          "description": "Agent policy document"
  "/api/v1/agent-policy/platforms":
    "get":
      "summary": "List agent platforms"
      "description": "Source-labeled common agent platform registry. Version insights-agent-platforms-2026-05-16.1."
      "operationId": "listAgentPlatforms"
      "tags":
        - "Agent Policy"
      "responses":
        "200":
          "description": "Agent platform registry"
  "/api/v1/agent-policy/platforms/{id}":
    "get":
      "summary": "Get agent platform"
      "description": "Return one source-labeled platform policy entry by ID."
      "operationId": "getAgentPlatform"
      "tags":
        - "Agent Policy"
      "parameters":
        -
          "name": "id"
          "in": "path"
          "required": true
          "schema":
            "type": "string"
      "responses":
        "200":
          "description": "Agent platform entry"
        "404":
          "description": "Agent platform not found"
  "/api/v1/agent-policy/robots":
    "get":
      "summary": "Get robots policy"
      "description": "Return generated robots.txt text and policy validation."
      "operationId": "getRobotsPolicy"
      "tags":
        - "Agent Policy"
      "responses":
        "200":
          "description": "Robots policy text and validation"
  "/api/v1/agent-policy/summary":
    "get":
      "summary": "Get agent policy summary"
      "description": "Return public/protected route counts, discovery artifacts, platform summaries, and JA4 handling policy."
      "operationId": "getAgentPolicySummary"
      "tags":
        - "Agent Policy"
      "responses":
        "200":
          "description": "Agent policy summary"
  "/api/v1/agent-policy/evaluate":
    "post":
      "summary": "Evaluate agent access"
      "description": "Bounded public-safe evaluator for method/path/user-agent access decisions. This does not authorize protected actions."
      "operationId": "evaluateAgentAccess"
      "tags":
        - "Agent Policy"
      "requestBody":
        "required": false
        "content":
          "application/json":
            "schema":
              "type": "object"
              "properties":
                "userAgent":
                  "type": "string"
                "path":
                  "type": "string"
                "method":
                  "type": "string"
                  "default": "GET"
      "responses":
        "200":
          "description": "Access decision"
  "/api/mcp":
    "get":
      "summary": "MCP Tool Manifest"
      "description": "Get available MCP tools for AI agent integration. No API key required."
      "operationId": "getMcpManifest"
      "tags":
        - "MCP"
      "responses":
        "200":
          "description": "MCP tool manifest with public Insights tools and protected report/bulk tools"
    "post":
      "summary": "Execute MCP Tool"
      "description": "Execute an MCP tool call. Supports all analysis and scoring tools."
      "operationId": "executeMcpTool"
      "tags":
        - "MCP"
      "requestBody":
        "required": true
        "content":
          "application/json":
            "schema":
              "type": "object"
              "required":
                - "method"
                - "params"
              "properties":
                "jsonrpc":
                  "type": "string"
                  "const": "2.0"
                "method":
                  "type": "string"
                  "enum":
                    - "initialize"
                    - "ping"
                    - "tools/list"
                    - "tools/call"
                    - "resources/list"
                    - "resources/read"
                    - "prompts/list"
                    - "prompts/get"
                "params":
                  "type": "object"
                "id":
                  "type": "string"
      "responses":
        "200":
          "description": "Tool execution result"
  "/api/v1/health":
    "get":
      "summary": "Health Check v1"
      "description": "Public-safe health summary using the standard PlatPhorm health shape."
      "operationId": "healthCheckV1"
      "tags":
        - "System"
      "responses":
        "200":
          "description": "System health or honest degraded state"
  "/openapi.yaml":
    "get":
      "summary": "OpenAPI YAML"
      "description": "YAML representation of this OpenAPI document."
      "operationId": "getOpenApiYaml"
      "tags":
        - "Discovery"
      "responses":
        "200":
          "description": "OpenAPI YAML"
  "/openapi.json":
    "get":
      "summary": "OpenAPI JSON"
      "description": "JSON representation of this OpenAPI document."
      "operationId": "getOpenApiJson"
      "tags":
        - "Discovery"
      "responses":
        "200":
          "description": "OpenAPI JSON"
  "/api/health":
    "get":
      "summary": "Health Check"
      "description": "Check API and database health status."
      "operationId": "healthCheck"
      "tags":
        - "System"
      "responses":
        "200":
          "description": "System is healthy"
        "503":
          "description": "System is unhealthy"
  "/llms.txt":
    "get":
      "summary": "LLMs.txt"
      "description": "Machine-readable discovery document for AI systems."
      "operationId": "getLlmsTxt"
      "tags":
        - "Discovery"
      "responses":
        "200":
          "description": "LLMs.txt content"
  "/humans.txt":
    "get":
      "summary": "Humans.txt"
      "description": "Public human attribution, maintainer, policy, testing, and technology disclosure for Insights."
      "operationId": "getHumansTxt"
      "tags":
        - "Discovery"
      "responses":
        "200":
          "description": "humans.txt content"
  "/robots.txt":
    "get":
      "summary": "Robots.txt"
      "description": "Public robots policy aligned with .well-known/agent-policy.json."
      "operationId": "getRobotsTxt"
      "tags":
        - "Discovery"
        - "Agent Policy"
      "responses":
        "200":
          "description": "robots.txt"
  "/.well-known/agents.json":
    "get":
      "summary": "Agents manifest"
      "description": "Machine-readable agent interaction manifest for Insights."
      "operationId": "getAgentsJson"
      "tags":
        - "Discovery"
        - "Agent Policy"
      "responses":
        "200":
          "description": "agents.json"
  "/.well-known/agent-policy.json":
    "get":
      "summary": "Agent policy"
      "description": "Operational allow policy for AI agents, crawlers, fetchers, MCP clients, and API clients."
      "operationId": "getAgentPolicyWellKnown"
      "tags":
        - "Discovery"
        - "Agent Policy"
      "responses":
        "200":
          "description": "agent-policy.json"
  "/.well-known/ai-policy.json":
    "get":
      "summary": "AI content-use policy"
      "description": "Public AI training, search, answer, citation, caching, freshness, and protected-action policy."
      "operationId": "getAiPolicyWellKnown"
      "tags":
        - "Discovery"
        - "Agent Policy"
      "responses":
        "200":
          "description": "ai-policy.json"
  "/.well-known/humans.txt":
    "get":
      "summary": "Well-known humans.txt"
      "description": "Alternate well-known humans.txt route for attribution and maintainer discovery."
      "operationId": "getWellKnownHumansTxt"
      "tags":
        - "Discovery"
      "responses":
        "200":
          "description": ".well-known humans.txt content"
  "/.well-known/trust.json":
    "get":
      "summary": "Trust policy"
      "description": "Trust, trace, Vercel metadata, JA4 digest, discovery, and public/protected policy."
      "operationId": "getTrustPolicy"
      "tags":
        - "Discovery"
        - "Agent Policy"
      "responses":
        "200":
          "description": "trust.json"
"components":
  "securitySchemes":
    "PlatPhormBearer":
      "type": "http"
      "scheme": "bearer"
      "description": "Protected actions accept Authorization: Bearer $PLATPHORM_API_KEY."
    "PlatPhormApiKey":
      "type": "apiKey"
      "in": "header"
      "name": "X-PlatPhorm-API-Key"
      "description": "Protected actions accept X-PlatPhorm-API-Key: $PLATPHORM_API_KEY."
  "schemas":
    "AnalysisResponse":
      "type": "object"
      "properties":
        "success":
          "type": "boolean"
        "data":
          "type": "object"
          "properties":
            "id":
              "type": "string"
            "url":
              "type": "string"
            "strategy":
              "type": "string"
            "scores":
              "$ref": "#/components/schemas/LighthouseScores"
            "coreWebVitals":
              "$ref": "#/components/schemas/CoreWebVitals"
            "advancedScores":
              "$ref": "#/components/schemas/AdvancedScores"
            "aiRecommendations":
              "type": "array"
              "items":
                "$ref": "#/components/schemas/Recommendation"
            "carbonFootprint":
              "type": "object"
            "securityHeaders":
              "type": "object"
            "ietfStandardsReport":
              "$ref": "#/components/schemas/IetfStandardsReport"
        "meta":
          "type": "object"
          "properties":
            "requestId":
              "type": "string"
            "duration":
              "type": "number"
    "LighthouseScores":
      "type": "object"
      "properties":
        "performance":
          "type": "integer"
          "minimum": 0
          "maximum": 100
        "accessibility":
          "type": "integer"
          "minimum": 0
          "maximum": 100
        "seo":
          "type": "integer"
          "minimum": 0
          "maximum": 100
        "bestPractices":
          "type": "integer"
          "minimum": 0
          "maximum": 100
    "CoreWebVitals":
      "type": "object"
      "properties":
        "lcp":
          "$ref": "#/components/schemas/MetricValue"
        "inp":
          "$ref": "#/components/schemas/MetricValue"
        "cls":
          "$ref": "#/components/schemas/MetricValue"
        "fcp":
          "$ref": "#/components/schemas/MetricValue"
        "ttfb":
          "$ref": "#/components/schemas/MetricValue"
    "MetricValue":
      "type": "object"
      "properties":
        "value":
          "type": "number"
        "rating":
          "type": "string"
          "enum":
            - "good"
            - "needs-improvement"
            - "poor"
        "unit":
          "type": "string"
    "AdvancedScores":
      "type": "object"
      "properties":
        "readability":
          "$ref": "#/components/schemas/ReadabilityScore"
        "searchability":
          "$ref": "#/components/schemas/SearchabilityScore"
        "answerability":
          "$ref": "#/components/schemas/AnswerabilityScore"
        "audience":
          "$ref": "#/components/schemas/AudienceScore"
        "llmInstructions":
          "type": "object"
    "ReadabilityScore":
      "type": "object"
      "properties":
        "overall":
          "type": "integer"
          "minimum": 0
          "maximum": 100
        "fleschKincaid":
          "type": "number"
        "smogIndex":
          "type": "number"
        "gunningFog":
          "type": "number"
        "colemanLiau":
          "type": "number"
        "avgSentenceLength":
          "type": "number"
        "avgSyllablesPerWord":
          "type": "number"
    "SearchabilityScore":
      "type": "object"
      "properties":
        "overall":
          "type": "integer"
          "minimum": 0
          "maximum": 100
        "metaScore":
          "type": "integer"
        "structuredDataScore":
          "type": "integer"
        "semanticScore":
          "type": "integer"
        "linkingScore":
          "type": "integer"
    "AnswerabilityScore":
      "type": "object"
      "properties":
        "overall":
          "type": "integer"
          "minimum": 0
          "maximum": 100
        "questionCoverage":
          "type": "integer"
        "contentClarity":
          "type": "integer"
        "citabilityScore":
          "type": "integer"
        "structureScore":
          "type": "integer"
    "AudienceScore":
      "type": "object"
      "properties":
        "overall":
          "type": "integer"
          "minimum": 0
          "maximum": 100
        "expertiseLevel":
          "type": "string"
          "enum":
            - "beginner"
            - "intermediate"
            - "advanced"
            - "expert"
        "engagementSignals":
          "type": "integer"
        "accessibilityScore":
          "type": "integer"
    "Recommendation":
      "type": "object"
      "properties":
        "title":
          "type": "string"
        "description":
          "type": "string"
        "priority":
          "type": "string"
          "enum":
            - "critical"
            - "high"
            - "medium"
            - "low"
        "impact":
          "type": "string"
        "effort":
          "type": "string"
        "category":
          "type": "string"
    "IetfStandardsReport":
      "type": "object"
      "properties":
        "summary":
          "type": "object"
        "standards":
          "type": "array"
          "items":
            "type": "object"
        "rfcs":
          "type": "array"
          "items":
            "type": "object"
        "requirements":
          "type": "array"
          "items":
            "type": "object"
        "applicability":
          "type": "array"
          "items":
            "type": "object"
        "results":
          "type": "array"
          "items":
            "type": "object"
        "manualReviewItems":
          "type": "array"
          "items":
            "type": "object"
        "labReviewItems":
          "type": "array"
          "items":
            "type": "object"
        "coverageGaps":
          "type": "array"
          "items":
            "type": "object"
        "conformanceCaveat":
          "type": "string"
        "registryVersion":
          "type": "string"
        "sourceUrl":
          "type": "string"
        "generatedAt":
          "type": "string"
          "format": "date-time"
"tags":
  -
    "name": "Analysis"
    "description": "Performance analysis endpoints"
  -
    "name": "Comparison"
    "description": "URL comparison endpoints"
  -
    "name": "AI-Era Scoring"
    "description": "Advanced scoring for SEO, AEO, and GEO optimization"
  -
    "name": "Timeline"
    "description": "Public analysis timeline"
  -
    "name": "Ranking"
    "description": "Deterministic Phase 2 ranking endpoints"
  -
    "name": "Test Registry"
    "description": "Versioned quality test registry endpoints"
  -
    "name": "Validation"
    "description": "Route and discovery validation endpoints"
  -
    "name": "Agent Policy"
    "description": "Agent, crawler, AI policy, robots, and public/protected access endpoints"
  -
    "name": "MCP"
    "description": "Model Context Protocol integration - no API key required"
  -
    "name": "Discovery"
    "description": "Machine-readable discovery endpoints"
  -
    "name": "System"
    "description": "System and health endpoints"