{
  "openapi": "3.0.3",
  "info": {
    "title": "Score for AI - AI Readiness Scanner API",
    "description": "API for scanning websites and retrieving AI readiness scores. Analyzes 48 checks across 5 categories to measure how well AI agents can read, understand, and recommend your website.",
    "version": "1.0.0",
    "contact": {
      "name": "Score for AI",
      "url": "https://scoreforai.com",
      "email": "hello@scoreforai.com"
    },
    "license": {
      "name": "Proprietary"
    }
  },
  "servers": [
    {
      "url": "https://scoreforai.com/api",
      "description": "Production API"
    }
  ],
  "paths": {
    "/scan": {
      "post": {
        "summary": "Start a new AI readiness scan",
        "description": "Submit a URL to scan for AI readiness. Returns a scan ID that can be used to poll for results.",
        "operationId": "startScan",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["url"],
                "properties": {
                  "url": {
                    "type": "string",
                    "format": "uri",
                    "description": "The website URL to scan",
                    "example": "https://example.com"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Scan started successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ScanResult"
                }
              }
            }
          },
          "400": {
            "description": "Invalid URL provided"
          },
          "429": {
            "description": "Rate limit exceeded"
          }
        }
      }
    },
    "/scan/{id}": {
      "get": {
        "summary": "Get scan results",
        "description": "Retrieve the results of a previously started scan by its ID.",
        "operationId": "getScanResult",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The scan ID returned from the POST /scan endpoint"
          }
        ],
        "responses": {
          "200": {
            "description": "Scan results",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ScanResult"
                }
              }
            }
          },
          "404": {
            "description": "Scan not found"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ScanResult": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique scan identifier"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "The scanned URL"
          },
          "score": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100,
            "description": "Overall AI readiness score (0-100)"
          },
          "categories": {
            "type": "object",
            "properties": {
              "access": {
                "$ref": "#/components/schemas/CategoryScore"
              },
              "readability": {
                "$ref": "#/components/schemas/CategoryScore"
              },
              "identity": {
                "$ref": "#/components/schemas/CategoryScore"
              },
              "integration": {
                "$ref": "#/components/schemas/CategoryScore"
              },
              "answerability": {
                "$ref": "#/components/schemas/CategoryScore"
              }
            }
          },
          "status": {
            "type": "string",
            "enum": ["pending", "scanning", "complete", "error"],
            "description": "Current scan status"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "CategoryScore": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Category name"
          },
          "score": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100,
            "description": "Category score (0-100)"
          },
          "checks": {
            "type": "integer",
            "description": "Number of checks in this category"
          },
          "passed": {
            "type": "integer",
            "description": "Number of passed checks"
          }
        }
      }
    }
  }
}