{
  "openapi": "3.1.0",
  "info": {
    "title": "AIO.GEO Public Protocol API",
    "version": "0.3.3",
    "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)"
    }
  ],
  "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/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/wall": {
      "get": {
        "tags": [
          "audit"
        ],
        "operationId": "firstHtmlWall",
        "summary": "List First HTML opted-in pins",
        "description": "Newest-first public wall. Opt-in pins only. Never dumps every audit. Structural readiness receipts, not LLM rankings.",
        "responses": {
          "200": {
            "description": "Pinned receipts",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": { "type": "boolean" },
                    "pins": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/FirstHtmlPin" }
                    },
                    "refusal": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "audit"
        ],
        "operationId": "pinFirstHtmlReceipt",
        "summary": "Opt in to pin a just-run receipt",
        "description": "Fail closed unless a successful public audit for this domain and score exists in the recent window. Optional sanitized note. No email required.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["domain", "overallScore"],
                "properties": {
                  "domain": { "type": "string", "example": "example.com" },
                  "overallScore": { "type": "number", "example": 72 },
                  "note": { "type": "string", "maxLength": 140 }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Pinned receipt"
          },
          "400": {
            "description": "No eligible just-run audit"
          },
          "429": {
            "description": "Rate limited"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-AIO-GEO-Key",
        "description": "Optional ag_live_* key for higher rate limits"
      }
    },
    "schemas": {
      "AuditResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "domain": {
            "type": "string"
          },
          "overallScore": {
            "type": "number"
          },
          "methodology": {
            "type": "string"
          },
          "pillars": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Pillar"
            }
          },
          "recommendations": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "briefUrl": {
            "type": "string"
          },
          "cli": {
            "type": "string"
          },
          "refusal": {
            "type": "string"
          },
          "error": {
            "type": "string"
          }
        }
      },
      "Pillar": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "score": {
            "type": "number"
          },
          "summary": {
            "type": "string"
          }
        }
      },
      "BriefResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "brief": {
            "type": "object",
            "additionalProperties": true
          },
          "error": {
            "type": "string"
          }
        }
      },
      "FirstHtmlPin": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "domain": { "type": "string" },
          "createdAt": { "type": "string", "format": "date-time" },
          "overallScore": { "type": "number" },
          "methodology": { "type": "string" },
          "briefUrl": { "type": "string" },
          "note": { "type": ["string", "null"] }
        }
      }
    }
  }
}
