{
  "openapi": "3.1.0",
  "info": {
    "title": "Boostermage API",
    "version": "1.0.3",
    "description": "Public REST API for MTG sealed product pricing data across UK retailers. Free and read-only. Listing links always point to Boostermage product pages; retailer and affiliate destination URLs are not exposed."
  },
  "servers": [
    { "url": "https://api.boostermage.com", "description": "Production server" }
  ],
  "paths": {
    "/api/v1/health": {
      "get": {
        "summary": "Health check",
        "operationId": "health",
        "responses": {
          "200": {
            "description": "Service health status",
            "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "db": { "type": "string" }, "timestamp": { "type": "string" } } } } }
          }
        }
      }
    },
    "/api/v1/products": {
      "get": {
        "summary": "Search products",
        "operationId": "searchProducts",
        "parameters": [
          { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Search query" },
          { "name": "set", "in": "query", "schema": { "type": "string" }, "description": "Filter by set slug" },
          { "name": "category", "in": "query", "schema": { "type": "string" }, "description": "Filter by category" },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 } }
        ],
        "responses": {
          "200": { "description": "List of products", "content": { "application/json": { "schema": { "type": "object" } } } }
        }
      }
    },
    "/api/v1/products/{id}/history": {
      "get": {
        "summary": "Price history for a product",
        "operationId": "getPriceHistory",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "retailer", "in": "query", "schema": { "type": "string" }, "description": "Filter by retailer ID" },
          { "name": "days", "in": "query", "schema": { "type": "integer", "default": 90, "maximum": 730 } }
        ],
        "responses": { "200": { "description": "Price observations" } }
      }
    },
    "/api/v1/products/{id}/history-summary": {
      "get": {
        "summary": "Compact daily price history for a product",
        "operationId": "getPriceHistorySummary",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "retailer", "in": "query", "schema": { "type": "string" }, "description": "Filter by retailer ID" },
          { "name": "days", "in": "query", "schema": { "type": "integer", "default": 90, "maximum": 730 } }
        ],
        "responses": { "200": { "description": "Daily aggregates and recorded price range" } }
      }
    },
    "/api/v1/products/{id}/best-price": {
      "get": {
        "summary": "Best price for a product",
        "operationId": "findBestPrice",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": { "200": { "description": "Best price across retailers" } }
      }
    },
    "/api/v1/products/{id}/price-range": {
      "get": {
        "summary": "Price range for a product",
        "operationId": "getPriceRange",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "days", "in": "query", "schema": { "type": "integer", "default": 365, "maximum": 730 } }
        ],
        "responses": { "200": { "description": "Lowest, highest, and average price" } }
      }
    },
    "/api/v1/products/deals/list": {
      "get": {
        "summary": "Products below average market price",
        "operationId": "findDeals",
        "parameters": [
          { "name": "min_discount", "in": "query", "schema": { "type": "number", "default": 5 }, "description": "Minimum discount percentage" },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 100 } }
        ],
        "responses": { "200": { "description": "Deals list" } }
      }
    },
    "/api/v1/products/in-stock/list": {
      "get": {
        "summary": "Products currently in stock or pre-order",
        "operationId": "findInStock",
        "parameters": [
          { "name": "availability", "in": "query", "schema": { "type": "string", "default": "in-stock,pre-order" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 30, "maximum": 100 } }
        ],
        "responses": { "200": { "description": "In-stock products" } }
      }
    },
    "/api/v1/products/by-set/{slug}": {
      "get": {
        "summary": "All products in a set",
        "operationId": "getSetProducts",
        "parameters": [
          { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 } }
        ],
        "responses": { "200": { "description": "Set products with prices" } }
      }
    },
    "/api/v1/retailers": {
      "get": {
        "summary": "List all tracked retailers",
        "operationId": "listRetailers",
        "responses": { "200": { "description": "Retailer list" } }
      }
    },
    "/api/v1/retailers/{id}/products": {
      "get": {
        "summary": "Products at a specific retailer",
        "operationId": "getRetailerProducts",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 200 } }
        ],
        "responses": { "200": { "description": "Retailer product listings" } }
      }
    },
    "/api/v1/prices/latest": {
      "get": {
        "summary": "Latest price snapshot",
        "operationId": "getLatestPrices",
        "parameters": [
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 100, "maximum": 500 } }
        ],
        "responses": { "200": { "description": "Latest prices" } }
      }
    },
    "/api/v1/prices/best": {
      "get": {
        "summary": "Best prices for all products",
        "operationId": "getBestPrices",
        "parameters": [
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 100, "maximum": 500 } }
        ],
        "responses": { "200": { "description": "Best prices" } }
      }
    },
    "/api/v1/releases/upcoming": {
      "get": {
        "summary": "Upcoming MTG releases",
        "operationId": "getUpcomingReleases",
        "parameters": [
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 50 } }
        ],
        "responses": { "200": { "description": "Upcoming releases" } }
      }
    }
  }
}