{
  "openapi": "3.1.0",
  "info": {
    "title": "BuyMeGift Public API",
    "version": "1.0.0",
    "description": "Public read-only API endpoints exposed by BuyMeGift for catalog discovery, site metrics, and service health."
  },
  "servers": [
    {
      "url": "https://api.buymegift.com",
      "description": "Production"
    }
  ],
  "paths": {
    "/v1/healthz": {
      "get": {
        "operationId": "getHealth",
        "summary": "Health check",
        "description": "Returns a minimal service health payload for the public BuyMeGift API.",
        "responses": {
          "200": {
            "description": "Service is reachable",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["success", "status", "service", "time"],
                  "properties": {
                    "success": { "type": "boolean" },
                    "status": { "type": "string" },
                    "service": { "type": "string" },
                    "time": { "type": "string", "format": "date-time" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/catalog/products": {
      "get": {
        "operationId": "listCatalogProducts",
        "summary": "List catalog products",
        "description": "Returns public catalog products with paging and filter parameters.",
        "parameters": [
          { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } },
          { "name": "page_size", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 80 } },
          { "name": "category", "in": "query", "schema": { "type": "string" } },
          { "name": "store", "in": "query", "schema": { "type": "string" } },
          { "name": "sort", "in": "query", "schema": { "type": "string", "enum": ["trending", "price-asc", "price-desc", "newest", "sale"] } },
          { "name": "search", "in": "query", "schema": { "type": "string" } },
          { "name": "on_sale", "in": "query", "schema": { "type": "boolean" } },
          { "name": "brand", "in": "query", "schema": { "type": "string" } },
          { "name": "colour", "in": "query", "schema": { "type": "string" } },
          { "name": "gender", "in": "query", "schema": { "type": "string" } },
          { "name": "size", "in": "query", "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "Catalog page returned successfully"
          }
        }
      }
    },
    "/v1/catalog/filters": {
      "get": {
        "operationId": "getCatalogFilters",
        "summary": "List catalog filters",
        "description": "Returns public catalog filter buckets derived from the current product set.",
        "responses": {
          "200": {
            "description": "Filter metadata returned successfully"
          }
        }
      }
    },
    "/v1/site-metrics": {
      "get": {
        "operationId": "getSiteMetrics",
        "summary": "Get public site metrics",
        "description": "Returns public aggregate site metrics such as product counts and supported storefront totals.",
        "responses": {
          "200": {
            "description": "Metrics returned successfully"
          }
        }
      }
    }
  }
}