{
  "openapi": "3.1.0",
  "info": {
    "title": "SitePulsar API",
    "description": "Agent Readiness audit platform — score how AI engines and autonomous agents find, read, and act on your brand across ChatGPT, Claude, Gemini, Perplexity, and Grok. The API allows authenticated users to start audits, check status, and retrieve results programmatically.",
    "version": "1.0.0",
    "contact": {
      "name": "SitePulsar Support",
      "url": "https://www.sitepulsar.ai/contact"
    },
    "termsOfService": "https://www.sitepulsar.ai/terms"
  },
  "servers": [
    {
      "url": "https://www.sitepulsar.ai",
      "description": "Production"
    }
  ],
  "security": [
    { "bearerAuth": [] },
    { "cookieAuth": [] }
  ],
  "paths": {
    "/api/audit/start": {
      "post": {
        "summary": "Start a new audit",
        "description": "Initiates an AEO (Agent Experience Optimization) audit — formerly GEO + AIO — for a given website URL and brand name. Requires authentication and at least 1 credit. The audit runs asynchronously — use the status endpoint to poll for completion.",
        "operationId": "startAudit",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AuditInput"
              },
              "example": {
                "url": "https://example.com",
                "brandName": "Example Corp"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Audit started successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuditStarted"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Not authenticated"
          },
          "402": {
            "description": "Insufficient credits"
          }
        }
      }
    },
    "/api/audit/status/{id}": {
      "get": {
        "summary": "Check audit status",
        "description": "Returns the current status of an audit. Poll this endpoint until status is 'completed' or 'failed'.",
        "operationId": "getAuditStatus",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Audit ID returned from the start endpoint"
          }
        ],
        "responses": {
          "200": {
            "description": "Audit status",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuditStatus"
                }
              }
            }
          },
          "401": {
            "description": "Not authenticated"
          },
          "404": {
            "description": "Audit not found"
          }
        }
      }
    },
    "/api/audit/result/{id}": {
      "get": {
        "summary": "Get audit results",
        "description": "Returns the full audit report including the AEO score (overall + FIND/READ/USE pillars, exposed in the response as geo_score + aio_score for backward compatibility), reputation data, competitor analysis, and action plan. Only available after the audit status is 'completed'.",
        "operationId": "getAuditResult",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Audit ID"
          }
        ],
        "responses": {
          "200": {
            "description": "Full audit results",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuditResult"
                }
              }
            }
          },
          "401": {
            "description": "Not authenticated"
          },
          "404": {
            "description": "Audit not found"
          }
        }
      }
    },
    "/api/audit/pdf/{id}": {
      "get": {
        "summary": "Download audit PDF report",
        "description": "Generates and returns a downloadable PDF report for a completed audit.",
        "operationId": "getAuditPdf",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Audit ID"
          }
        ],
        "responses": {
          "200": {
            "description": "PDF report",
            "content": {
              "application/pdf": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "401": {
            "description": "Not authenticated"
          },
          "404": {
            "description": "Audit not found"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "API key from your SitePulsar dashboard (/api-keys). Format: `Authorization: Bearer sp_live_<key>`"
      },
      "cookieAuth": {
        "type": "apiKey",
        "in": "cookie",
        "name": "sb-access-token",
        "description": "Supabase session cookie. Authenticate via the web app at /login."
      }
    },
    "schemas": {
      "AuditInput": {
        "type": "object",
        "required": ["url", "brandName"],
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Website URL to audit",
            "example": "https://example.com"
          },
          "brandName": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100,
            "description": "Brand or company name",
            "example": "Example Corp"
          }
        }
      },
      "AuditStarted": {
        "type": "object",
        "properties": {
          "auditId": {
            "type": "string",
            "format": "uuid",
            "description": "Unique audit identifier for polling status and retrieving results"
          }
        }
      },
      "AuditStatus": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "status": {
            "type": "string",
            "enum": ["processing", "completed", "failed"],
            "description": "Current audit status"
          },
          "geo_score": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100,
            "nullable": true,
            "description": "Overall GEO score (available when completed)"
          },
          "aio_score": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100,
            "nullable": true,
            "description": "Overall AIO score (available when completed)"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "AuditResult": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "audit_id": {
            "type": "string",
            "format": "uuid",
            "description": "Alias of id"
          },
          "geo_score": {
            "type": "object",
            "description": "GEO score breakdown",
            "properties": {
              "overall": { "type": "integer", "minimum": 0, "maximum": 100 },
              "schemaMarkup": { "type": "integer", "minimum": 0, "maximum": 100 },
              "brandAuthority": { "type": "integer", "minimum": 0, "maximum": 100 },
              "contentStructure": { "type": "integer", "minimum": 0, "maximum": 100 },
              "aiVisibility": { "type": "integer", "minimum": 0, "maximum": 100 },
              "competitivePosition": { "type": "integer", "minimum": 0, "maximum": 100 }
            }
          },
          "action_plan": {
            "type": "array",
            "description": "Prioritized list of recommendations",
            "items": {
              "type": "object",
              "properties": {
                "priority": { "type": "string", "enum": ["critical", "high", "medium", "low"] },
                "category": { "type": "string" },
                "title": { "type": "string" },
                "description": { "type": "string" },
                "estimatedImpact": { "type": "integer", "minimum": 0, "maximum": 100 }
              }
            }
          },
          "reputation_data": {
            "type": "array",
            "description": "Per-AI-engine brand mention analysis (ChatGPT, Claude, Gemini, Grok, Perplexity)",
            "items": {
              "type": "object",
              "properties": {
                "provider": { "type": "string" },
                "mentioned": { "type": "boolean" },
                "sentiment": { "type": "string" },
                "context": { "type": "string" },
                "authorityScore": { "type": "integer", "minimum": 0, "maximum": 100 },
                "recommendedAs": { "type": "array", "items": { "type": "string" } }
              }
            }
          },
          "competitor_data": {
            "type": "array",
            "description": "Competitor share-of-voice per AI engine",
            "items": {
              "type": "object",
              "properties": {
                "provider": { "type": "string" },
                "competitors": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "name": { "type": "string" },
                      "url": { "type": "string" },
                      "mentionFrequency": { "type": "integer" },
                      "strengths": { "type": "array", "items": { "type": "string" } },
                      "weaknesses": { "type": "array", "items": { "type": "string" } }
                    }
                  }
                }
              }
            }
          },
          "crawl_data": {
            "type": "object",
            "description": "Website crawl results",
            "properties": {
              "jsonLd": { "type": "array", "description": "Detected JSON-LD schema blocks" },
              "schemaTypes": { "type": "array", "items": { "type": "string" } },
              "metaTags": { "type": "array", "items": { "type": "object" } },
              "semanticHtml": { "type": "object" }
            }
          },
          "summary": {
            "type": "string",
            "description": "AI-generated executive summary of the audit"
          },
          "generated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "details": {
            "type": "array",
            "items": {
              "type": "object"
            }
          }
        }
      }
    }
  }
}