{
  "openapi": "3.1.0",
  "info": {
    "title": "AgentAEO API",
    "description": "AI search visibility and AEO audit API. Run audits across ChatGPT, Perplexity, Claude, and Google AI. Generate schema markup and AEO-optimized content programmatically.\n\n**Production:** Use the server URL below. Do not publish or embed raw Supabase project hostnames in public integrations; the Render API gateway is the canonical external surface.",
    "version": "1.0.0",
    "contact": {
      "name": "AgentAEO Support",
      "email": "agents@agentaeo.com",
      "url": "https://agentaeo.com/agents"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://agentaeo.com/terms"
    }
  },
  "servers": [
    {
      "url": "https://agentaeo-api.onrender.com",
      "description": "Production API gateway (canonical for external integrations)"
    }
  ],
  "security": [
    { "BearerAuth": [] },
    { "ApiKeyAuth": [] }
  ],
  "paths": {
    "/api/aeo-audit": {
      "post": {
        "operationId": "runAeoAudit",
        "summary": "Run an AEO audit",
        "description": "Starts an AEO audit job via the production gateway. Tests your URL across ChatGPT, Perplexity, Claude, and Google AI. Free tier runs 8 queries (2 per platform). Paid tier runs 40 queries (10 per platform) with full citation gap analysis and 30-day implementation blueprint. Poll GET /api/aeo-status/{auditId} until complete.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["url"],
                "properties": {
                  "url": {
                    "type": "string",
                    "format": "uri",
                    "description": "The website URL to audit",
                    "example": "https://example.com"
                  },
                  "keyword": {
                    "type": "string",
                    "description": "Primary industry keyword for query generation",
                    "example": "payment API"
                  },
                  "tier": {
                    "type": "string",
                    "enum": ["free", "paid"],
                    "default": "free",
                    "description": "Audit tier — free (8 queries) or paid (40 queries)"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Audit job queued successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "auditId": {
                      "type": "string",
                      "format": "uuid",
                      "description": "Unique audit identifier for polling"
                    },
                    "status": {
                      "type": "string",
                      "enum": ["queued", "processing"]
                    }
                  }
                }
              }
            }
          },
          "400": { "description": "Invalid request (missing URL or invalid parameters)" },
          "401": { "description": "Authentication required" },
          "429": { "description": "Rate limit exceeded" }
        }
      }
    },
    "/api/aeo-status/{auditId}": {
      "get": {
        "operationId": "checkAeoJobStatus",
        "summary": "Check audit job status",
        "description": "Poll the status of a running or completed AEO audit. Returns the current step, progress percentage, and full results when complete.",
        "parameters": [
          {
            "name": "auditId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The audit ID returned from POST /api/aeo-audit"
          }
        ],
        "responses": {
          "200": {
            "description": "Audit status and results",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "enum": ["queued", "processing", "completed", "failed"]
                    },
                    "current_step": {
                      "type": "integer",
                      "minimum": 1,
                      "maximum": 6
                    },
                    "score": {
                      "type": "number",
                      "description": "Overall AEO score (0-100), present when completed"
                    },
                    "grade": {
                      "type": "string",
                      "enum": ["A+", "A", "B+", "B", "C+", "C", "D", "F"],
                      "description": "Letter grade, present when completed"
                    },
                    "findings": {
                      "type": "object",
                      "description": "Full audit findings, present when completed"
                    },
                    "share_of_model": {
                      "type": "object",
                      "description": "Per-platform visibility breakdown"
                    },
                    "error_message": {
                      "type": "string",
                      "description": "Error details if status is failed"
                    }
                  }
                }
              }
            }
          },
          "404": { "description": "Audit not found" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Supabase JWT token from authentication"
      },
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "AgentAEO API key generated from the Developer Portal"
      }
    }
  }
}