{"openapi":"3.1.0","info":{"title":"Catalog Search MVP","version":"0.1.0"},"paths":{"/admin/orders":{"get":{"tags":["shop"],"summary":"Admin Orders","operationId":"admin_orders_admin_orders_get","responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}}}}},"/admin/order/{order_id}":{"get":{"tags":["shop"],"summary":"Admin Order View","operationId":"admin_order_view_admin_order__order_id__get","parameters":[{"name":"order_id","in":"path","required":true,"schema":{"type":"integer","title":"Order Id"}}],"responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/cart/add":{"post":{"tags":["cart"],"summary":"Cart Add","operationId":"cart_add_cart_add_post","requestBody":{"content":{"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/Body_cart_add_cart_add_post"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/cart/inc":{"post":{"tags":["cart"],"summary":"Cart Inc","description":"Увеличить/уменьшить количество.\ndelta может быть +1 или -1.\nЕсли стало <=0 -> удаляем позицию.","operationId":"cart_inc_cart_inc_post","requestBody":{"content":{"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/Body_cart_inc_cart_inc_post"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/cart/set":{"post":{"tags":["cart"],"summary":"Cart Set","description":"Установить количество вручную.\nqty <= 0 -> удаляем позицию.","operationId":"cart_set_cart_set_post","requestBody":{"content":{"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/Body_cart_set_cart_set_post"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/cart/remove":{"post":{"tags":["cart"],"summary":"Cart Remove","operationId":"cart_remove_cart_remove_post","requestBody":{"content":{"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/Body_cart_remove_cart_remove_post"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/cart/clear":{"post":{"tags":["cart"],"summary":"Cart Clear","operationId":"cart_clear_cart_clear_post","requestBody":{"content":{"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/Body_cart_clear_cart_clear_post"}}}},"responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/cart":{"get":{"tags":["cart"],"summary":"Cart View","operationId":"cart_view_cart_get","responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}}}}},"/checkout":{"get":{"tags":["checkout"],"summary":"Checkout Page","description":"Страница оформления заказа:\n- читает корзину\n- подтягивает товары из базы\n- считает суммы\n- рендерит templates/checkout.html","operationId":"checkout_page_checkout_get","responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}}}},"post":{"tags":["checkout"],"summary":"Checkout Submit","description":"Отправка заказа:\n- читает корзину\n- создаёт заказ + order_items\n- редиректит в WhatsApp с полным текстом","operationId":"checkout_submit_checkout_post","requestBody":{"content":{"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/Body_checkout_submit_checkout_post"}}}},"responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/quick-order":{"post":{"tags":["checkout"],"summary":"Quick Order","description":"1 клик:\n- создаём заказ в БД со статусом new\n- создаём одну позицию заказа\n- редиректим в WhatsApp с готовым текстом","operationId":"quick_order_quick_order_post","requestBody":{"content":{"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/Body_quick_order_quick_order_post"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/order/{token}":{"get":{"tags":["checkout"],"summary":"Order View","description":"Полный заказ по токену (бессрочно).","operationId":"order_view_order__token__get","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string","title":"Token"}}],"responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/catalog":{"get":{"tags":["SEO"],"summary":"Api Catalog","operationId":"api_catalog_api_catalog_get","parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"description":"Номер страницы, начиная с 1","default":1,"title":"Page"},"description":"Номер страницы, начиная с 1"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"description":"Размер страницы","default":100,"title":"Limit"},"description":"Размер страницы"},{"name":"instock","in":"query","required":false,"schema":{"type":"integer","description":"1 = только товары в наличии","default":0,"title":"Instock"},"description":"1 = только товары в наличии"},{"name":"order_by","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Имя колонки сортировки, если существует в таблице","title":"Order By"},"description":"Имя колонки сортировки, если существует в таблице"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/admin/generate-seo-files":{"post":{"tags":["SEO"],"summary":"Generate Seo Files","operationId":"generate_seo_files_api_admin_generate_seo_files_post","parameters":[{"name":"output_dir","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Папка для генерации файлов","title":"Output Dir"},"description":"Папка для генерации файлов"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/llms.txt":{"get":{"tags":["SEO Files"],"summary":"LLM discovery file for AI agents","description":"Returns the site's llms.txt file.\n\n    Purpose:\n    - helps AI systems understand the catalog structure\n    - points AI agents to the main API endpoints\n    - exposes canonical product page pattern and discovery resources\n\n    For AI clients:\n    This is a machine-oriented discovery file, not a search endpoint.\n    Use the URLs listed inside this file for actual catalog operations.","operationId":"llms_txt_llms_txt_get","responses":{"200":{"description":"Plain text llms.txt file","content":{"application/json":{"schema":{}}}}}}},"/robots.txt":{"get":{"tags":["SEO Files"],"summary":"Robots policy file for search engines and AI crawlers","description":"Returns the site's robots.txt file.\n\nPurpose:\n- tells crawlers which parts of the site may be crawled\n- exposes sitemap location\n- provides crawl policy for search engines and AI bots\n\nFor AI clients:\nThis is not a product search endpoint and not a product data endpoint.\nIt is a crawler-policy file used by indexing systems.\n\nResponse:\nPlain text file content of `/robots.txt`.","operationId":"robots_robots_txt_get","responses":{"200":{"description":"Plain text robots.txt file","content":{"application/json":{"schema":{}}}}}}},"/api":{"get":{"tags":["Service Docs"],"summary":"Human-readable API documentation page","description":"Returns the static HTML documentation page for the site's public API.\n\nPurpose:\n- documentation for programmers\n- quick manual review of available API routes\n- fallback documentation outside Swagger UI\n\nFor AI clients:\nThis endpoint is documentation, not a product search route.\nUse `/openapi.json` for machine-readable contract.\nUse `/api/ai-search`, `/api/search`, `/api/semantic-search`,\nand `/api/item/{sku}` for actual product operations.","operationId":"api_html_api_get","responses":{"200":{"description":"Static HTML API documentation page","content":{"application/json":{"schema":{}}}}}}},"/sitemap.xml":{"get":{"tags":["SEO Files"],"summary":"Main XML sitemap index for the site","description":"Returns the main XML sitemap file.\n\nPurpose:\n- entrypoint for search engine indexing\n- discovery of public site sections\n- canonical sitemap location advertised in robots.txt\n\nFor AI clients:\nThis endpoint is for indexing/discovery workflows.\nIt is not a search endpoint and not a product detail endpoint.","operationId":"sitemap_sitemap_xml_get","responses":{"200":{"description":"Main XML sitemap file","content":{"application/json":{"schema":{}}}}}}},"/sitemap_pages.xml":{"get":{"tags":["SEO Files"],"summary":"XML sitemap for static and informational pages","description":"Returns the sitemap containing static/informational pages.\n\nTypical content:\n- homepage\n- public info pages\n- non-product pages\n\nFor AI clients:\nThis is an indexing/discovery file, not a product search endpoint.","operationId":"sitemap_pages_sitemap_pages_xml_get","responses":{"200":{"description":"XML sitemap for site pages","content":{"application/json":{"schema":{}}}}}}},"/sitemap_products.xml":{"get":{"tags":["SEO Files"],"summary":"XML sitemap for product URLs","description":"Returns the sitemap containing product URLs.\n\nPurpose:\n- discovery of product pages by search engines\n- bulk indexing of catalog items\n- sitemap partition dedicated to product resources\n\nFor AI clients:\nUse this endpoint for product URL discovery only.\nFor actual product JSON retrieval, use `/api/item/{sku}`.","operationId":"sitemap_products_sitemap_products_xml_get","responses":{"200":{"description":"XML sitemap for product pages","content":{"application/json":{"schema":{}}}}}}},"/BingSiteAuth.xml":{"get":{"tags":["SEO Files"],"summary":"Bing site ownership verification file","description":"Returns the XML verification file used by Bing Webmaster Tools.\n\nPurpose:\n- proves domain ownership to Bing\n- used only for search engine verification workflows\n\nFor AI clients:\nThis is a verification artifact, not a product endpoint.","operationId":"bing_site_auth_BingSiteAuth_xml_get","responses":{"200":{"description":"Bing verification XML file","content":{"application/json":{"schema":{}}}}}}},"/api/ai-catalog":{"get":{"tags":["AI Catalog"],"summary":"AI catalog discovery endpoint","description":"Machine-readable discovery endpoint for AI agents.\n\n    Purpose:\n    Provides a single entry point that describes how AI systems\n    should interact with this product catalog.\n\n    Recommended flow for AI agents:\n\n    1) Use the main search endpoint to find products\n    2) Retrieve product details using the product API\n    3) Use the canonical product page URL for HTML rendering\n\n    This endpoint reduces the need for AI systems to parse\n    the entire OpenAPI schema and provides a simplified\n    catalog interaction model.","operationId":"ai_catalog_discovery_api_ai_catalog_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/api/catalog-root":{"get":{"tags":["Catalog"],"summary":"Root catalog categories as JSON","description":"Returns the first root catalog categories in JSON format.\n\nResponse fields for each category:\n- `name`: category name\n- `item_count`: number of products in the category\n- `url`: full absolute URL to the category page\n\nUse `depth` to control how many top categories are returned.\nDefault value is 10.","operationId":"api_catalog_root_api_catalog_root_get","parameters":[{"name":"depth","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"How many first root categories to return","default":10,"title":"Depth"},"description":"How many first root categories to return"}],"responses":{"200":{"description":"Root catalog category list in JSON","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/product/{sku}":{"get":{"tags":["Redirects"],"summary":"SEO alias for canonical product page","description":"Redirect endpoint for product pages.\n\nPurpose:\n- supports legacy links\n- supports SEO-friendly aliases\n- redirects clients to the canonical HTML product page\n\nCanonical destination:\n`/item/{sku}`\n\nFor AI clients:\nDo not treat this endpoint as the canonical product resource.\nThis route returns an HTTP redirect.\nIf you need full JSON product data, use `/api/item/{sku}`.\nIf you need the canonical HTML page, follow the redirect to `/item/{sku}`.\n\nExample:\n- `/product/998528` -> `/item/998528`","operationId":"redirect_product_to_item_product__sku__get","parameters":[{"name":"sku","in":"path","required":true,"schema":{"type":"string","description":"Product SKU used to build redirect target `/item/{sku}`","examples":["998528","CM11","GBH226"],"title":"Sku"},"description":"Product SKU used to build redirect target `/item/{sku}`"}],"responses":{"200":{"description":"HTTP 301 redirect to canonical HTML product page `/item/{sku}`","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/p/{sku}":{"get":{"tags":["Redirects"],"summary":"Short alias redirect to canonical product page","description":"Short redirect alias for product pages.\n\nPurpose:\n- short links\n- compact public product URLs\n- legacy compatibility\n\nCanonical destination:\n`/item/{sku}`\n\nFor AI clients:\nThis is not the canonical product resource and not a JSON API endpoint.\nIt returns an HTTP redirect to the HTML product page.\nFor structured product data, use `/api/item/{sku}`.\n\nExample:\n- `/p/998528` -> `/item/998528`","operationId":"redirect_short_to_item_p__sku__get","parameters":[{"name":"sku","in":"path","required":true,"schema":{"type":"string","description":"Product SKU used to build redirect target `/item/{sku}`","examples":["998528","CM11","GBH226"],"title":"Sku"},"description":"Product SKU used to build redirect target `/item/{sku}`"}],"responses":{"200":{"description":"HTTP 301 redirect to canonical HTML product page `/item/{sku}`","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/ai-search":{"get":{"tags":["AI Search"],"summary":"Main search endpoint for external AI agents","description":"Primary machine-friendly product search endpoint.\n\nFor external AI agents:\nUse this endpoint as the default product search route.\n\nSupported modes:\n- `auto`:\n  server chooses the most appropriate search strategy\n- `keyword`:\n  exact SKU / exact name / literal text search\n- `semantic`:\n  natural-language semantic search\n- `hybrid`:\n  combined keyword + semantic search\n\nRecommended usage:\nIf the client does not know which search strategy to choose,\nuse `mode=auto`.\n\nTypical flow for AI agents:\n1. Call `/api/ai-search?q=...&mode=auto`\n2. Read `items`\n3. Take `sku`\n4. Call `/api/item/{sku}` for a full product card\n\nBest examples:\n- `CT18116BMC` -> usually resolved to `keyword`\n- `перфоратор crown` -> usually resolved to `hybrid`\n- `добавка для бетона` -> usually resolved to `hybrid`\n- `машинка для бурения` -> usually resolved to `hybrid`\n\nResponse:\nReturns:\n- original query\n- requested mode\n- resolved search mode used by server\n- result count\n- items","operationId":"api_ai_search_api_ai_search_get","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1,"description":"User search query for AI-oriented product retrieval","examples":["CT18116BMC","перфоратор crown","добавка для бетона","машинка для бурения"],"title":"Q"},"description":"User search query for AI-oriented product retrieval"},{"name":"mode","in":"query","required":false,"schema":{"type":"string","pattern":"^(auto|keyword|semantic|hybrid)$","description":"Search mode: auto, keyword, semantic, hybrid","default":"auto","title":"Mode"},"description":"Search mode: auto, keyword, semantic, hybrid"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum number of products to return","default":20,"title":"Limit"},"description":"Maximum number of products to return"},{"name":"prefix","in":"query","required":false,"schema":{"type":"integer","description":"Enable prefix mode for keyword/hybrid search: 1 = enabled, 0 = disabled","default":0,"title":"Prefix"},"description":"Enable prefix mode for keyword/hybrid search: 1 = enabled, 0 = disabled"},{"name":"instock","in":"query","required":false,"schema":{"type":"integer","description":"Return only products in stock: 1 = only in stock, 0 = all products","default":1,"title":"Instock"},"description":"Return only products in stock: 1 = only in stock, 0 = all products"},{"name":"min_score","in":"query","required":false,"schema":{"type":"number","minimum":0.0,"description":"Minimum semantic similarity threshold for semantic/hybrid search","default":0.2,"title":"Min Score"},"description":"Minimum semantic similarity threshold for semantic/hybrid search"}],"responses":{"200":{"description":"Unified AI-friendly search response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"x-ai-guidance":{"recommended_as_primary_search_endpoint":true,"follow_up_endpoint":"/api/item/{sku}","recommended_default_mode":"auto","modes":{"auto":"server chooses the most appropriate search strategy","keyword":"exact sku / exact product name / literal query","semantic":"natural-language semantic search","hybrid":"combined keyword + semantic search"}}}},"/api/llm-search-plan":{"get":{"tags":["AI Search"],"summary":"LLM search planning endpoint","description":"Returns a structured LLM-generated search plan for the client query.\n\nThis endpoint does not search the catalog by itself.\nIt interprets the query and returns:\n- query type\n- normalized query\n- candidate catalog entities\n- one or more search queries for the catalog\n\nUse this endpoint as an orchestration layer before running keyword, semantic,\nanalog, or material-set search flows.","operationId":"api_llm_search_plan_api_llm_search_plan_get","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1,"description":"Raw client query that must be interpreted into a catalog search plan","examples":["стропила","болгарка","чем обработать дерево","циферблат"],"title":"Q"},"description":"Raw client query that must be interpreted into a catalog search plan"}],"responses":{"200":{"description":"Structured JSON plan for catalog search orchestration","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/query-spell-suggest":{"get":{"tags":["AI Search"],"summary":"Spell suggestion fallback for raw client query","description":"Returns a corrected query candidate when the original text may contain a typo.\n\nUse this endpoint only as a fallback when:\n- product search returned no results\n- analog search returned no results\n- you want to verify whether the user likely misspelled the product name\n\nThis endpoint does not search the catalog.\nIt only suggests a corrected query candidate based on external autocomplete data.","operationId":"api_query_spell_suggest_api_query_spell_suggest_get","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1,"description":"Raw client query that may contain a typo","examples":["страпила","колоши","щотка"],"title":"Q"},"description":"Raw client query that may contain a typo"}],"responses":{"200":{"description":"Spell correction suggestion for the original query","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/query-domain-classify":{"get":{"tags":["AI Search"],"summary":"Catalog domain classification for corrected or ambiguous query","description":"Classifies whether the query belongs to our store domains:\n- construction goods\n- household goods\n- outside the store domain\n\nUse this endpoint after spell-correction or before analog search fallback.","operationId":"api_query_domain_classify_api_query_domain_classify_get","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1,"description":"Corrected or ambiguous query that must be classified by store domain","examples":["стропила","галоши","tank"],"title":"Q"},"description":"Corrected or ambiguous query that must be classified by store domain"}],"responses":{"200":{"description":"Domain classification for catalog relevance","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/search":{"get":{"tags":["Search"],"summary":"Keyword search: exact SKU, exact name, short literal query","description":"Main keyword / FTS search endpoint.\n\nFor external AI agents:\nUse this endpoint when the user query is:\n- an exact SKU / article / model code\n- an exact or near-exact product name\n- a short literal text query\n- a query where strict textual matching is preferred\n\nBest query examples:\n- `CM11`\n- `bosch gbh 2-26`\n- `перфоратор`\n- `шуруп`\n- `саморез 3.5x25`\n\nDo not use as the first choice when the user asks by meaning / purpose.\nExamples of queries that are better for `/api/semantic-search`:\n- `клей для плитки для ванной`\n- `чем сверлить бетон`\n- `материал для утепления стены`\n- `что использовать для гипсокартона`\n\nResponse logic:\nReturns a JSON object with:\n- original query\n- `search_type = \"keyword\"`\n- result count\n- result items\n\nEach item is intended to be a lightweight search result for catalog usage.\nIf the client needs full product details, call `/api/item/{sku}` using the returned `sku`.\n\nRecommended integration flow for AI agents:\n1. Call `/api/search?q=...`\n2. Read `items`\n3. Take `sku`\n4. Call `/api/item/{sku}` for a full product card","operationId":"api_search_api_search_get","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1,"description":"Exact SKU, exact product name, or literal text fragment for keyword search","examples":["CM11","bosch gbh 2-26","перфоратор"],"title":"Q"},"description":"Exact SKU, exact product name, or literal text fragment for keyword search"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum number of products to return","default":20,"title":"Limit"},"description":"Maximum number of products to return"},{"name":"prefix","in":"query","required":false,"schema":{"type":"integer","description":"Enable prefix matching in FTS search: 1 = enabled, 0 = disabled","default":0,"title":"Prefix"},"description":"Enable prefix matching in FTS search: 1 = enabled, 0 = disabled"},{"name":"instock","in":"query","required":false,"schema":{"type":"integer","description":"Return only products in stock: 1 = only in stock, 0 = all products","default":0,"title":"Instock"},"description":"Return only products in stock: 1 = only in stock, 0 = all products"}],"responses":{"200":{"description":"Keyword search response with lightweight product result items","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"x-ai-guidance":{"recommended_for":["exact sku","exact product name","literal text search","short catalog query"],"not_recommended_for":["natural language intent","purpose-based search","descriptive user request"],"follow_up_endpoint":"/api/item/{sku}"}}},"/api/semantic-search":{"get":{"tags":["Search"],"summary":"Semantic search: natural language, intent, purpose, descriptive query","description":"Semantic product search endpoint based on embeddings.\n\nFor external AI agents:\nUse this endpoint when the user query is:\n- natural-language\n- descriptive\n- purpose-based\n- intent-based\n- not tied to a known exact SKU or exact product name\n\nBest query examples:\n- `клей для плитки для ванной`\n- `инструмент для сверления бетона`\n- `чем утеплить стену`\n- `саморезы для металла`\n- `что использовать для монтажа гипсокартона`\n\nDo not use as the first choice when a strict exact match is required.\nExamples better suited for `/api/search`:\n- `CM11`\n- `GBH 2-26`\n- `Makita HR2470`\n- exact product name lookups\n\nResponse logic:\nReturns a JSON object with:\n- original query\n- `search_type = \"semantic\"`\n- result count\n- result items\n\nThis endpoint is designed to interpret the meaning of the query, not only exact token matches.\n\nRecommended integration flow for AI agents:\n1. Call `/api/semantic-search?q=...`\n2. Read `items`\n3. Take `sku`\n4. Call `/api/item/{sku}` for a full product card if needed\n\nPractical recommendation:\nIf the client does not know whether the user query is exact or semantic,\nprefer implementing an external decision rule such as:\n- short exact / SKU-like query -> `/api/search`\n- descriptive / natural-language query -> `/api/semantic-search`","operationId":"api_semantic_search_api_semantic_search_get","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1,"description":"Natural-language product query for semantic search","examples":["клей для плитки для ванной","инструмент для сверления бетона","чем утеплить стену"],"title":"Q"},"description":"Natural-language product query for semantic search"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum number of products to return","default":20,"title":"Limit"},"description":"Maximum number of products to return"},{"name":"min_score","in":"query","required":false,"schema":{"type":"number","minimum":0.0,"description":"Minimum semantic similarity threshold","default":0.2,"title":"Min Score"},"description":"Minimum semantic similarity threshold"}],"responses":{"200":{"description":"Semantic search response with lightweight product result items","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"x-ai-guidance":{"recommended_for":["natural language search","purpose-based product search","descriptive query","query by meaning"],"not_recommended_for":["exact sku","strict model code lookup","exact literal product name only"],"follow_up_endpoint":"/api/item/{sku}"}}},"/api/analog-search":{"get":{"tags":["Search"],"summary":"Analog search by product group and key attributes","description":"Returns analog products for the best matched catalog item.\n\nLogic:\n- first finds the most relevant base product for the query\n- then selects other items from the same analog group\n- ranks them by similarity of brand, material, product type, size, volume, price, and stock\n\nUse this endpoint only when the client explicitly asks to see analogs or replacements.\nDo not use it as the default primary search.","operationId":"api_analog_search_api_analog_search_get","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1,"description":"Query or SKU used to find a base product and then return analogs","examples":["смеситель haiba","перфоратор crown","4066490"],"title":"Q"},"description":"Query or SKU used to find a base product and then return analogs"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum number of analog items to return","default":20,"title":"Limit"},"description":"Maximum number of analog items to return"},{"name":"instock","in":"query","required":false,"schema":{"type":"integer","description":"Return only analogs in stock: 1 = only in stock, 0 = all products","default":1,"title":"Instock"},"description":"Return only analogs in stock: 1 = only in stock, 0 = all products"}],"responses":{"200":{"description":"Analog search response with similar products","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/item/{sku}":{"get":{"tags":["Items"],"summary":"Get full product card by known SKU","description":"Returns a full product card for one known SKU.\n\nFor external AI agents:\nUse this endpoint when:\n- a search endpoint already returned a `sku`\n- full product details are needed\n- the client needs the canonical product object\n\nRecommended flow:\n1. Search first using `/api/search` or `/api/semantic-search`\n2. Take the `sku` from search results\n3. Call `/api/item/{sku}`\n\nDo not use for general product search.\nThis endpoint is not intended to find products by free text.\nIt is intended to retrieve a single product by exact SKU.","operationId":"api_item_api_item__sku__get","parameters":[{"name":"sku","in":"path","required":true,"schema":{"type":"string","description":"Exact product SKU / article","examples":["CM11","GBH226"],"title":"Sku"},"description":"Exact product SKU / article"}],"responses":{"200":{"description":"Full product card for one SKU","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"x-ai-guidance":{"recommended_for":["full product retrieval","post-search product details","canonical product card access"],"requires":["sku"]}}},"/api/search-suggest":{"get":{"tags":["Search"],"summary":"Autocomplete suggestions only, not final product search","description":"Autocomplete suggestions endpoint.\n\nFor external AI agents:\nUse this endpoint only when building:\n- autosuggest\n- typeahead\n- live query completion\n- UI input assistance\n\nWhat it returns:\nThis endpoint returns suggestion strings, not final ranked product cards.\n\nDo not use as the main search function.\nFor final product retrieval, use:\n- `/api/search`\n- `/api/semantic-search`\n\nExample use case:\nUser typed:\n- `кле`\n- `перф`\n- `самор`\n\nThen the client may call `/api/search-suggest` to propose likely completions.","operationId":"api_search_suggest_api_search_suggest_get","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1,"description":"User input prefix for autocomplete suggestions","examples":["кле","перф","самор"],"title":"Q"},"description":"User input prefix for autocomplete suggestions"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"description":"Maximum number of suggestions to return","default":10,"title":"Limit"},"description":"Maximum number of suggestions to return"}],"responses":{"200":{"description":"Autocomplete suggestion strings","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"x-ai-guidance":{"recommended_for":["autocomplete","query suggestion","typeahead ui"],"not_recommended_for":["final product search","product ranking","semantic intent retrieval"]}}},"/api/popular-searches":{"get":{"tags":["Search"],"summary":"Popular successful search queries for homepage suggestions","description":"Returns a list of popular recent search queries that produced results.\n\nPurpose:\n- show real user queries on the homepage\n- improve search engagement\n- expose only successful searches where results_count > 0\n\nFiltering logic:\n- only queries with results_count > 0\n- ignores empty and too short queries\n- can be limited by recent period in days\n\nFor UI clients:\nUse this endpoint to render clickable search chips under the main search bar.\nThis is not a product card endpoint.","operationId":"api_popular_searches_api_popular_searches_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"description":"Maximum number of queries to return","default":10,"title":"Limit"},"description":"Maximum number of queries to return"},{"name":"days","in":"query","required":false,"schema":{"type":"integer","maximum":365,"minimum":1,"description":"Analyze only this recent number of days","default":30,"title":"Days"},"description":"Analyze only this recent number of days"},{"name":"min_len","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Minimum trimmed query length","default":3,"title":"Min Len"},"description":"Minimum trimmed query length"}],"responses":{"200":{"description":"Popular successful search queries","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"x-ai-guidance":{"recommended_for":["homepage popular queries","ui search chips","analytics-driven query suggestions"],"not_recommended_for":["final product search","single product retrieval"]}}},"/api/search-history":{"get":{"tags":["Service"],"summary":"Recent search history summary for diagnostics and analytics","description":"Service / analytics endpoint.\n\nFor external AI agents:\nThis endpoint is not intended as a product search function.\n\nUse only when:\n- diagnostics are needed\n- search analytics are needed\n- admin/service integration is needed\n\nDo not use for product retrieval.","operationId":"api_search_history_api_search_history_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"description":"Maximum number of recent search history records to return","default":10,"title":"Limit"},"description":"Maximum number of recent search history records to return"}],"responses":{"200":{"description":"Recent search history summary","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"x-ai-guidance":{"category":"service","not_a_product_search_endpoint":true}}},"/":{"get":{"summary":"Home","operationId":"home__get","parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string","default":"","title":"Q"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":20,"title":"Limit"}},{"name":"prefix","in":"query","required":false,"schema":{"type":"integer","default":0,"title":"Prefix"}},{"name":"instock","in":"query","required":false,"schema":{"type":"integer","default":0,"title":"Instock"}},{"name":"analog","in":"query","required":false,"schema":{"type":"integer","default":0,"title":"Analog"}}],"responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/analogs":{"get":{"summary":"Analogs Page","operationId":"analogs_page_analogs_get","parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string","default":"","title":"Q"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":20,"title":"Limit"}},{"name":"instock","in":"query","required":false,"schema":{"type":"integer","default":0,"title":"Instock"}}],"responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/item/{sku}":{"get":{"summary":"Item Card","operationId":"item_card_item__sku__get","parameters":[{"name":"sku","in":"path","required":true,"schema":{"type":"string","title":"Sku"}}],"responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/catalog":{"get":{"summary":"Catalog Root","operationId":"catalog_root_catalog_get","responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}}}}},"/catalog/{node_id}":{"get":{"summary":"Catalog Node Page","operationId":"catalog_node_page_catalog__node_id__get","parameters":[{"name":"node_id","in":"path","required":true,"schema":{"type":"integer","title":"Node Id"}},{"name":"instock","in":"query","required":false,"schema":{"type":"integer","default":0,"title":"Instock"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":60,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"text/html":{"schema":{"type":"string"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"Body_cart_add_cart_add_post":{"properties":{"sku":{"type":"string","title":"Sku"},"qty":{"type":"integer","title":"Qty","default":1},"next":{"type":"string","title":"Next","description":"Куда вернуться после добавления","default":"/"}},"type":"object","required":["sku"],"title":"Body_cart_add_cart_add_post"},"Body_cart_clear_cart_clear_post":{"properties":{"next":{"type":"string","title":"Next","default":"/cart"}},"type":"object","title":"Body_cart_clear_cart_clear_post"},"Body_cart_inc_cart_inc_post":{"properties":{"sku":{"type":"string","title":"Sku"},"delta":{"type":"integer","title":"Delta","default":1},"next":{"type":"string","title":"Next","default":"/cart"}},"type":"object","required":["sku"],"title":"Body_cart_inc_cart_inc_post"},"Body_cart_remove_cart_remove_post":{"properties":{"sku":{"type":"string","title":"Sku"},"next":{"type":"string","title":"Next","default":"/cart"}},"type":"object","required":["sku"],"title":"Body_cart_remove_cart_remove_post"},"Body_cart_set_cart_set_post":{"properties":{"sku":{"type":"string","title":"Sku"},"qty":{"type":"integer","title":"Qty"},"next":{"type":"string","title":"Next","default":"/cart"}},"type":"object","required":["sku","qty"],"title":"Body_cart_set_cart_set_post"},"Body_checkout_submit_checkout_post":{"properties":{"phone":{"type":"string","title":"Phone","default":""},"name":{"type":"string","title":"Name","default":""},"delivery_type":{"type":"string","title":"Delivery Type","default":"Самовывоз"},"address":{"type":"string","title":"Address","default":""},"comment":{"type":"string","title":"Comment","default":""}},"type":"object","title":"Body_checkout_submit_checkout_post"},"Body_quick_order_quick_order_post":{"properties":{"sku":{"type":"string","title":"Sku"},"qty":{"type":"integer","title":"Qty","default":1}},"type":"object","required":["sku"],"title":"Body_quick_order_quick_order_post"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}