{
  "openapi": "3.1.0",
  "info": {
    "title": "aiready.tools GEO Audit API",
    "version": "3.3.0",
    "summary": "Run a GEO / AI-readiness audit of a public web page and get the full result as JSON.",
    "description": "One read-only endpoint. It fetches the given page (plus a few sampled sub-pages and robots.txt / llms.txt), runs the aiready.tools audit engine and returns scores, findings and an action plan. No API key is needed. Fair use: 10 requests per hour per IP address. Results are cached per URL for the current day; add fresh=1 to force a new analysis. The audit measures technical and content signals; it does not and cannot guarantee that AI assistants will mention or cite a site.",
    "contact": { "name": "aiready.tools", "email": "info@aiready.tools", "url": "https://aiready.tools/api-docs" },
    "termsOfService": "https://aiready.tools/terms"
  },
  "servers": [ { "url": "https://aiready.tools" } ],
  "paths": {
    "/api/audit.php": {
      "get": {
        "operationId": "runAudit",
        "summary": "Audit a web page for AI readiness (GEO)",
        "description": "Synchronous. The server stops after 90 seconds at the latest. Same URL on the same day returns the cached result with cached=true.",
        "parameters": [
          { "name": "url", "in": "query", "required": true, "description": "Absolute URL of the page to audit, including https://. URL-encode it.", "schema": { "type": "string", "format": "uri" }, "example": "https://example.com/" },
          { "name": "fresh", "in": "query", "required": false, "description": "1 = ignore today's cached result and analyse again.", "schema": { "type": "string", "enum": ["1"] } }
        ],
        "responses": {
          "200": {
            "description": "Audit result. status = done (scored), blocked (page could not be measured, e.g. bot protection or error page; no score) or partial (too many modules failed; no score).",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditResult" } } }
          },
          "400": { "description": "Missing or invalid url parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "429": { "description": "Fair-use limit reached (10 requests per hour per IP).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimited" } } } },
          "500": { "description": "Audit failed on the server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "AuditResult": {
        "type": "object",
        "required": ["status", "url"],
        "properties": {
          "status": { "type": "string", "enum": ["done", "blocked", "partial"] },
          "cached": { "type": "boolean", "description": "true if today's cached result was returned." },
          "url": { "type": "string" },
          "domain": { "type": "string" },
          "analyzed_at": { "type": "string", "format": "date-time" },
          "geo_score": { "type": ["integer", "null"], "minimum": 0, "maximum": 100, "description": "Weighted GEO score. null when the page could not be measured." },
          "verdict": { "type": ["string", "null"], "description": "Excellent (>=75), Good (>=60), Fair (>=45), Weak (>=30), Critical." },
          "summary_desc": { "type": "string" },
          "summary_desc_de": { "type": "string" },
          "not_measured": { "type": "array", "items": { "type": "string" }, "description": "Modules that could not be measured. Never read a missing score as 0." },
          "modules": {
            "type": "object",
            "description": "One object per module, each with at least score (0-100 or null) and findings. Keys: citability, crawlers, schema, llmstxt, eeat, brand, platforms, agent_pricing, agent_readiness.",
            "additionalProperties": { "type": "object" }
          },
          "action_plan": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "priority": { "type": "string" },
                "title": { "type": "string" },
                "desc": { "type": "string" },
                "why": { "type": "string" },
                "steps": { "type": "array", "items": { "type": "string" } },
                "where": { "type": "string" },
                "check": { "type": "string" },
                "effort": { "type": "string" },
                "category": { "type": "string" }
              }
            }
          },
          "site": { "type": "object" },
          "fetch": { "type": "object" },
          "meta": { "type": "object", "properties": { "version": { "type": "string" }, "duration_ms": { "type": "integer" } } }
        }
      },
      "Error": { "type": "object", "properties": { "error": { "type": "string" }, "status": { "type": "string" } } },
      "RateLimited": { "type": "object", "properties": { "error": { "type": "string" }, "status": { "type": "string", "const": "rate_limited" }, "hint": { "type": "string" }, "retry_after": { "type": "integer" } } }
    }
  }
}
