{
  "openapi": "3.1.0",
  "info": {
    "title": "FavURL Public API",
    "description": "Read-only public endpoints for discovering FavURL business landing pages. Page generation and management endpoints require authentication and are not part of this public surface.",
    "version": "1.0.0",
    "contact": {
      "name": "FavURL",
      "email": "hello@favurl.com",
      "url": "https://favurl.com"
    }
  },
  "servers": [
    { "url": "https://favurl.com", "description": "Production" }
  ],
  "paths": {
    "/api/stats": {
      "get": {
        "operationId": "getStats",
        "summary": "Total number of published landing pages",
        "responses": {
          "200": {
            "description": "Page count",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": { "count": { "type": "integer" } },
                  "required": ["count"]
                }
              }
            }
          }
        }
      }
    },
    "/api/recent": {
      "get": {
        "operationId": "getRecent",
        "summary": "Most recently published landing pages (up to 30)",
        "responses": {
          "200": {
            "description": "Recent pages",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/PageList" }
              }
            }
          }
        }
      }
    },
    "/api/popular": {
      "get": {
        "operationId": "getPopular",
        "summary": "Most-viewed landing pages (up to 5)",
        "responses": {
          "200": {
            "description": "Popular pages",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/PageList" }
              }
            }
          }
        }
      }
    },
    "/api/search": {
      "get": {
        "operationId": "searchBusinesses",
        "summary": "Search Google Places for a business to generate a page from",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "Search query (minimum 2 characters)",
            "schema": { "type": "string", "minLength": 2 }
          }
        ],
        "responses": {
          "200": {
            "description": "Matching places",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "results": { "type": "array", "items": { "type": "object" } }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Page": {
        "type": "object",
        "properties": {
          "name": { "type": "string", "description": "Business name" },
          "slug": { "type": "string", "description": "URL slug, served at https://favurl.com/{slug}" },
          "cat": { "type": "string", "description": "Business category" },
          "city": { "type": "string" },
          "photo": { "type": ["string", "null"], "description": "Proxied photo URL" }
        },
        "required": ["name", "slug"]
      },
      "PageList": {
        "type": "object",
        "properties": {
          "pages": { "type": "array", "items": { "$ref": "#/components/schemas/Page" } }
        },
        "required": ["pages"]
      }
    }
  }
}