{"openapi":"3.1.0","info":{"title":"KazGroupMetal public catalog API","version":"1.0.0","description":"Read-only metal catalog, Almaty, Kazakhstan. No API key. Version v1 uses /api/v1/catalog. Breaking changes get a new URL version; additive fields may appear in v1. Deprecation notices will be published at /developers; a scheduled removal will use Deprecation and Sunset headers. No v1 removal is scheduled. Prices and stock require manager confirmation.","contact":{"email":"info@kazgroupmetal.kz","url":"https://kazgroupmetal.kz/contacts"}},"servers":[{"url":"https://kazgroupmetal.kz"}],"security":[],"externalDocs":{"description":"Quickstart, accuracy, versioning, errors and retry guidance","url":"https://kazgroupmetal.kz/developers"},"paths":{"/catalog/categories.json":{"get":{"operationId":"listCategoriesForWeb","summary":"List published category slugs and counts","description":"Preferred public address for direct web reading in ChatGPT and Claude. Same data as the v1 endpoint.","responses":{"200":{"description":"Published categories","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CategoryList"}}}},"405":{"description":"Use GET or HEAD","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/catalog/search.json":{"get":{"operationId":"searchProductsForWeb","summary":"Find products by words and exact specifications","description":"Preferred public address for direct web reading. Use Russian product names in q. Same filters, pagination and data as v1.","parameters":[{"name":"q","in":"query","schema":{"type":"string","maxLength":200},"description":"Russian names, size strings and steel grades; all words match. Bare numbers match size. Examples: арматура 16; арматура А500С 12 мм; труба 80x40x3; ГОСТ 8240."},{"name":"category","in":"query","schema":{"type":"string"},"description":"Exact slug returned by listCategories"},{"name":"steel","in":"query","schema":{"type":"string","maxLength":100},"description":"Steel grade words"},{"name":"standard","in":"query","schema":{"type":"string","maxLength":100},"description":"Standard or GOST words"},{"name":"diameter","in":"query","schema":{"type":"number","exclusiveMinimum":0,"maximum":100000},"description":"Exact dimension in millimetres; a range of cut lengths is null"},{"name":"thickness","in":"query","schema":{"type":"number","exclusiveMinimum":0,"maximum":100000},"description":"Exact dimension in millimetres; a range of cut lengths is null"},{"name":"width","in":"query","schema":{"type":"number","exclusiveMinimum":0,"maximum":100000},"description":"Exact dimension in millimetres; a range of cut lengths is null"},{"name":"length","in":"query","schema":{"type":"number","exclusiveMinimum":0,"maximum":100000},"description":"Exact dimension in millimetres; a range of cut lengths is null"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":10},"description":"Products per response"},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"maximum":100000,"default":0},"description":"Zero-based offset"}],"responses":{"200":{"description":"Matches; total: 0 is a valid empty result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResults"}}}},"400":{"description":"Invalid filter or pagination; correct the parameter from detail","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"405":{"description":"Use GET or HEAD","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/catalog/products/{slug}.json":{"get":{"operationId":"getProductForWeb","summary":"Read a published product and its canonical source URL","description":"Preferred public address for direct web reading in ChatGPT and Claude. Returns the same published product as v1.","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9-]+$"}}],"responses":{"200":{"description":"Product and its published description","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductDetails"}}}},"404":{"description":"Product is missing or hidden; search for a valid slug","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"405":{"description":"Use GET or HEAD","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v1/catalog/categories":{"get":{"operationId":"listCategories","summary":"List published category slugs and counts","description":"Choose an exact category slug before searching.","responses":{"200":{"description":"Published categories","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CategoryList"}}}},"405":{"description":"Use GET or HEAD","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v1/catalog/search":{"get":{"operationId":"searchProducts","summary":"Find products by words and exact specifications","description":"All query words must match. Bare numbers match the product size, not cut lengths, steel-grade digits or standard years. Dimension tuples compare complete numbers, so 80x40x3 does not match 80x40x3.5. Use ГОСТ before a bare standard number. Explicit metre units search cut lengths. Missing numeric fields do not match dimension filters. Follow next until null. Product existence does not confirm stock.","parameters":[{"name":"q","in":"query","schema":{"type":"string","maxLength":200},"description":"Russian names, size strings and steel grades; all words match. Bare numbers match size. Examples: арматура 16; арматура А500С 12 мм; труба 80x40x3; ГОСТ 8240."},{"name":"category","in":"query","schema":{"type":"string"},"description":"Exact slug returned by listCategories"},{"name":"steel","in":"query","schema":{"type":"string","maxLength":100},"description":"Steel grade words"},{"name":"standard","in":"query","schema":{"type":"string","maxLength":100},"description":"Standard or GOST words"},{"name":"diameter","in":"query","schema":{"type":"number","exclusiveMinimum":0,"maximum":100000},"description":"Exact dimension in millimetres; a range of cut lengths is null"},{"name":"thickness","in":"query","schema":{"type":"number","exclusiveMinimum":0,"maximum":100000},"description":"Exact dimension in millimetres; a range of cut lengths is null"},{"name":"width","in":"query","schema":{"type":"number","exclusiveMinimum":0,"maximum":100000},"description":"Exact dimension in millimetres; a range of cut lengths is null"},{"name":"length","in":"query","schema":{"type":"number","exclusiveMinimum":0,"maximum":100000},"description":"Exact dimension in millimetres; a range of cut lengths is null"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":10},"description":"Products per response"},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"maximum":100000,"default":0},"description":"Zero-based offset"}],"responses":{"200":{"description":"Matches; total: 0 is a valid empty result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResults"}}}},"400":{"description":"Invalid filter or pagination; correct the parameter from detail","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"405":{"description":"Use GET or HEAD","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/v1/catalog/products/{slug}":{"get":{"operationId":"getProduct","summary":"Read a published product and its canonical source URL","description":"Includes current published content, sections and FAQs. Drafts are excluded. Numeric length is null for multiple options; read cutLength.","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9-]+$"}}],"responses":{"200":{"description":"Product and its published description","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductDetails"}}}},"404":{"description":"Product is missing or hidden; search for a valid slug","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"405":{"description":"Use GET or HEAD","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/catalog.json":{"get":{"operationId":"downloadCatalog","summary":"Download the complete legacy JSON catalog","description":"Larger original export. Use the v1 search and product endpoints for normalized millimetres and published product text.","responses":{"200":{"description":"Public catalog export","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogExport"}}}}}}}},"components":{"schemas":{"AccuracyPolicy":{"type":"object","properties":{"price":{"type":"string"},"availability":{"type":"string"},"images":{"type":"string"}},"required":["price","availability","images"]},"CatalogLink":{"type":"object","properties":{"rel":{"type":"string","enum":["self","item","next"]},"href":{"type":"string","format":"uri"},"type":{"type":"string","const":"application/json"},"title":{"type":"string"}},"required":["rel","href","type"]},"Product":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"url":{"type":"string","format":"uri"},"dataUrl":{"type":"string","format":"uri","description":"Follow this exact public JSON URL from search results; do not guess a URL from the name."},"category":{"type":"string"},"size":{"type":"string"},"cutLength":{"type":["string","null"]},"steel":{"type":"string"},"standard":{"type":"string"},"unit":{"type":"string"},"price":{"type":"null","description":"Not published. Request a quotation; null never means free."},"availability":{"type":"string","const":"Подтверждается менеджером"},"updatedAt":{"type":"string"},"dimensionsMm":{"type":"object","properties":{"thickness":{"type":["number","null"]},"width":{"type":["number","null"]},"length":{"type":["number","null"]},"diameter":{"type":["number","null"]}},"required":["thickness","width","length","diameter"]},"image":{"type":"string","format":"uri"}},"required":["id","slug","name","url","dataUrl","category","size","cutLength","steel","standard","unit","price","availability","updatedAt","dimensionsMm","image"]},"ProductDetails":{"type":"object","properties":{"schemaVersion":{"type":"string"},"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"url":{"type":"string","format":"uri"},"dataUrl":{"type":"string","format":"uri","description":"Follow this exact public JSON URL from search results; do not guess a URL from the name."},"category":{"type":"string"},"size":{"type":"string"},"cutLength":{"type":["string","null"]},"steel":{"type":"string"},"standard":{"type":"string"},"unit":{"type":"string"},"price":{"type":"null","description":"Not published. Request a quotation; null never means free."},"availability":{"type":"string","const":"Подтверждается менеджером"},"updatedAt":{"type":"string"},"dimensionsMm":{"type":"object","properties":{"thickness":{"type":["number","null"]},"width":{"type":["number","null"]},"length":{"type":["number","null"]},"diameter":{"type":["number","null"]}},"required":["thickness","width","length","diameter"]},"image":{"type":"string","format":"uri"},"description":{"type":"string"},"application":{"type":"string"},"delivery":{"type":"string"},"sections":{"type":"array","items":{"type":"object","properties":{"heading":{"type":"string"},"text":{"type":"string"}},"required":["heading","text"]}},"faqs":{"type":"array","items":{"type":"object","properties":{"question":{"type":"string"},"answer":{"type":"string"}},"required":["question","answer"]}},"contentUpdatedAt":{"type":"string"},"accuracyPolicy":{"$ref":"#/components/schemas/AccuracyPolicy"}},"required":["schemaVersion","id","slug","name","url","dataUrl","category","size","cutLength","steel","standard","unit","price","availability","updatedAt","dimensionsMm","image","description","application","delivery","sections","faqs","contentUpdatedAt","accuracyPolicy"]},"Category":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"url":{"type":"string","format":"uri"},"productCount":{"type":"integer"}},"required":["slug","name","description","url","productCount"]},"CategoryList":{"type":"object","properties":{"schemaVersion":{"type":"string"},"categories":{"type":"array","items":{"$ref":"#/components/schemas/Category"}}},"required":["schemaVersion","categories"]},"SearchResults":{"type":"object","properties":{"schemaVersion":{"type":"string"},"query":{"type":"string"},"total":{"type":"integer"},"offset":{"type":"integer"},"limit":{"type":"integer"},"next":{"type":["string","null"]},"browseUrl":{"type":"string","format":"uri","description":"HTML search with the same filters and ordinary product links. Preferred for web readers that cannot follow URLs inside JSON."},"links":{"type":"array","items":{"$ref":"#/components/schemas/CatalogLink"},"description":"Typed JSON navigation: self, item links to product JSON, and optional next page."},"navigation":{"type":"array","items":{"type":"string"},"description":"Markdown-labelled product JSON links inside the JSON document for text readers. API clients can use links or products[].dataUrl."},"accuracyPolicy":{"$ref":"#/components/schemas/AccuracyPolicy"},"products":{"type":"array","items":{"$ref":"#/components/schemas/Product"}}},"required":["schemaVersion","query","total","offset","limit","next","browseUrl","links","navigation","accuracyPolicy","products"]},"CatalogExport":{"type":"object","properties":{"schemaVersion":{"type":"string"},"canonicalUrl":{"type":"string"},"organization":{"type":"object","properties":{"name":{"type":"string"},"legalName":{"type":"string"},"bin":{"type":"string"},"location":{"type":"string"},"serviceArea":{"type":"string"},"phone":{"type":"string"},"email":{"type":"string"},"whatsapp":{"type":"string"},"address":{"type":"string"},"hours":{"type":"string"}},"required":["name","legalName","bin","location","serviceArea","phone","email","whatsapp","address","hours"]},"accuracyPolicy":{"type":"object","properties":{"price":{"type":"string"},"availability":{"type":"string"},"productImages":{"type":"string"},"weightCalculation":{"type":"string"},"projectCalculation":{"type":"string"}},"required":["price","availability","productImages","weightCalculation","projectCalculation"]},"categories":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"url":{"type":"string"},"productCount":{"type":"integer"}},"required":["slug","name","description","url","productCount"]}},"products":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"size":{"type":"string"},"gost":{"type":"string"},"steel":{"type":"string"},"cutLength":{"type":"string"},"url":{"type":"string"},"price":{"type":"null"},"availability":{"type":"string"}},"required":["id","slug","name","size","gost","steel","cutLength","url","price","availability"]}}},"required":["schemaVersion","canonicalUrl","organization","accuracyPolicy","categories","products"]},"Problem":{"type":"object","properties":{"type":{"type":"string"},"code":{"type":"string","enum":["INVALID_ARGUMENT","NOT_FOUND","METHOD_NOT_ALLOWED"]},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"documentation":{"type":"string","format":"uri"}},"required":["type","code","title","status","detail","documentation"]}}}}