{"openapi":"3.1.0","info":{"title":"RunningShoesHQ Public API","version":"1.0.0","description":"Read-only access to the published running-shoe catalogue. Values are time-sensitive: check each shoe page's last-verified date and sources before making a purchase recommendation, and do not present editorial verdicts as manufacturer facts.","contact":{"url":"https://runningshoeshq.com/"}},"servers":[{"url":"https://runningshoeshq.com"}],"paths":{"/api/shoes":{"get":{"operationId":"listPublishedShoes","summary":"List published shoes (paginated)","description":"Returns published shoes only, in a stable brand-interleaved browse order. Page by increasing `offset`; `limit` is capped at 100.","parameters":[{"name":"limit","in":"query","required":false,"description":"Page size, 1–100 (default 24). Values are clamped, not rejected.","schema":{"type":"integer","minimum":1,"maximum":100,"default":24}},{"name":"offset","in":"query","required":false,"description":"Number of shoes to skip (default 0).","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"A page of published shoes.","content":{"application/json":{"schema":{"type":"object","required":["shoes","total"],"properties":{"shoes":{"type":"array","items":{"type":"object","description":"A published running-shoe version, flattened for the catalogue UI. Facts (weight, stack, drop, plate, price) are sourced and dated; editorial fields such as `verdict` are labelled opinion, not measurement.","required":["id","slug","name","brand","price","weightGrams"],"properties":{"id":{"type":"integer","description":"Stable numeric id (also used by favourites)."},"slug":{"type":"string","description":"Public URL slug: /shoes/{slug}."},"name":{"type":"string"},"brand":{"type":"string"},"url":{"type":"string","format":"uri","description":"Manufacturer product page."},"releaseYear":{"type":"integer"},"imageUrl":{"type":"string","format":"uri"},"description":{"type":"string"},"terrain":{"type":"string","enum":["road","trail","hybrid"]},"lugDepthMm":{"type":["number","null"]},"weightGrams":{"type":"number"},"gender":{"type":"string","enum":["Men","Women","Unisex"]},"heelToToeDropMm":{"type":"number"},"stackHeelMm":{"type":["number","null"]},"stackForefootMm":{"type":["number","null"]},"cushionLevel":{"type":["string","null"],"enum":["minimal","low","moderate","high","max",null]},"firmness":{"type":["string","null"]},"stability":{"type":["string","null"]},"plateType":{"type":["string","null"]},"waterproof":{"type":"boolean"},"carbonPlate":{"type":"boolean"},"rockPlate":{"type":"boolean"},"midsoleMaterial":{"type":["string","null"]},"outsoleMaterial":{"type":["string","null"]},"upperMaterial":{"type":["string","null"]},"primaryUse":{"type":"string"},"useCase":{"type":"string"},"raceDistance":{"type":["string","null"],"enum":["short","marathon","ultra",null]},"alsoGoodFor":{"type":"array","items":{"type":"string"}},"price":{"type":"number","description":"MSRP in `priceCurrency`."},"priceCurrency":{"type":["string","null"],"description":"ISO 4217 code."},"widthOptions":{"type":"array","items":{"type":"string","enum":["standard","wide","extra-wide"]}},"verdict":{"type":["string","null"],"description":"Editorial one-liner (opinion)."}}}},"total":{"type":"integer","description":"Total published shoes across all pages."}}}}}},"500":{"description":"The catalogue could not be read.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"hint":{"type":"string","description":"How to recover from this error."}}}}}}}}}}}},"components":{"schemas":{"Shoe":{"type":"object","description":"A published running-shoe version, flattened for the catalogue UI. Facts (weight, stack, drop, plate, price) are sourced and dated; editorial fields such as `verdict` are labelled opinion, not measurement.","required":["id","slug","name","brand","price","weightGrams"],"properties":{"id":{"type":"integer","description":"Stable numeric id (also used by favourites)."},"slug":{"type":"string","description":"Public URL slug: /shoes/{slug}."},"name":{"type":"string"},"brand":{"type":"string"},"url":{"type":"string","format":"uri","description":"Manufacturer product page."},"releaseYear":{"type":"integer"},"imageUrl":{"type":"string","format":"uri"},"description":{"type":"string"},"terrain":{"type":"string","enum":["road","trail","hybrid"]},"lugDepthMm":{"type":["number","null"]},"weightGrams":{"type":"number"},"gender":{"type":"string","enum":["Men","Women","Unisex"]},"heelToToeDropMm":{"type":"number"},"stackHeelMm":{"type":["number","null"]},"stackForefootMm":{"type":["number","null"]},"cushionLevel":{"type":["string","null"],"enum":["minimal","low","moderate","high","max",null]},"firmness":{"type":["string","null"]},"stability":{"type":["string","null"]},"plateType":{"type":["string","null"]},"waterproof":{"type":"boolean"},"carbonPlate":{"type":"boolean"},"rockPlate":{"type":"boolean"},"midsoleMaterial":{"type":["string","null"]},"outsoleMaterial":{"type":["string","null"]},"upperMaterial":{"type":["string","null"]},"primaryUse":{"type":"string"},"useCase":{"type":"string"},"raceDistance":{"type":["string","null"],"enum":["short","marathon","ultra",null]},"alsoGoodFor":{"type":"array","items":{"type":"string"}},"price":{"type":"number","description":"MSRP in `priceCurrency`."},"priceCurrency":{"type":["string","null"],"description":"ISO 4217 code."},"widthOptions":{"type":"array","items":{"type":"string","enum":["standard","wide","extra-wide"]}},"verdict":{"type":["string","null"],"description":"Editorial one-liner (opinion)."}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable explanation."},"hint":{"type":"string","description":"How to recover from this error."}}}}}}}}