{
  "openapi": "3.1.0",
  "info": {
    "title": "AIO.GEO Public Protocol API",
    "version": "0.3.1",
    "description": "AI Search Readiness audit, dry-run fix packs, executive briefs, and proof seals. We do not sell LLM rankings. Nobody can measure them honestly. We sell what can be measured: structure, accessibility, and receipts to prove it. Operator stack: Grok Build engineering surface; Cursor MCP (@aio-geo/mcp-server). Not an official xAI product.",
    "contact": {
      "name": "AIO.GEO Protocol",
      "url": "https://www.aiogeoprotocol.com/contact",
      "email": "aiogeoprotocol@gmail.com"
    },
    "license": {
      "name": "Proprietary product + MIT operator packages",
      "url": "https://github.com/DigitalCurrensy/aio-geo-protocol"
    }
  },
  "servers": [
    {
      "url": "https://www.aiogeoprotocol.com",
      "description": "Production (canonical www)"
    },
    {
      "url": "https://aiogeoprotocol.com",
      "description": "Apex (308 redirect to www)"
    },
    {
      "url": "http://127.0.0.1:8080",
      "description": "Local dev"
    }
  ],
  "tags": [
    {
      "name": "audit",
      "description": "Plane A structural readiness"
    },
    {
      "name": "remediation",
      "description": "Plane B dry-run fix packs"
    },
    {
      "name": "brief",
      "description": "Agency dual-engine executive brief"
    },
    {
      "name": "proof",
      "description": "Plane C HMAC seals"
    }
  ],
  "paths": {
    "/api/v1/public/audit": {
      "post": {
        "tags": [
          "audit"
        ],
        "operationId": "publicAudit",
        "summary": "Run AI Search Readiness audit",
        "description": "Structural 5-pillar readiness scan (geo-heuristic-v3.5). Not an LLM ranking. SSRF firewall enforced.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "domain"
                ],
                "properties": {
                  "domain": {
                    "type": "string",
                    "example": "example.com",
                    "description": "Public hostname or URL"
                  },
                  "mode": {
                    "type": "string",
                    "enum": [
                      "light",
                      "deep"
                    ],
                    "default": "light"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Audit result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "domain": {
                      "type": "string"
                    },
                    "overallScore": {
                      "type": "number"
                    },
                    "methodology": {
                      "type": "string"
                    },
                    "pillars": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "key": {
                            "type": "string"
                          },
                          "score": {
                            "type": "number"
                          },
                          "weight": {
                            "type": "number"
                          }
                        }
                      }
                    },
                    "recommendations": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid or blocked URL (SSRF firewall)"
          }
        }
      }
    },
    "/api/v1/public/apply": {
      "post": {
        "tags": [
          "remediation"
        ],
        "operationId": "publicApplyDryRun",
        "summary": "Generate dry-run remediation fix pack",
        "description": "Returns robots/schema/content patches. Default is dry_run=true; no live writes without explicit operator action and credentials.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "domain"
                ],
                "properties": {
                  "domain": {
                    "type": "string"
                  },
                  "dry_run": {
                    "type": "boolean",
                    "default": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Fix pack JSON"
          },
          "400": {
            "description": "Invalid domain or SSRF block"
          }
        }
      }
    },
    "/api/v1/public/brief": {
      "post": {
        "tags": [
          "brief"
        ],
        "operationId": "publicExecutiveBrief",
        "summary": "Generate dual-engine SEO + AIO executive brief",
        "description": "Runs real runGeoAudit, synthesizes traditional SERP structure score + AI Search Readiness, three plain-English fixes, optional Neon lead harvest. Not an LLM ranking product.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "domain"
                ],
                "properties": {
                  "domain": {
                    "type": "string",
                    "example": "example.com"
                  },
                  "agencyName": {
                    "type": "string",
                    "example": "Scorpion Legal Growth"
                  },
                  "industryPreset": {
                    "type": "string",
                    "enum": [
                      "legal",
                      "medical",
                      "trades",
                      "saas",
                      "ecom",
                      "general"
                    ],
                    "default": "general"
                  },
                  "leadEmail": {
                    "type": "string",
                    "format": "email"
                  },
                  "mode": {
                    "type": "string",
                    "enum": [
                      "light",
                      "deep"
                    ],
                    "default": "light"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Executive brief payload + sharePath",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "sharePath": {
                      "type": "string"
                    },
                    "brief": {
                      "type": "object",
                      "properties": {
                        "slug": {
                          "type": "string"
                        },
                        "clientDomain": {
                          "type": "string"
                        },
                        "agencyName": {
                          "type": "string"
                        },
                        "serp": {
                          "type": "object"
                        },
                        "aio": {
                          "type": "object"
                        },
                        "actions": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid domain or crawl failure"
          },
          "429": {
            "description": "Rate limited"
          }
        }
      },
      "get": {
        "tags": [
          "brief"
        ],
        "operationId": "publicBriefHelp",
        "summary": "Brief endpoint schema help",
        "responses": {
          "200": {
            "description": "Accepted body fields"
          }
        }
      }
    },
    "/api/v1/public/proof/{id}": {
      "get": {
        "tags": [
          "proof"
        ],
        "operationId": "publicProof",
        "summary": "Fetch HMAC proof seal metadata",
        "description": "Integrity of a recorded structural experiment. Not an LLM ranking product.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Proof seal",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "expId": {
                      "type": "string"
                    },
                    "valid": {
                      "type": "boolean"
                    },
                    "domain": {
                      "type": "string"
                    },
                    "att": {
                      "type": "number"
                    },
                    "methodology": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Unknown experiment id"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-AIO-GEO-Key",
        "description": "Optional ag_live_* key for higher rate limits"
      }
    }
  }
}