{
  "openapi": "3.1.0",
  "info": {
    "title": "MagicGEO Public API",
    "version": "1.1.0",
    "description": "Free, no-auth API to measure how readable and citable a public URL, brand or Shopify App Store listing is for AI engines (ChatGPT, Perplexity, Google AI Overviews) and classic search engines. All responses are computed from live public pages or from MagicGEO's real audit corpus — no simulated data. Per-IP daily quotas apply.",
    "contact": { "name": "MagicGEO Team", "url": "https://www.magic-geo.tech", "email": "contact@magic-geo.tech" },
    "license": { "name": "Free for non-commercial and attributed use", "url": "https://www.magic-geo.tech/terms" }
  },
  "servers": [{ "url": "https://www.magic-geo.tech", "description": "Production" }],
  "tags": [
    { "name": "GEO", "description": "Generative Engine Optimization audits" },
    { "name": "Shopify Apps", "description": "Shopify App Store listing visibility" },
    { "name": "Ops", "description": "Service health" }
  ],
  "paths": {
    "/api/health": {
      "get": {
        "tags": ["Ops"],
        "summary": "Service health",
        "operationId": "getHealth",
        "parameters": [
          { "name": "deep", "in": "query", "schema": { "type": "string", "enum": ["1"] }, "description": "Also ping each downstream endpoint." }
        ],
        "responses": {
          "200": { "description": "Healthy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" } } } },
          "503": { "description": "Degraded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" } } } }
        }
      }
    },
    "/api/geo/audit": {
      "post": {
        "tags": ["GEO"],
        "summary": "Audit a public URL (GEO score 0-100)",
        "operationId": "geoAudit",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UrlRequest" } } } },
        "responses": {
          "200": { "description": "Audit result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Audit" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/geo/recommendations": {
      "post": {
        "tags": ["GEO"],
        "summary": "Prioritized fixes for a public URL",
        "operationId": "geoRecommendations",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UrlRequest" } } } },
        "responses": {
          "200": {
            "description": "Ranked fixes with recoverable points, impact and effort",
            "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/geo/entity": {
      "post": {
        "tags": ["GEO"],
        "summary": "Trust record for a brand or domain",
        "description": "Aggregated real audit history for a domain: current score, certification, recurring issues, structured-data types and network percentile. Runs one live audit when the domain has never been audited.",
        "operationId": "geoEntityLookup",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "type": "object", "required": ["domain"], "properties": { "domain": { "type": "string", "example": "example.com" } } } } }
        },
        "responses": {
          "200": { "description": "Entity record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Entity" } } } },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/geo/stats": {
      "post": {
        "tags": ["GEO"],
        "summary": "Anonymized network-wide GEO benchmarks",
        "operationId": "geoIndustryStats",
        "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object" } } } },
        "responses": {
          "200": { "description": "Aggregate benchmarks", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/shopify-app/audit": {
      "post": {
        "tags": ["Shopify Apps"],
        "summary": "Audit a Shopify App Store listing",
        "operationId": "shopifyAppAudit",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["handle"],
                "properties": {
                  "handle": { "type": "string", "description": "App handle or full apps.shopify.com URL", "example": "klaviyo-email-marketing" },
                  "action": { "type": "string", "enum": ["audit", "report", "watch"], "default": "audit" },
                  "email": { "type": "string", "format": "email", "description": "Required when action=watch" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Listing audit", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } },
          "404": { "description": "Listing not found" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/shopify-app/badge": {
      "get": {
        "tags": ["Shopify Apps"],
        "summary": "Embeddable visibility badge",
        "operationId": "shopifyAppBadge",
        "parameters": [
          { "name": "handle", "in": "query", "required": true, "schema": { "type": "string" } },
          { "name": "format", "in": "query", "schema": { "type": "string", "enum": ["svg", "json"], "default": "svg" } }
        ],
        "responses": {
          "200": {
            "description": "SVG badge or JSON payload with the embed snippet",
            "content": {
              "image/svg+xml": { "schema": { "type": "string" } },
              "application/json": { "schema": { "type": "object", "additionalProperties": true } }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" }
        }
      }
    }
  },
  "components": {
    "responses": {
      "BadRequest": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "RateLimited": {
        "description": "Per-IP daily quota reached",
        "headers": { "Retry-After": { "schema": { "type": "string" }, "description": "Seconds until the quota resets" } },
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": { "error": { "type": "string" }, "message": { "type": "string" } }
      },
      "UrlRequest": {
        "type": "object",
        "required": ["url"],
        "properties": { "url": { "type": "string", "format": "uri", "example": "https://example.com" } }
      },
      "Audit": {
        "type": "object",
        "properties": {
          "url": { "type": "string" },
          "score": { "type": "integer", "minimum": 0, "maximum": 100 },
          "grade": { "type": "string" },
          "certified": { "type": "boolean" },
          "schemaTypes": { "type": "array", "items": { "type": "string" } },
          "checks": { "type": "array", "items": { "type": "object", "additionalProperties": true } },
          "analyzedAt": { "type": "string", "format": "date-time" }
        }
      },
      "Entity": {
        "type": "object",
        "properties": {
          "domain": { "type": "string" },
          "known": { "type": "boolean" },
          "geoScore": { "type": "integer" },
          "grade": { "type": "string" },
          "certified": { "type": "boolean" },
          "audits": { "type": "integer" },
          "bestScore": { "type": "integer" },
          "averageScore": { "type": "integer" },
          "trend": { "type": "integer", "nullable": true },
          "structuredDataTypes": { "type": "array", "items": { "type": "string" } },
          "recurringIssues": {
            "type": "array",
            "items": { "type": "object", "properties": { "check": { "type": "string" }, "occurrences": { "type": "integer" } } }
          },
          "networkAverageScore": { "type": "integer", "nullable": true },
          "networkPercentile": { "type": "integer", "nullable": true },
          "lastAuditedAt": { "type": "string", "format": "date-time" }
        }
      },
      "Health": {
        "type": "object",
        "properties": {
          "status": { "type": "string", "enum": ["ok", "degraded"] },
          "version": { "type": "string" },
          "checkedAt": { "type": "string", "format": "date-time" },
          "database": { "type": "object", "additionalProperties": true },
          "endpoints": { "type": "array", "items": { "type": "object", "additionalProperties": true } },
          "mcp": { "type": "object", "additionalProperties": true }
        }
      }
    }
  }
}