{
  "openapi": "3.1.0",
  "info": {
    "title": "Lumea Blooms Public Catalog API",
    "version": "1.0.0",
    "description": "Read-only JSON API for published catalog data. Intended for storefront integrations and AI agents. Responses include `X-API-Version: 1`. List/search endpoints return `{ data, pagination }`; product detail returns `{ data }`."
  },
  "servers": [
    {
      "url": "https://api.lumeablooms.com",
      "description": "Production API host"
    }
  ],
  "paths": {
    "/v1/products": {
      "get": {
        "operationId": "listProducts",
        "summary": "List published products",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": { "type": "integer", "minimum": 1, "default": 1 }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated product list",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ProductListResponse" }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "429": {
            "description": "Rate limited",
            "headers": {
              "Retry-After": {
                "schema": { "type": "integer" },
                "description": "Seconds until the client may retry"
              }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    },
    "/v1/products/{id}": {
      "get": {
        "operationId": "getProductById",
        "summary": "Get published product by id",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "format": "uuid" }
          }
        ],
        "responses": {
          "200": {
            "description": "Product detail",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ProductDetailDocument" }
              }
            }
          },
          "400": {
            "description": "Invalid id",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "404": {
            "description": "Product not found or not published",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "429": {
            "description": "Rate limited",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    },
    "/v1/search": {
      "get": {
        "operationId": "searchProducts",
        "summary": "Search published products by name or short description",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": { "type": "string", "minLength": 2, "maxLength": 200 },
            "description": "Search term; `%`, `_`, `\\` are stripped server-side before matching."
          },
          {
            "name": "page",
            "in": "query",
            "schema": { "type": "integer", "minimum": 1, "default": 1 }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated search results",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ProductListResponse" }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          },
          "429": {
            "description": "Rate limited",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Pagination": {
        "type": "object",
        "required": ["page", "limit", "total", "total_pages"],
        "properties": {
          "page": { "type": "integer", "minimum": 1 },
          "limit": { "type": "integer", "minimum": 1 },
          "total": { "type": "integer", "minimum": 0 },
          "total_pages": { "type": "integer", "minimum": 0 }
        }
      },
      "ProductListItem": {
        "type": "object",
        "required": [
          "id",
          "slug",
          "url",
          "name",
          "short_description",
          "product_type",
          "currency",
          "base_price",
          "effective_price",
          "tax_rate",
          "price_from",
          "variant_count",
          "stock",
          "image_url",
          "offer_pickup_at_store",
          "offer_home_delivery",
          "created_at",
          "updated_at"
        ],
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "slug": { "type": "string" },
          "url": { "type": "string", "format": "uri" },
          "name": { "type": "string" },
          "short_description": { "type": ["string", "null"] },
          "product_type": {
            "type": "string",
            "enum": ["common", "subscription", "event"]
          },
          "currency": { "type": "string", "enum": ["EUR"] },
          "base_price": { "type": "number" },
          "effective_price": { "type": "number" },
          "tax_rate": { "type": "number" },
          "price_from": { "type": ["number", "null"] },
          "variant_count": { "type": "integer", "minimum": 0 },
          "stock": { "type": ["integer", "null"] },
          "image_url": { "type": ["string", "null"], "format": "uri" },
          "offer_pickup_at_store": { "type": "boolean" },
          "offer_home_delivery": { "type": "boolean" },
          "gift_bono_enabled": { "type": "boolean" },
          "groups_enabled": { "type": "boolean" },
          "created_at": { "type": "string", "format": "date-time" },
          "updated_at": { "type": "string", "format": "date-time" }
        }
      },
      "ProductVariant": {
        "type": "object",
        "required": [
          "id",
          "name",
          "sku",
          "price_modifier",
          "unit_price",
          "stock",
          "sort_order"
        ],
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "name": { "type": "string" },
          "sku": { "type": ["string", "null"] },
          "price_modifier": { "type": "number" },
          "unit_price": { "type": "number" },
          "stock": { "type": ["integer", "null"] },
          "sort_order": { "type": "integer" }
        }
      },
      "ProductImage": {
        "type": "object",
        "required": ["url", "alt_text", "sort_order", "is_primary"],
        "properties": {
          "url": { "type": "string", "format": "uri" },
          "alt_text": { "type": ["string", "null"] },
          "sort_order": { "type": "integer" },
          "is_primary": { "type": "boolean" }
        }
      },
      "ProductExtra": {
        "type": "object",
        "required": [
          "id",
          "title",
          "description",
          "price",
          "sort_order",
          "is_required"
        ],
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "title": { "type": "string" },
          "description": { "type": ["string", "null"] },
          "price": { "type": "number" },
          "sort_order": { "type": "integer" },
          "is_required": { "type": "boolean" }
        }
      },
      "ProductSession": {
        "type": "object",
        "required": [
          "id",
          "start_at",
          "end_at",
          "status",
          "max_attendees",
          "booked_count"
        ],
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "start_at": { "type": "string", "format": "date-time" },
          "end_at": { "type": ["string", "null"], "format": "date-time" },
          "status": {
            "type": "string",
            "enum": ["available", "full", "cancelled"]
          },
          "max_attendees": { "type": ["integer", "null"] },
          "booked_count": { "type": "integer", "minimum": 0 }
        }
      },
      "ProductDetail": {
        "allOf": [
          { "$ref": "#/components/schemas/ProductListItem" },
          {
            "type": "object",
            "required": [
              "description",
              "category_ids",
              "variants",
              "images",
              "extras",
              "sessions"
            ],
            "properties": {
              "description": { "type": ["string", "null"] },
              "category_ids": {
                "type": "array",
                "items": { "type": "string", "format": "uuid" }
              },
              "variants": {
                "type": "array",
                "items": { "$ref": "#/components/schemas/ProductVariant" }
              },
              "images": {
                "type": "array",
                "items": { "$ref": "#/components/schemas/ProductImage" }
              },
              "extras": {
                "type": "array",
                "items": { "$ref": "#/components/schemas/ProductExtra" }
              },
              "sessions": {
                "type": "array",
                "items": { "$ref": "#/components/schemas/ProductSession" }
              }
            }
          }
        ]
      },
      "ProductListResponse": {
        "type": "object",
        "required": ["data", "pagination"],
        "properties": {
          "data": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/ProductListItem" }
          },
          "pagination": { "$ref": "#/components/schemas/Pagination" }
        }
      },
      "ProductDetailDocument": {
        "type": "object",
        "required": ["data"],
        "properties": {
          "data": { "$ref": "#/components/schemas/ProductDetail" }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "object",
            "required": ["code", "message"],
            "properties": {
              "code": { "type": "string" },
              "message": { "type": "string" },
              "details": {
                "type": "array",
                "items": {
                  "type": "object",
                  "required": ["path", "message"],
                  "properties": {
                    "path": { "type": "string" },
                    "message": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}