{
  "openapi": "3.1.0",
  "info": {
    "title": "aireadify Agent-Readiness Scan API",
    "version": "0.1.0",
    "description": "Score any public URL on AI-agent readiness: 24 signals with evidence, per-issue fix plan (action, product layer, effort), storefront platform detection and a plan summary. Free, 10 scans per 10 minutes per IP.",
    "contact": {
      "email": "hello@aireadify.ai",
      "url": "https://aireadify.ai"
    }
  },
  "servers": [
    {
      "url": "https://aireadify.ai"
    }
  ],
  "paths": {
    "/api/scan": {
      "get": {
        "operationId": "scanAgentReadiness",
        "summary": "Scan a URL for agent readiness",
        "description": "Fetches public endpoints of the target site, runs 20 checks, and returns a graded report.",
        "parameters": [
          {
            "name": "url",
            "in": "query",
            "required": true,
            "description": "The site to scan, e.g. example.com or https://example.com",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Scan result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "url": {
                          "type": "string"
                        },
                        "final_url": {
                          "type": "string"
                        },
                        "total_score": {
                          "type": "integer",
                          "minimum": 0,
                          "maximum": 100
                        },
                        "grade": {
                          "type": "string",
                          "enum": [
                            "A+",
                            "A",
                            "B",
                            "C",
                            "D",
                            "F"
                          ]
                        },
                        "categories": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        },
                        "checks": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        },
                        "extras": {
                          "type": "object"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid url, or blocked host"
          },
          "429": {
            "description": "Rate limited (max 10 scans / 10 min / IP)"
          }
        }
      }
    }
  }
}