{
  "openapi": "3.1.0",
  "info": {
    "title": "AI Visibility Evidence Audit API",
    "version": "1.1.0",
    "description": "Evidence-first, reproducible checks of public web visibility signals for a brand or organization.",
    "x-guidance": "For a no-cost preview, call POST /api/visibility-audit. For the complete premium route, call POST /api/visibility-audit-premium with the same JSON body. If the premium route returns HTTP 402, decode the payment-required header, sign the exact Base USDC requirement with an x402-compatible client, and retry with PAYMENT-SIGNATURE.",
    "license": {
      "name": "CC BY 4.0"
    }
  },
  "servers": [
    {
      "url": "https://ai-visibility-field-notes.joseopazosuazo.chatgpt.site"
    }
  ],
  "tags": [
    {
      "name": "AI visibility",
      "description": "Reproducible evidence checks for public web presence."
    }
  ],
  "paths": {
    "/api/visibility-audit": {
      "post": {
        "operationId": "runFreeVisibilityAudit",
        "summary": "Run a free visibility audit",
        "description": "Checks a public URL for reproducible visibility signals and returns a JSON score with evidence and issues.",
        "tags": ["AI visibility"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AuditRequest"
              },
              "example": {
                "url": "https://example.com"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Evidence-first audit result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuditResult"
                }
              }
            }
          },
          "400": {
            "description": "Invalid or unsafe URL."
          }
        }
      }
    },
    "/api/visibility-audit-premium": {
      "post": {
        "operationId": "runPremiumVisibilityAudit",
        "summary": "Run a premium visibility audit",
        "description": "The paid, high-value version of the audit. It uses x402 exact USDC-compatible settlement on Base mainnet and does not require an account or API key.",
        "tags": ["AI visibility"],
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "19.00"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AuditRequest"
              },
              "example": {
                "url": "https://example.com"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Premium evidence-first audit result after successful settlement.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuditResult"
                }
              }
            },
            "headers": {
              "PAYMENT-RESPONSE": {
                "description": "Base64-encoded x402 settlement confirmation.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "402": {
            "description": "Payment Required. Decode the payment-required header, sign its exact requirement, and retry with PAYMENT-SIGNATURE.",
            "headers": {
              "PAYMENT-REQUIRED": {
                "description": "Base64-encoded x402 v2 payment requirements.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "503": {
            "description": "Facilitator unavailable; settlement was not confirmed."
          }
        }
      },
      "options": {
        "operationId": "describePremiumVisibilityAudit",
        "summary": "Describe premium payment requirements",
        "responses": {
          "200": {
            "description": "Service and payment description."
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "AuditRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": ["url"],
        "properties": {
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Public HTTP or HTTPS URL to inspect. Private-network targets are rejected.",
            "example": "https://example.com"
          }
        }
      },
      "AuditResult": {
        "type": "object",
        "description": "Deterministic audit result containing score, evidence, and issues.",
        "properties": {
          "url": {
            "type": "string",
            "format": "uri"
          },
          "score": {
            "type": "number",
            "minimum": 0,
            "maximum": 100
          },
          "evidence": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "issues": {
            "type": "array",
            "items": {
              "type": "object"
            }
          }
        },
        "required": ["url", "score", "evidence", "issues"]
      }
    }
  }
}