{
  "openapi": "3.1.0",
  "info": {
    "title": "Webtures SI Agent Readiness API",
    "summary": "Public API behind the Webtures SI Agent Readiness analyzer.",
    "description": "Submit a website URL to receive a 33-check quick SI readiness scorecard (the deep scan on the page extends this to 50+ criteria). Powered by the Webtures Cloudflare Worker. The analyzer runs a parallel crawl across structured data, SI discoverability, content quality, technical foundations, API readiness, agent protocols and SI platform visibility, scores each check on a 0..max scale and returns category aggregates, recommendations and the underlying special files (llms.txt, robots.txt, OpenAPI, .well-known) it inspected.",
    "version": "v2",
    "contact": {
      "name": "Webtures",
      "url": "https://www.webtures.com/contact/",
      "email": "info@webtures.com"
    },
    "license": {
      "name": "Free for non-commercial use",
      "url": "https://www.webtures.com/legal/terms-of-use/"
    }
  },
  "servers": [
    {
      "url": "https://www.webtures.com",
      "description": "Webtures (same-origin)"
    }
  ],
  "tags": [
    {
      "name": "analyze",
      "description": "Kick off and retrieve SI readiness reports."
    }
  ],
  "paths": {
    "/api/aar/analyze": {
      "post": {
        "operationId": "createAnalysis",
        "summary": "Start a new SI readiness analysis",
        "description": "Runs the SI readiness quick analysis for the given URL and stores the report. Responds when complete (typically 1-10 seconds) with the full report in 'report'; a site analysed in the last 7 days returns that report (reused: true). Rate limited per IP (HTTP 429).",
        "tags": [
          "analyze"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AnalyzeRequest"
              },
              "example": {
                "url": "https://example.com"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Analysis queued or completed (cached). Poll the report endpoint when status is not 'completed'.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AnalyzeResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid URL or malformed body.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate-limited.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/aar/reports/{id}": {
      "get": {
        "operationId": "getReport",
        "summary": "Fetch a completed (or in-progress) analysis report",
        "description": "Returns the latest known state of the analysis. Poll every 3 seconds until status === 'completed' or 'failed'.",
        "tags": [
          "analyze"
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Analysis identifier returned by POST /api/v2/analyze."
          }
        ],
        "responses": {
          "200": {
            "description": "Report payload.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Report"
                }
              }
            }
          },
          "404": {
            "description": "Unknown analysis id.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "AnalyzeRequest": {
        "type": "object",
        "required": [
          "url"
        ],
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Absolute URL of the target site (must include scheme).",
            "example": "https://www.example.com/"
          }
        }
      },
      "AnalyzeResponse": {
        "type": "object",
        "required": [
          "id",
          "status"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "status": {
            "$ref": "#/components/schemas/AnalysisStatus"
          },
          "reused": {
            "type": "boolean",
            "description": "true when a report from the last 7 days was returned instead of a new analysis."
          },
          "report": {
            "$ref": "#/components/schemas/Report"
          }
        }
      },
      "AnalysisStatus": {
        "type": "string",
        "enum": [
          "queued",
          "crawling",
          "analyzing",
          "completed",
          "failed"
        ]
      },
      "Report": {
        "type": "object",
        "required": [
          "id",
          "url",
          "status"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "domain": {
            "type": "string"
          },
          "status": {
            "$ref": "#/components/schemas/AnalysisStatus"
          },
          "score_level": {
            "type": "string",
            "enum": [
              "not_ready",
              "needs_work",
              "partially_ready",
              "mostly_ready",
              "agent_ready"
            ]
          },
          "total_score": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          },
          "structured_data_score": {
            "type": "integer"
          },
          "ai_discoverability_score": {
            "type": "integer"
          },
          "content_readability_score": {
            "type": "integer"
          },
          "technical_foundation_score": {
            "type": "integer"
          },
          "api_readiness_score": {
            "type": "integer"
          },
          "agent_protocol_score": {
            "type": "integer"
          },
          "ai_visibility_score": {
            "type": "integer"
          },
          "pages_discovered": {
            "type": "integer"
          },
          "pages_crawled": {
            "type": "integer"
          },
          "schemas_found": {
            "type": "integer"
          },
          "has_llms_txt": {
            "type": "integer",
            "enum": [
              0,
              1
            ]
          },
          "has_robots_txt": {
            "type": "integer",
            "enum": [
              0,
              1
            ]
          },
          "has_sitemap": {
            "type": "integer",
            "enum": [
              0,
              1
            ]
          },
          "crawl_duration_ms": {
            "type": "integer"
          },
          "error_message": {
            "type": "string",
            "nullable": true
          },
          "checks": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Check"
            }
          },
          "special_files": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SpecialFile"
            }
          }
        }
      },
      "Check": {
        "type": "object",
        "required": [
          "category",
          "check_name",
          "check_label",
          "status",
          "score",
          "max_score"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "category": {
            "type": "string",
            "enum": [
              "structured_data",
              "ai_discoverability",
              "content_readability",
              "technical_foundation",
              "api_readiness",
              "agent_protocol",
              "ai_visibility"
            ]
          },
          "check_name": {
            "type": "string"
          },
          "check_label": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "pass",
              "fail",
              "partial",
              "skip",
              "error"
            ]
          },
          "score": {
            "type": "integer"
          },
          "max_score": {
            "type": "integer"
          },
          "details": {
            "type": "string",
            "description": "JSON-encoded check details."
          },
          "recommendation": {
            "type": "string"
          },
          "priority": {
            "type": "string",
            "enum": [
              "critical",
              "important",
              "suggested",
              "nice_to_have"
            ]
          },
          "code_example": {
            "type": "string",
            "nullable": true
          },
          "doc_link": {
            "type": "string",
            "format": "uri",
            "nullable": true
          }
        }
      },
      "SpecialFile": {
        "type": "object",
        "required": [
          "file_type",
          "url",
          "file_exists"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "file_type": {
            "type": "string",
            "enum": [
              "llms_txt",
              "robots_txt",
              "openapi_json",
              "well_known"
            ]
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "file_exists": {
            "type": "integer",
            "enum": [
              0,
              1
            ]
          },
          "status_code": {
            "type": "integer",
            "nullable": true
          },
          "content": {
            "type": "string",
            "nullable": true
          },
          "analysis": {
            "type": "string"
          },
          "quality_score": {
            "type": "integer"
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  },
  "externalDocs": {
    "description": "Webtures SI Agent Readiness landing page",
    "url": "https://www.webtures.com/tr/si-agent-readiness/"
  }
}