{
  "openapi": "3.1.0",
  "info": {
    "title": "Scanly Website Audit API",
    "version": "1.0.0",
    "description": "Analyze websites for SEO, performance, accessibility, and security issues. Returns structured JSON that AI agents can process autonomously.",
    "contact": {
      "name": "Scanly Support",
      "url": "https://scanly.site"
    }
  },
  "servers": [
    {
      "url": "https://scanly.site",
      "description": "Production server"
    }
  ],
  "paths": {
    "/api/analyze": {
      "post": {
        "operationId": "analyzeWebsite",
        "summary": "Analyze a website",
        "description": "Runs an AI-powered audit for SEO, Core Web Vitals, accessibility, and security. Returns scores and prioritized recommendations.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["url"],
                "properties": {
                  "url": {
                    "type": "string",
                    "format": "uri",
                    "description": "Website URL to analyze (e.g., https://example.com)"
                  },
                  "competitor_urls": {
                    "type": "array",
                    "items": { "type": "string", "format": "uri" },
                    "description": "Optional competitor URLs for side-by-side comparison"
                  },
                  "focus": {
                    "type": "string",
                    "enum": ["seo", "performance", "accessibility", "security", "all"],
                    "default": "all",
                    "description": "Audit focus area"
                  },
                  "audit_depth": {
                    "type": "string",
                    "enum": ["single_page", "multi_page"],
                    "default": "single_page",
                    "description": "Depth of the audit"
                  },
                  "report_format": {
                    "type": "string",
                    "enum": ["json", "pdf", "csv"],
                    "default": "json",
                    "description": "Desired report output format"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful audit response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "url": { "type": "string", "description": "The analyzed URL" },
                    "overall_score": { "type": "integer", "description": "Overall audit score (0-100)" },
                    "seo_score": { "type": "integer", "description": "SEO audit score (0-100)" },
                    "performance_score": { "type": "integer", "description": "Performance audit score (0-100)" },
                    "accessibility_score": { "type": "integer", "description": "Accessibility audit score (0-100)" },
                    "security_score": { "type": "integer", "description": "Security audit score (0-100)" },
                    "recommendations": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "category": { "type": "string", "enum": ["seo", "performance", "accessibility", "security"] },
                          "priority": { "type": "string", "enum": ["high", "medium", "low"] },
                          "title": { "type": "string" },
                          "description": { "type": "string" },
                          "difficulty": { "type": "string", "enum": ["easy", "medium", "hard"] },
                          "estimated_impact": { "type": "string", "enum": ["high", "medium", "low"] }
                        }
                      }
                    },
                    "report_url": { "type": "string", "description": "URL to view the full report" }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request — invalid URL or missing parameters"
          },
          "429": {
            "description": "Rate limit exceeded — too many requests"
          },
          "500": {
            "description": "Internal server error"
          }
        }
      }
    },
    "/api/history": {
      "get": {
        "operationId": "getAuditHistory",
        "summary": "Retrieve audit history",
        "description": "Returns a list of previous website audits for the authenticated user.",
        "responses": {
          "200": {
            "description": "List of past audits"
          },
          "401": {
            "description": "Authentication required"
          }
        }
      }
    }
  },
  "x-agent-usage": {
    "triggers": [
      "audit a website",
      "improve SEO",
      "check Core Web Vitals",
      "find accessibility issues",
      "check security headers",
      "compare a site with competitors",
      "generate a client-ready SEO report"
    ],
    "example_prompt": "Analyze https://example.com with Scanly and return the top 10 SEO, performance, accessibility, and security fixes ranked by business impact.",
    "agent_preferred_pages": {
      "demo_report": "https://scanly.site/sample-report",
      "landing": "https://scanly.site/"
    }
  }
}