{"openapi":"3.1.0","info":{"title":"Product Link Expander API","version":"1.0.0","description":"Expands supported retail short and product URLs, returning the final URL, canonical product URL, item ID, redirect chain, and metadata when available."},"externalDocs":{"description":"Privacy Policy","url":"https://amazon-expander.ccdesign.workers.dev/privacy"},"servers":[{"url":"https://amazon-expander.ccdesign.workers.dev"}],"paths":{"/expand":{"get":{"operationId":"expandProductLink","summary":"Expand a product link","description":"Resolve a supported HTTPS retail short or product URL.","parameters":[{"name":"url","in":"query","required":true,"description":"The supported retail short or product URL to expand.","schema":{"type":"string","format":"uri","examples":["https://a.co/d/0d9FdKEj"]}}],"responses":{"200":{"description":"Product URL expanded successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExpandSuccess"}}}},"400":{"description":"The request URL is missing, invalid, or not allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExpandFailure"}}}},"502":{"description":"Retail redirect or fetch handling failed upstream.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExpandFailure"}}}}}},"post":{"operationId":"expandProductLinkFromJson","summary":"Expand a product link from JSON","description":"Resolve a supported HTTPS product URL from a JSON request body.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"additionalProperties":false,"properties":{"url":{"type":"string","format":"uri","examples":["https://a.co/d/0d9FdKEj"]}}}}}},"responses":{"200":{"description":"Product URL expanded successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExpandSuccess"}}}},"400":{"description":"The request URL is missing, invalid, or not allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExpandFailure"}}}},"502":{"description":"Retail redirect or fetch handling failed upstream.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExpandFailure"}}}}}}},"/supported":{"get":{"operationId":"listSupportedRetailers","summary":"List supported retailers","description":"Return the supported retail product-link domains and item ID types.","responses":{"200":{"description":"Supported retailers listed successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupportedRetailersResponse"},"examples":{"current":{"value":{"retailers":[{"id":"amazon","name":"Amazon","hosts":["a.co","amzn.to","amazon.com","www.amazon.com"],"item_id_type":"ASIN","example_url":"https://www.amazon.com/dp/B0ABCDEF12"},{"id":"walmart","name":"Walmart","hosts":["walmart.com","www.walmart.com","walmrt.us"],"item_id_type":"Walmart item ID","example_url":"https://www.walmart.com/ip/Example-Product/123456789"},{"id":"target","name":"Target","hosts":["target.com","www.target.com","tgt.biz"],"item_id_type":"TCIN","example_url":"https://www.target.com/p/example/-/A-87654321"},{"id":"bestbuy","name":"Best Buy","hosts":["bestbuy.com","www.bestbuy.com","bby.me"],"item_id_type":"SKU","example_url":"https://www.bestbuy.com/site/example/6543210.p"},{"id":"ebay","name":"eBay","hosts":["ebay.com","www.ebay.com","ebay.us"],"item_id_type":"eBay item ID","example_url":"https://www.ebay.com/itm/112233445566"},{"id":"etsy","name":"Etsy","hosts":["etsy.com","www.etsy.com","etsy.me"],"item_id_type":"Etsy listing ID","example_url":"https://www.etsy.com/listing/123456789/example"},{"id":"homedepot","name":"Home Depot","hosts":["homedepot.com","www.homedepot.com","thd.co"],"item_id_type":"Home Depot item ID","example_url":"https://www.homedepot.com/p/example/ABCD1234"},{"id":"lowes","name":"Lowe's","hosts":["lowes.com","www.lowes.com","low.es"],"item_id_type":"Lowe's item ID","example_url":"https://www.lowes.com/pd/example/5012345679"},{"id":"aliexpress","name":"AliExpress","hosts":["aliexpress.com","www.aliexpress.com","a.aliexpress.com","s.click.aliexpress.com"],"item_id_type":"AliExpress item ID","example_url":"https://www.aliexpress.com/item/1005001234567890.html"},{"id":"temu","name":"Temu","hosts":["temu.com","www.temu.com","share.temu.com"],"item_id_type":"Temu goods ID","example_url":"https://www.temu.com/example-g-601099512345678.html"},{"id":"costco","name":"Costco","hosts":["costco.com","www.costco.com"],"item_id_type":"Costco item ID","example_url":"https://www.costco.com/example.product.100123456.html"},{"id":"samsclub","name":"Sam's Club","hosts":["samsclub.com","www.samsclub.com"],"item_id_type":"Sam's Club product ID","example_url":"https://www.samsclub.com/p/example/prod12345678"},{"id":"wayfair","name":"Wayfair","hosts":["wayfair.com","www.wayfair.com"],"item_id_type":"Wayfair SKU","example_url":"https://www.wayfair.com/furniture/pdp/example-w005123456.html"},{"id":"chewy","name":"Chewy","hosts":["chewy.com","www.chewy.com"],"item_id_type":"Chewy product ID","example_url":"https://www.chewy.com/example/dp/123456"},{"id":"sephora","name":"Sephora","hosts":["sephora.com","www.sephora.com"],"item_id_type":"Sephora product ID","example_url":"https://www.sephora.com/product/example-P123456"},{"id":"ulta","name":"Ulta Beauty","hosts":["ulta.com","www.ulta.com"],"item_id_type":"Ulta product ID","example_url":"https://www.ulta.com/p/example-pimprod2031234"},{"id":"macys","name":"Macy's","hosts":["macys.com","www.macys.com"],"item_id_type":"Macy's product ID","example_url":"https://www.macys.com/shop/product/example?ID=1234567"},{"id":"kohls","name":"Kohl's","hosts":["kohls.com","www.kohls.com"],"item_id_type":"Kohl's product ID","example_url":"https://www.kohls.com/product/prd-1234567/example.jsp"},{"id":"nordstrom","name":"Nordstrom","hosts":["nordstrom.com","www.nordstrom.com"],"item_id_type":"Nordstrom style ID","example_url":"https://www.nordstrom.com/s/example/1234567"},{"id":"rei","name":"REI","hosts":["rei.com","www.rei.com"],"item_id_type":"REI product ID","example_url":"https://www.rei.com/product/123456/example"},{"id":"nike","name":"Nike","hosts":["nike.com","www.nike.com"],"item_id_type":"Nike style code","example_url":"https://www.nike.com/t/example/HJ1234-001"},{"id":"adidas","name":"Adidas","hosts":["adidas.com","www.adidas.com"],"item_id_type":"Adidas product code","example_url":"https://www.adidas.com/us/example/IE1234.html"},{"id":"stockx","name":"StockX","hosts":["stockx.com","www.stockx.com"],"item_id_type":"StockX product slug","example_url":"https://stockx.com/example-product"}]}}}}}}}}}},"components":{"schemas":{"RedirectHop":{"type":"object","required":["url","status","location"],"properties":{"url":{"type":"string"},"status":{"type":"integer"},"location":{"type":["string","null"]}}},"ExpandSuccess":{"type":"object","required":["input","ok","final_url","clean_final_url","canonical_url","retailer","item_id","item_id_type","asin","title","description","image_url","confidence","redirect_count","chain","warnings","warning_codes"],"properties":{"input":{"type":"string"},"ok":{"type":"boolean","const":true},"final_url":{"type":"string"},"clean_final_url":{"type":["string","null"]},"canonical_url":{"type":["string","null"]},"retailer":{"type":["string","null"]},"item_id":{"type":["string","null"]},"item_id_type":{"type":["string","null"]},"asin":{"type":["string","null"]},"title":{"type":["string","null"]},"description":{"type":["string","null"]},"image_url":{"type":["string","null"]},"confidence":{"type":"string","enum":["high","medium","low"]},"redirect_count":{"type":"integer"},"chain":{"type":"array","items":{"$ref":"#/components/schemas/RedirectHop"}},"warnings":{"type":"array","items":{"type":"string"}},"warning_codes":{"type":"array","items":{"type":"string"}}}},"ExpandFailure":{"type":"object","required":["input","ok","error","final_url","clean_final_url","canonical_url","retailer","item_id","item_id_type","asin","description","image_url","confidence","chain","warnings","warning_codes"],"properties":{"input":{"type":"string"},"ok":{"type":"boolean","const":false},"error":{"type":"string"},"final_url":{"type":"null"},"clean_final_url":{"type":"null"},"canonical_url":{"type":"null"},"retailer":{"type":"null"},"item_id":{"type":"null"},"item_id_type":{"type":"null"},"asin":{"type":"null"},"description":{"type":"null"},"image_url":{"type":"null"},"confidence":{"type":"string","const":"low"},"chain":{"type":"array","items":{"$ref":"#/components/schemas/RedirectHop"}},"warnings":{"type":"array","items":{"type":"string"}},"warning_codes":{"type":"array","items":{"type":"string"}}}},"SupportedRetailer":{"type":"object","required":["id","name","hosts","item_id_type","example_url"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"hosts":{"type":"array","items":{"type":"string"}},"item_id_type":{"type":"string"},"example_url":{"type":"string","format":"uri"}}},"SupportedRetailersResponse":{"type":"object","required":["retailers"],"properties":{"retailers":{"type":"array","items":{"$ref":"#/components/schemas/SupportedRetailer"}}}}}}}