{
  "openapi": "3.1.0",
  "info": {
    "title": "AEO Engine Free AEO Report — Agent API",
    "version": "1.0.0",
    "description": "Keyless API for AI agents to run AEO Engine's free AEO visibility report (https://aeoengine.ai/aeo-report) on a user's behalf. Requires the user's real email (MX-validated, no disposable domains) — the finished report is emailed there and returned as JSON with a shareable URL. No API key, no captcha. Rate limits: 3/hour per IP, 1/24h per email, 1/24h per target domain (repeats return the cached report), and a global daily cap. Reports take up to ~10 minutes; poll the status endpoint every 30 seconds. OpenAPI spec: https://aeoengine.ai/.well-known/aeo-report-openapi.json",
    "contact": { "name": "AEO Engine", "url": "https://aeoengine.ai", "email": "team@aeoengine.ai" }
  },
  "servers": [{ "url": "https://ikvmveescayhdcwbnslb.supabase.co/functions/v1" }],
  "paths": {
    "/aeo-report-agent": {
      "post": {
        "summary": "Request a free AEO report for a domain",
        "operationId": "runAeoReport",
        "description": "Starts an AEO visibility report (ChatGPT, Perplexity, Gemini, Claude coverage, competitor gaps, prioritized fixes). Responds 202 with a job to poll, or 200 with a cached report if this domain was run in the last 24h. The 'company' field is a honeypot — agents must never fill it.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["domain", "email"],
                "properties": {
                  "domain": { "type": "string", "description": "Registrable domain or full URL to audit, e.g. example.com" },
                  "email": { "type": "string", "description": "The user's work email. Must be a real mailbox (MX-validated; disposable domains are rejected with 422). The report is emailed here." },
                  "competitor": { "type": "string", "description": "Optional competitor domain to compare against." },
                  "company": { "type": "string", "description": "Honeypot. Always omit." }
                }
              },
              "example": { "domain": "example.com", "email": "user@example.com" }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Report queued",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "job_id": { "type": "string" },
                    "status_url": { "type": "string" },
                    "poll_interval_seconds": { "type": "integer", "example": 30 },
                    "expected_duration_minutes": { "type": "integer", "example": 10 }
                  }
                }
              }
            }
          },
          "200": { "description": "Cached report from the last 24h — same shape as a completed status response, plus cached: true" },
          "400": { "description": "bad_request — body must be a JSON object" },
          "422": { "description": "invalid_email or invalid_domain — see reason" },
          "429": { "description": "Rate limit exceeded (ip/email/domain). Retry-After header set." },
          "503": { "description": "daily_cap or service_unavailable" }
        }
      },
      "options": { "summary": "CORS preflight", "responses": { "204": { "description": "CORS headers" } } }
    },
    "/aeo-report-agent/status": {
      "get": {
        "summary": "Poll report status",
        "operationId": "getAeoReportStatus",
        "parameters": [{ "name": "job_id", "in": "query", "required": true, "schema": { "type": "string" } }],
        "responses": {
          "200": {
            "description": "Job status; when complete, includes the structured report, shareable report_url, and a markdown_summary the agent can read to the user",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": { "type": "string", "enum": ["queued", "running", "complete", "failed"] },
                    "job_id": { "type": "string" },
                    "report": {
                      "type": "object",
                      "properties": {
                        "visibility_score": { "type": "number" },
                        "engines": { "type": "object" },
                        "scores": { "type": "object" },
                        "top_opportunities": { "type": "array", "items": { "type": "string" } }
                      }
                    },
                    "report_url": { "type": "string", "description": "Public shareable report URL" },
                    "markdown_summary": { "type": "string" }
                  }
                }
              }
            }
          },
          "404": { "description": "not_found — unknown job_id" }
        }
      }
    }
  }
}