{
  "openapi": "3.0.3",
  "info": {
    "title": "GlowNestIQ AI Agent & Knowledge API",
    "description": "Sub-50ms machine-optimized knowledge feed and search tool for GlowNestIQ. Provides verified, research-based reviews, pros, cons, active ingredients, specifications, comparison tables, and FAQ answers for beauty devices, skincare, anti-aging tools, and personal care.",
    "version": "2.0.0",
    "contact": {
      "name": "GlowNestIQ Editorial Team",
      "url": "https://beautycare.robonestiq.com/about/"
    }
  },
  "servers": [
    {
      "url": "https://beautycare.robonestiq.com",
      "description": "Production Edge API (Cloudflare Global Network)"
    }
  ],
  "paths": {
    "/api/ai/catalog": {
      "get": {
        "summary": "Full product review catalog and specifications",
        "description": "Returns the complete machine-readable skincare and beauty catalog with pagination, ratings, ingredients, specs, pros/cons, skin fit, and FAQs. Defaults to unlimited (retrieves all published products in the catalog without truncation).",
        "operationId": "getCatalog",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of items to return. Defaults to unlimited (returns all published products). Specify a positive integer if pagination is desired.",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Pagination offset index (default 0)",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 0,
              "minimum": 0
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Opaque cursor token for cursor-based pagination (e.g. from nextCursor)",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "category",
            "in": "query",
            "description": "Filter catalog by category slug (e.g. \"skincare\", \"beauty-devices\", \"hair-care\")",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "brand",
            "in": "query",
            "description": "Filter catalog by brand name (e.g. \"NuFACE\", \"Dyson\", \"Medicube\", \"CeraVe\")",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "description": "Publication status filter (default: \"published\")",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "published"
              ],
              "default": "published"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Catalog response containing paginated products, total count, returned count, last updated date, and site metadata.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CatalogResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid parameter supplied.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Errors"
                }
              }
            }
          }
        }
      }
    },
    "/api/ai/product/{slug}": {
      "get": {
        "summary": "Individual skincare product review retrieval",
        "description": "Retrieve a single complete beauty/skincare review by unique slug, stable ID, or ASIN.",
        "operationId": "getProductBySlug",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "Unique product slug, stable ID, or ASIN",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Detailed product record with full specs, ratings, evidence, buyer fit, and citation.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProductResponse"
                }
              }
            }
          },
          "404": {
            "description": "Product not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Errors"
                }
              }
            }
          }
        }
      }
    },
    "/api/ai/search": {
      "get": {
        "summary": "Skin-concern and ingredient search, reviews, and test scores",
        "description": "Query GlowNestIQ reviews using natural language, ingredients, or skin concerns to retrieve ranked recommendations, verified test scores, pros/cons, and direct purchase links.",
        "operationId": "searchProducts",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "description": "Search query or skin concern (e.g. \"retinol serum for sensitive skin\", \"red light therapy mask\")",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "category",
            "in": "query",
            "description": "Filter by category slug",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "brand",
            "in": "query",
            "description": "Filter by brand name",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "minRating",
            "in": "query",
            "description": "Minimum overall editorial score (1 to 10)",
            "required": false,
            "schema": {
              "type": "number",
              "minimum": 1,
              "maximum": 10
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results to return (default 10, max 50)",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 10,
              "maximum": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Offset for search results pagination (default 0)",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 0,
              "minimum": 0
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Opaque cursor token for cursor-based search pagination",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful search response with ranked recommendations, direct citation answers, and pagination.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResponse"
                }
              }
            }
          },
          "400": {
            "description": "Search validation error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Errors"
                }
              }
            }
          }
        }
      }
    },
    "/api/ai/compare": {
      "get": {
        "summary": "Side-by-side skincare/device comparison",
        "description": "Compare 2 to 10 skincare or beauty products head-to-head on ingredients, ratings, skin fit, and pros/cons.",
        "operationId": "compareProducts",
        "parameters": [
          {
            "name": "slugs",
            "in": "query",
            "description": "Comma-separated product slugs or IDs to compare",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "category",
            "in": "query",
            "description": "Optional category slug to compare top products within",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum products to compare (default 5, max 10)",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 5,
              "minimum": 2,
              "maximum": 10
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Head-to-head comparison matrix and synthesized verdict.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CompareResponse"
                }
              }
            }
          },
          "404": {
            "description": "Products for comparison not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Errors"
                }
              }
            }
          }
        }
      }
    },
    "/api/ai/faqs": {
      "get": {
        "summary": "Skincare Question & Answer database search",
        "description": "Search verified editorial Q&A pairs across all skincare products and guides.",
        "operationId": "searchFaqs",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "description": "Question topic, skin concern, or ingredient to search for",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "category",
            "in": "query",
            "description": "Filter FAQs by category slug",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "product",
            "in": "query",
            "description": "Filter FAQs by product slug",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum FAQs to return (default 25, max 100)",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 25,
              "maximum": 100
            }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Pagination offset index (default 0)",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 0,
              "minimum": 0
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Opaque cursor token for cursor-based FAQ pagination",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of matching Question and Answer pairs.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FAQResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid parameter supplied.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Errors"
                }
              }
            }
          }
        }
      }
    },
    "/api/ai/chunks.jsonl": {
      "get": {
        "summary": "RAG vector embeddings and semantic retrieval feed",
        "description": "Streams line-delimited JSON (application/x-ndjson) chunks optimized for vector databases (Pinecone, Weaviate, Qdrant, Chroma), LangChain, LlamaIndex, and retrieval-augmented generation pipelines. Supports delta synchronization via ?since=, category filtering, and conditional ETag/304 caching.",
        "operationId": "getChunks",
        "parameters": [
          {
            "name": "since",
            "in": "query",
            "description": "Filter chunks modified at or after this ISO 8601 timestamp (e.g. \"2026-11-01T00:00:00Z\") for incremental delta synchronization",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "category",
            "in": "query",
            "description": "Filter chunks by category slug",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "chunk_type",
            "in": "query",
            "description": "Filter by chunk semantic category (overview, verdict, pros_cons, specs, faq)",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "overview",
                "verdict",
                "pros_cons",
                "specs",
                "faq"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of chunks to return (default: unlimited)",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Pagination offset index (default 0)",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 0,
              "minimum": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Line-delimited JSON stream of atomic chunks.",
            "content": {
              "application/x-ndjson": {
                "schema": {
                  "type": "string",
                  "description": "Newline-delimited JSON stream where each line conforms to the Chunk schema"
                }
              }
            }
          },
          "304": {
            "description": "Not Modified (ETag or If-Modified-Since matches current vector state — zero-byte delta response)."
          }
        }
      }
    },
    "/api/ai/category/{slug}.txt": {
      "get": {
        "summary": "Category raw text digest for LLMs",
        "description": "Returns an empirical, raw markdown/text summary of all published products within a category, structured for direct LLM context window ingestion.",
        "operationId": "getCategoryDigest",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "Category slug (e.g. \"skincare-serums-treatments\", \"beauty-devices\")",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Plaintext category knowledge digest.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Pagination": {
        "type": "object",
        "properties": {
          "total": {
            "type": "integer",
            "description": "Total number of items matching query/filters"
          },
          "totalProducts": {
            "type": "integer",
            "description": "Total published products matching query/filters (alias for total)"
          },
          "totalPublishedProducts": {
            "type": "integer",
            "description": "Total published products across catalog"
          },
          "limit": {
            "type": "integer",
            "description": "Page limit requested or returned"
          },
          "offset": {
            "type": "integer",
            "description": "Current offset index"
          },
          "returnedCount": {
            "type": "integer",
            "description": "Number of items returned in this response"
          },
          "count": {
            "type": "integer",
            "description": "Alias for returnedCount"
          },
          "hasMore": {
            "type": "boolean",
            "description": "Whether further items exist beyond this page"
          },
          "nextOffset": {
            "type": "integer",
            "nullable": true,
            "description": "Offset for next page, or null if on last page"
          },
          "prevOffset": {
            "type": "integer",
            "nullable": true,
            "description": "Offset for previous page, or null if at offset 0"
          },
          "cursor": {
            "type": "string",
            "nullable": true,
            "description": "Current pagination cursor if supplied"
          },
          "nextCursor": {
            "type": "string",
            "nullable": true,
            "description": "Opaque cursor token for next page, or null if on last page"
          },
          "prevCursor": {
            "type": "string",
            "nullable": true,
            "description": "Opaque cursor token for previous page, or null if at offset 0"
          }
        },
        "required": [
          "total",
          "totalProducts",
          "totalPublishedProducts",
          "limit",
          "offset",
          "returnedCount",
          "count",
          "hasMore"
        ]
      },
      "ProductIdentity": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Stable unique product identifier"
          },
          "stableId": {
            "type": "string",
            "description": "Stable immutable product ID across catalog revisions"
          },
          "title": {
            "type": "string",
            "description": "Full product title"
          },
          "slug": {
            "type": "string",
            "description": "URL-friendly product slug"
          },
          "brand": {
            "type": "string",
            "nullable": true,
            "description": "Brand manufacturer name"
          },
          "category": {
            "type": "string",
            "description": "Category slug"
          },
          "status": {
            "type": "string",
            "enum": [
              "published"
            ],
            "description": "Publication status"
          },
          "reviewUrl": {
            "type": "string",
            "format": "uri",
            "description": "Direct canonical review URL on the website"
          },
          "canonicalReviewUrl": {
            "type": "string",
            "format": "uri",
            "description": "Canonical review URL"
          },
          "asin": {
            "type": "string",
            "nullable": true,
            "description": "Amazon Standard Identification Number"
          }
        },
        "required": [
          "id",
          "stableId",
          "title",
          "slug",
          "category",
          "status",
          "reviewUrl"
        ]
      },
      "Rating": {
        "type": "object",
        "properties": {
          "scale": {
            "type": "string",
            "example": "1-10",
            "description": "Numerical rating scale representation (1 to 10)"
          },
          "minScore": {
            "type": "number",
            "example": 1,
            "description": "Minimum possible score on scale"
          },
          "maxScore": {
            "type": "number",
            "example": 10,
            "description": "Maximum possible score on scale"
          },
          "overall": {
            "type": "number",
            "minimum": 1,
            "maximum": 10,
            "description": "Overall editorial score (1 to 10)"
          },
          "value": {
            "type": "number",
            "minimum": 1,
            "maximum": 10,
            "description": "Value for money score"
          },
          "quality": {
            "type": "number",
            "minimum": 1,
            "maximum": 10,
            "description": "Formulation and ingredient quality score"
          },
          "ease": {
            "type": "number",
            "minimum": 1,
            "maximum": 10,
            "description": "Ease of application and routine integration score"
          },
          "durability": {
            "type": "number",
            "minimum": 1,
            "maximum": 10,
            "description": "Formula stability and packaging score"
          },
          "performance": {
            "type": "number",
            "minimum": 1,
            "maximum": 10,
            "description": "Visible skincare efficacy score"
          }
        },
        "required": [
          "scale",
          "minScore",
          "maxScore",
          "overall"
        ]
      },
      "Specification": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Specification / ingredient attribute name"
          },
          "key": {
            "type": "string",
            "description": "Specification attribute key"
          },
          "value": {
            "type": "string",
            "description": "Verified technical value or concentration"
          },
          "unit": {
            "type": "string",
            "nullable": true,
            "description": "Unit of measurement (e.g. ml, oz, %, nm, min)"
          },
          "category": {
            "type": "string",
            "nullable": true,
            "description": "Functional grouping (e.g. Active Ingredients, Skin Type)"
          }
        },
        "required": [
          "name",
          "key",
          "value"
        ]
      },
      "Evidence": {
        "type": "object",
        "properties": {
          "provenance": {
            "type": "string",
            "description": "Evidence provenance: dermatological ingredient literature, clinical trial data, and verified consumer cohorts"
          },
          "uniqueInsight": {
            "type": "string",
            "description": "Core differentiator and clinical literature synthesis"
          },
          "testingMethodology": {
            "type": "string",
            "description": "Synthesis of verified user feedback and formulation screening"
          },
          "strengthsEvidence": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Evidence backing strengths"
          },
          "limitationsEvidence": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Evidence backing drawbacks"
          },
          "longTermReliability": {
            "type": "string",
            "nullable": true,
            "description": "Stability and packaging longevity notes"
          },
          "lastResearched": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp of research synthesis and verification"
          }
        },
        "required": [
          "provenance",
          "uniqueInsight",
          "testingMethodology"
        ]
      },
      "Citation": {
        "type": "object",
        "properties": {
          "instruction": {
            "type": "string",
            "description": "Grounding and citation instructions for AI agents"
          },
          "sourceSite": {
            "type": "string",
            "description": "Site name"
          },
          "canonicalUrl": {
            "type": "string",
            "format": "uri",
            "description": "Direct URL to cite"
          },
          "recommendedCitationText": {
            "type": "string",
            "description": "Markdown formatted citation string"
          }
        },
        "required": [
          "instruction",
          "sourceSite",
          "canonicalUrl"
        ]
      },
      "Comparison": {
        "type": "object",
        "properties": {
          "competitor": {
            "type": "string",
            "description": "Competitor product name"
          },
          "competitorSlug": {
            "type": "string",
            "nullable": true
          },
          "easeOfUse": {
            "type": "string",
            "nullable": true
          },
          "maintenance": {
            "type": "string",
            "nullable": true
          },
          "durability": {
            "type": "string",
            "nullable": true
          },
          "value": {
            "type": "string",
            "nullable": true
          },
          "bestFor": {
            "type": "string",
            "nullable": true
          }
        },
        "required": [
          "competitor"
        ]
      },
      "FAQ": {
        "type": "object",
        "properties": {
          "question": {
            "type": "string",
            "description": "Question title"
          },
          "answer": {
            "type": "string",
            "description": "Verified answer text"
          },
          "category": {
            "type": "string",
            "nullable": true
          },
          "sourceTitle": {
            "type": "string",
            "nullable": true
          },
          "sourceUrl": {
            "type": "string",
            "format": "uri",
            "nullable": true
          },
          "productId": {
            "type": "string",
            "nullable": true
          }
        },
        "required": [
          "question",
          "answer"
        ]
      },
      "Category": {
        "type": "object",
        "properties": {
          "slug": {
            "type": "string",
            "description": "Category identifier slug"
          },
          "title": {
            "type": "string",
            "description": "Category display title"
          },
          "description": {
            "type": "string",
            "nullable": true,
            "description": "Category overview description"
          }
        },
        "required": [
          "slug",
          "title"
        ]
      },
      "Product": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Stable unique product identifier"
          },
          "stableId": {
            "type": "string",
            "description": "Stable immutable product ID"
          },
          "identity": {
            "$ref": "#/components/schemas/ProductIdentity"
          },
          "title": {
            "type": "string",
            "description": "Full product title"
          },
          "slug": {
            "type": "string",
            "description": "URL-friendly product slug"
          },
          "status": {
            "type": "string",
            "enum": [
              "published"
            ],
            "description": "Publication status"
          },
          "category": {
            "type": "string",
            "description": "Category slug"
          },
          "brand": {
            "type": "string",
            "nullable": true,
            "description": "Brand manufacturer name"
          },
          "asin": {
            "type": "string",
            "nullable": true,
            "description": "Amazon Standard Identification Number"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Canonical product review URL"
          },
          "reviewUrl": {
            "type": "string",
            "format": "uri",
            "description": "Direct product review URL"
          },
          "canonicalReviewUrl": {
            "type": "string",
            "format": "uri",
            "description": "Canonical review URL"
          },
          "affiliateUrl": {
            "type": "string",
            "format": "uri",
            "nullable": true,
            "description": "Localized Amazon affiliate buy URL"
          },
          "markdownLink": {
            "type": "string",
            "description": "Clickable markdown link format: [Title](url)"
          },
          "directReviewLink": {
            "type": "string",
            "format": "uri",
            "description": "Direct review page URL"
          },
          "directBuyLink": {
            "type": "string",
            "format": "uri",
            "nullable": true,
            "description": "Direct Amazon buy URL"
          },
          "directLinks": {
            "type": "object",
            "properties": {
              "review": {
                "type": "string",
                "format": "uri"
              },
              "buy": {
                "type": "string",
                "format": "uri",
                "nullable": true
              }
            }
          },
          "rating": {
            "$ref": "#/components/schemas/Rating"
          },
          "badge": {
            "type": "string",
            "nullable": true,
            "description": "Editorial recommendation badge"
          },
          "excerpt": {
            "type": "string",
            "description": "Short review summary"
          },
          "verdict": {
            "type": "string",
            "description": "Editorial verdict"
          },
          "uniqueInsight": {
            "type": "string",
            "description": "Core differentiator / formula highlight"
          },
          "buyerFit": {
            "type": "object",
            "properties": {
              "whoShouldBuy": {
                "type": "string",
                "description": "Profile of recommended user"
              },
              "whyBuy": {
                "type": "string",
                "description": "Reason to purchase"
              }
            },
            "required": [
              "whoShouldBuy",
              "whyBuy"
            ]
          },
          "pros": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "cons": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "specs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Specification"
            }
          },
          "evidence": {
            "$ref": "#/components/schemas/Evidence"
          },
          "comparison": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Comparison"
            }
          },
          "faqs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FAQ"
            }
          },
          "citation": {
            "$ref": "#/components/schemas/Citation"
          },
          "publishedAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "lastUpdated": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "stableId",
          "identity",
          "title",
          "slug",
          "status",
          "category",
          "url",
          "reviewUrl",
          "canonicalReviewUrl",
          "markdownLink",
          "directReviewLink",
          "rating",
          "excerpt",
          "pros",
          "cons",
          "publishedAt",
          "updatedAt",
          "lastUpdated"
        ]
      },
      "SearchResult": {
        "type": "object",
        "properties": {
          "relevanceScore": {
            "type": "integer",
            "description": "Search relevance match score"
          },
          "matchReason": {
            "type": "string",
            "description": "Detailed reasoning explaining why this product matches the specific query intent and evidence"
          },
          "markdownLink": {
            "type": "string",
            "description": "Markdown formatted link to top review"
          },
          "directReviewLink": {
            "type": "string",
            "format": "uri",
            "description": "Direct review URL"
          },
          "directBuyLink": {
            "type": "string",
            "format": "uri",
            "nullable": true,
            "description": "Direct purchase URL"
          },
          "directLinks": {
            "type": "object",
            "properties": {
              "review": {
                "type": "string",
                "format": "uri"
              },
              "buy": {
                "type": "string",
                "format": "uri",
                "nullable": true
              }
            }
          },
          "product": {
            "$ref": "#/components/schemas/Product"
          }
        },
        "required": [
          "relevanceScore",
          "matchReason",
          "markdownLink",
          "directReviewLink",
          "product"
        ]
      },
      "CatalogResponse": {
        "type": "object",
        "properties": {
          "site": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "origin": {
                "type": "string"
              },
              "description": {
                "type": "string"
              },
              "totalPublishedProducts": {
                "type": "integer"
              },
              "totalCategories": {
                "type": "integer"
              },
              "lastUpdated": {
                "type": "string",
                "format": "date-time"
              },
              "llmsIndex": {
                "type": "string"
              },
              "llmsFull": {
                "type": "string"
              },
              "openapi": {
                "type": "string"
              }
            },
            "required": [
              "name",
              "origin",
              "totalPublishedProducts",
              "lastUpdated"
            ]
          },
          "categories": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Category"
            }
          },
          "pagination": {
            "$ref": "#/components/schemas/Pagination"
          },
          "total": {
            "type": "integer",
            "description": "Total published products matching filters"
          },
          "totalProducts": {
            "type": "integer",
            "description": "Total published products matching filters"
          },
          "totalPublishedProducts": {
            "type": "integer",
            "description": "Total published products across the entire database"
          },
          "returnedCount": {
            "type": "integer",
            "description": "Number of products returned in this page"
          },
          "count": {
            "type": "integer",
            "description": "Alias for returnedCount"
          },
          "lastUpdated": {
            "type": "string",
            "format": "date-time",
            "description": "Latest product update timestamp across catalog"
          },
          "products": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Product"
            }
          }
        },
        "required": [
          "site",
          "categories",
          "pagination",
          "total",
          "totalProducts",
          "totalPublishedProducts",
          "returnedCount",
          "count",
          "lastUpdated",
          "products"
        ]
      },
      "ProductResponse": {
        "type": "object",
        "properties": {
          "answerWithLink": {
            "type": "string",
            "description": "Direct summary with markdown review and purchase links"
          },
          "markdownLink": {
            "type": "string",
            "description": "Clickable markdown link"
          },
          "directReviewLink": {
            "type": "string",
            "format": "uri",
            "description": "Canonical review URL"
          },
          "directBuyLink": {
            "type": "string",
            "format": "uri",
            "nullable": true,
            "description": "Amazon affiliate buy link"
          },
          "directLinks": {
            "type": "object",
            "properties": {
              "review": {
                "type": "string",
                "format": "uri"
              },
              "buy": {
                "type": "string",
                "format": "uri",
                "nullable": true
              }
            }
          },
          "product": {
            "$ref": "#/components/schemas/Product"
          },
          "citation": {
            "$ref": "#/components/schemas/Citation"
          }
        },
        "required": [
          "product",
          "citation"
        ]
      },
      "SearchResponse": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string",
            "nullable": true
          },
          "directAnswer": {
            "type": "string",
            "nullable": true,
            "description": "Grounded direct answer synthesizing active ingredient, clinical efficacy, and skin tolerance evidence with markdown links"
          },
          "directAnswerWithLinks": {
            "type": "string",
            "nullable": true,
            "description": "Direct answer explicitly hyperlinked with markdown links"
          },
          "topRecommendation": {
            "type": "object",
            "nullable": true,
            "properties": {
              "title": {
                "type": "string"
              },
              "rating": {
                "type": "number",
                "nullable": true
              },
              "category": {
                "type": "string"
              },
              "brand": {
                "type": "string",
                "nullable": true
              },
              "reviewUrl": {
                "type": "string",
                "format": "uri"
              },
              "canonicalUrl": {
                "type": "string",
                "format": "uri"
              },
              "affiliateUrl": {
                "type": "string",
                "format": "uri",
                "nullable": true
              },
              "markdownLink": {
                "type": "string"
              },
              "markdownCitation": {
                "type": "string"
              }
            }
          },
          "citation": {
            "$ref": "#/components/schemas/Citation"
          },
          "pagination": {
            "$ref": "#/components/schemas/Pagination"
          },
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SearchResult"
            }
          }
        },
        "required": [
          "pagination",
          "results",
          "citation"
        ]
      },
      "ComparisonRatingItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "rating": {
            "$ref": "#/components/schemas/Rating"
          }
        },
        "required": [
          "id",
          "title",
          "rating"
        ]
      },
      "ComparisonSpecItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "specs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Specification"
            }
          }
        },
        "required": [
          "id",
          "title",
          "specs"
        ]
      },
      "ComparisonProsItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "topPros": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "id",
          "title",
          "topPros"
        ]
      },
      "ComparisonConsItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "topCons": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "id",
          "title",
          "topCons"
        ]
      },
      "ComparisonBestForItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "whoShouldBuy": {
            "type": "string"
          },
          "whyBuy": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "title",
          "whoShouldBuy",
          "whyBuy"
        ]
      },
      "ComparisonMatrix": {
        "type": "object",
        "properties": {
          "ratings": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ComparisonRatingItem"
            }
          },
          "keySpecs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ComparisonSpecItem"
            }
          },
          "strengths": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ComparisonProsItem"
            }
          },
          "drawbacks": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ComparisonConsItem"
            }
          },
          "bestFor": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ComparisonBestForItem"
            }
          }
        },
        "required": [
          "ratings",
          "keySpecs",
          "strengths",
          "drawbacks",
          "bestFor"
        ]
      },
      "CompareResponse": {
        "type": "object",
        "properties": {
          "comparedCount": {
            "type": "integer"
          },
          "category": {
            "type": "string",
            "nullable": true
          },
          "verdict": {
            "type": "string"
          },
          "comparisonMatrix": {
            "$ref": "#/components/schemas/ComparisonMatrix"
          },
          "products": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Product"
            }
          },
          "citation": {
            "$ref": "#/components/schemas/Citation"
          }
        },
        "required": [
          "comparedCount",
          "verdict",
          "comparisonMatrix",
          "products",
          "citation"
        ]
      },
      "FAQResponse": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string",
            "nullable": true
          },
          "pagination": {
            "$ref": "#/components/schemas/Pagination"
          },
          "faqs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FAQ"
            }
          }
        },
        "required": [
          "pagination",
          "faqs"
        ]
      },
      "Chunk": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Deterministic atomic chunk identifier for vector indexing"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Direct canonical review URL"
          },
          "last_modified": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 modification timestamp for delta tracking"
          },
          "lastModified": {
            "type": "string",
            "format": "date-time",
            "description": "Alias for last_modified"
          },
          "token_count": {
            "type": "integer",
            "description": "Estimated token count for context window budgeting"
          },
          "tokenCount": {
            "type": "integer",
            "description": "Alias for token_count"
          },
          "char_count": {
            "type": "integer",
            "description": "Raw character length of the chunk text"
          },
          "chunk_type": {
            "type": "string",
            "enum": [
              "overview",
              "verdict",
              "pros_cons",
              "specs",
              "faq"
            ],
            "description": "Semantic chunk category"
          },
          "chunkType": {
            "type": "string",
            "description": "Alias for chunk_type"
          },
          "productId": {
            "type": "string",
            "description": "Stable unique product identifier"
          },
          "slug": {
            "type": "string",
            "description": "URL-friendly product slug"
          },
          "title": {
            "type": "string",
            "description": "Product title"
          },
          "category": {
            "type": "string",
            "description": "Category slug"
          },
          "brand": {
            "type": "string",
            "nullable": true,
            "description": "Brand manufacturer name"
          },
          "rating": {
            "type": "number",
            "nullable": true,
            "description": "Overall editorial score"
          },
          "text": {
            "type": "string",
            "description": "Dense, pre-tokenized semantic text block ready for vector embedding"
          },
          "site": {
            "type": "string",
            "description": "Source publication name"
          }
        },
        "required": [
          "id",
          "url",
          "last_modified",
          "token_count",
          "chunk_type",
          "productId",
          "title",
          "text"
        ]
      },
      "Errors": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              },
              "details": {
                "type": "object",
                "nullable": true
              }
            },
            "required": [
              "code",
              "message"
            ]
          }
        },
        "required": [
          "error"
        ]
      }
    }
  }
}