{"openapi":"3.1.0","info":{"title":"sneakers.cx API","version":"hybrid-1","description":"Phase 0 foundation. Only existing Shopify storefront behavior is reachable. Alias, retailer identity, retailer asks, median proxy and StockX are locked disabled pending licenses and gates; flags alone cannot enable them. Canonical registry is internal and NON-DURABLE. No market trio is certified. Credits and caches remain per warm instance; errors cost zero."},"servers":[{"url":"https://sneakers.cx"}],"security":[{"bearerAuth":[]}],"paths":{"/v1/health":{"get":{"operationId":"health","summary":"Configured source modes, not an upstream availability check","security":[],"x-request-cost":0,"responses":{"200":{"description":"Process is serving requests","headers":{"X-Sneakers-Request-Id":{"description":"Request correlation UUID","schema":{"type":"string","format":"uuid"}},"X-Sneakers-Request-Cost":{"description":"Credits charged: operation cost on success, zero on failure","schema":{"type":"number"}},"X-Sneakers-Cache-Status":{"description":"hit means unexpired instance memory; live means no cache served","schema":{"type":"string","enum":["live","hit"]}},"X-Sneakers-Rate-Limit-Remaining":{"description":"Remaining monthly instance credits (zero for anonymous requests)","schema":{"type":"number"}},"X-Sneakers-Rate-Limit-Reset":{"description":"UTC month boundary as Unix seconds","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}}},"405":{"description":"GET required","headers":{"X-Sneakers-Request-Id":{"description":"Request correlation UUID","schema":{"type":"string","format":"uuid"}},"X-Sneakers-Request-Cost":{"description":"Credits charged: operation cost on success, zero on failure","schema":{"type":"number"}},"X-Sneakers-Cache-Status":{"description":"hit means unexpired instance memory; live means no cache served","schema":{"type":"string","enum":["live","hit"]}},"X-Sneakers-Rate-Limit-Remaining":{"description":"Remaining monthly instance credits (zero for anonymous requests)","schema":{"type":"number"}},"X-Sneakers-Rate-Limit-Reset":{"description":"UTC month boundary as Unix seconds","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/shopify/search":{"get":{"operationId":"shopify_search","summary":"shopify search","description":"Up to 10 predictive matches; on failure, query-filtered catalog fallback of up to 250 products. Variants may be empty. No catalog completeness guarantee.","tags":["shopify"],"x-request-cost":0.5,"parameters":[{"name":"store","in":"query","required":true,"description":"Public bare domain, e.g. shopnicekicks.com","schema":{"type":"string","minLength":1,"maxLength":253}},{"name":"query","in":"query","required":true,"description":"Search words","schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"include","in":"query","required":false,"schema":{"type":"string"},"description":"Optional comma-separated layers: market.alias, market.stockx, identity.retailers, retailers, proxies.median. These layers are disabled. Each requested missing layer appears in unavailable; no enrichment or additional charge occurs. Unrequested layers are omitted; unknown names report unsupported."}],"responses":{"200":{"description":"Success; instance cache TTL 60s; cache hits cost 0.5 credits","headers":{"X-Sneakers-Request-Id":{"description":"Request correlation UUID","schema":{"type":"string","format":"uuid"}},"X-Sneakers-Request-Cost":{"description":"Credits charged: operation cost on success, zero on failure","schema":{"type":"number"}},"X-Sneakers-Cache-Status":{"description":"hit means unexpired instance memory; live means no cache served","schema":{"type":"string","enum":["live","hit"]}},"X-Sneakers-Rate-Limit-Remaining":{"description":"Remaining monthly instance credits (zero for anonymous requests)","schema":{"type":"number"}},"X-Sneakers-Rate-Limit-Reset":{"description":"UTC month boundary as Unix seconds","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","required":["status","data","contractVersion","unavailable"],"additionalProperties":false,"properties":{"contractVersion":{"const":"hybrid-1"},"unavailable":{"type":"array","items":{"$ref":"#/components/schemas/Unavailable"}},"status":{"const":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}}}}}}},"401":{"description":"Invalid credentials","headers":{"X-Sneakers-Request-Id":{"description":"Request correlation UUID","schema":{"type":"string","format":"uuid"}},"X-Sneakers-Request-Cost":{"description":"Credits charged: operation cost on success, zero on failure","schema":{"type":"number"}},"X-Sneakers-Cache-Status":{"description":"hit means unexpired instance memory; live means no cache served","schema":{"type":"string","enum":["live","hit"]}},"X-Sneakers-Rate-Limit-Remaining":{"description":"Remaining monthly instance credits (zero for anonymous requests)","schema":{"type":"number"}},"X-Sneakers-Rate-Limit-Reset":{"description":"UTC month boundary as Unix seconds","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown endpoint or product","headers":{"X-Sneakers-Request-Id":{"description":"Request correlation UUID","schema":{"type":"string","format":"uuid"}},"X-Sneakers-Request-Cost":{"description":"Credits charged: operation cost on success, zero on failure","schema":{"type":"number"}},"X-Sneakers-Cache-Status":{"description":"hit means unexpired instance memory; live means no cache served","schema":{"type":"string","enum":["live","hit"]}},"X-Sneakers-Rate-Limit-Remaining":{"description":"Remaining monthly instance credits (zero for anonymous requests)","schema":{"type":"number"}},"X-Sneakers-Rate-Limit-Reset":{"description":"UTC month boundary as Unix seconds","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"GET required","headers":{"X-Sneakers-Request-Id":{"description":"Request correlation UUID","schema":{"type":"string","format":"uuid"}},"X-Sneakers-Request-Cost":{"description":"Credits charged: operation cost on success, zero on failure","schema":{"type":"number"}},"X-Sneakers-Cache-Status":{"description":"hit means unexpired instance memory; live means no cache served","schema":{"type":"string","enum":["live","hit"]}},"X-Sneakers-Rate-Limit-Remaining":{"description":"Remaining monthly instance credits (zero for anonymous requests)","schema":{"type":"number"}},"X-Sneakers-Rate-Limit-Reset":{"description":"UTC month boundary as Unix seconds","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid query or nonpublic store","headers":{"X-Sneakers-Request-Id":{"description":"Request correlation UUID","schema":{"type":"string","format":"uuid"}},"X-Sneakers-Request-Cost":{"description":"Credits charged: operation cost on success, zero on failure","schema":{"type":"number"}},"X-Sneakers-Cache-Status":{"description":"hit means unexpired instance memory; live means no cache served","schema":{"type":"string","enum":["live","hit"]}},"X-Sneakers-Rate-Limit-Remaining":{"description":"Remaining monthly instance credits (zero for anonymous requests)","schema":{"type":"number"}},"X-Sneakers-Rate-Limit-Reset":{"description":"UTC month boundary as Unix seconds","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"426":{"description":"Monthly instance credits exhausted","headers":{"X-Sneakers-Request-Id":{"description":"Request correlation UUID","schema":{"type":"string","format":"uuid"}},"X-Sneakers-Request-Cost":{"description":"Credits charged: operation cost on success, zero on failure","schema":{"type":"number"}},"X-Sneakers-Cache-Status":{"description":"hit means unexpired instance memory; live means no cache served","schema":{"type":"string","enum":["live","hit"]}},"X-Sneakers-Rate-Limit-Remaining":{"description":"Remaining monthly instance credits (zero for anonymous requests)","schema":{"type":"number"}},"X-Sneakers-Rate-Limit-Reset":{"description":"UTC month boundary as Unix seconds","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","headers":{"X-Sneakers-Request-Id":{"description":"Request correlation UUID","schema":{"type":"string","format":"uuid"}},"X-Sneakers-Request-Cost":{"description":"Credits charged: operation cost on success, zero on failure","schema":{"type":"number"}},"X-Sneakers-Cache-Status":{"description":"hit means unexpired instance memory; live means no cache served","schema":{"type":"string","enum":["live","hit"]}},"X-Sneakers-Rate-Limit-Remaining":{"description":"Remaining monthly instance credits (zero for anonymous requests)","schema":{"type":"number"}},"X-Sneakers-Rate-Limit-Reset":{"description":"UTC month boundary as Unix seconds","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Source disabled, blocked, malformed, timed out, or misconfigured","headers":{"X-Sneakers-Request-Id":{"description":"Request correlation UUID","schema":{"type":"string","format":"uuid"}},"X-Sneakers-Request-Cost":{"description":"Credits charged: operation cost on success, zero on failure","schema":{"type":"number"}},"X-Sneakers-Cache-Status":{"description":"hit means unexpired instance memory; live means no cache served","schema":{"type":"string","enum":["live","hit"]}},"X-Sneakers-Rate-Limit-Remaining":{"description":"Remaining monthly instance credits (zero for anonymous requests)","schema":{"type":"number"}},"X-Sneakers-Rate-Limit-Reset":{"description":"UTC month boundary as Unix seconds","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/shopify/product":{"get":{"operationId":"shopify_product","summary":"shopify product","description":"Handles try canonical .json first, Ajax .js only after canonical 404, then a 250-product catalog. Numeric IDs try an exact filtered lookup then at most four 250-product since_id pages. Stores may block or ignore filters. Legacy fields and prices unchanged; additive price provenance records unknown dimensions explicitly.","tags":["shopify"],"x-request-cost":0.5,"parameters":[{"name":"store","in":"query","required":true,"description":"Public bare domain, e.g. shopnicekicks.com","schema":{"type":"string","minLength":1,"maxLength":253}},{"name":"id","in":"query","required":true,"description":"Product ID or handle / StockX urlKey","schema":{"type":"string","minLength":1,"maxLength":253}},{"name":"include","in":"query","required":false,"schema":{"type":"string"},"description":"Optional comma-separated layers: market.alias, market.stockx, identity.retailers, retailers, proxies.median. These layers are disabled. Each requested missing layer appears in unavailable; no enrichment or additional charge occurs. Unrequested layers are omitted; unknown names report unsupported."}],"responses":{"200":{"description":"Success; instance cache TTL 120s; cache hits cost 0.5 credits","headers":{"X-Sneakers-Request-Id":{"description":"Request correlation UUID","schema":{"type":"string","format":"uuid"}},"X-Sneakers-Request-Cost":{"description":"Credits charged: operation cost on success, zero on failure","schema":{"type":"number"}},"X-Sneakers-Cache-Status":{"description":"hit means unexpired instance memory; live means no cache served","schema":{"type":"string","enum":["live","hit"]}},"X-Sneakers-Rate-Limit-Remaining":{"description":"Remaining monthly instance credits (zero for anonymous requests)","schema":{"type":"number"}},"X-Sneakers-Rate-Limit-Reset":{"description":"UTC month boundary as Unix seconds","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","required":["status","data","contractVersion","unavailable"],"additionalProperties":false,"properties":{"contractVersion":{"const":"hybrid-1"},"unavailable":{"type":"array","items":{"$ref":"#/components/schemas/Unavailable"}},"status":{"const":true},"data":{"$ref":"#/components/schemas/Product"}}}}}},"401":{"description":"Invalid credentials","headers":{"X-Sneakers-Request-Id":{"description":"Request correlation UUID","schema":{"type":"string","format":"uuid"}},"X-Sneakers-Request-Cost":{"description":"Credits charged: operation cost on success, zero on failure","schema":{"type":"number"}},"X-Sneakers-Cache-Status":{"description":"hit means unexpired instance memory; live means no cache served","schema":{"type":"string","enum":["live","hit"]}},"X-Sneakers-Rate-Limit-Remaining":{"description":"Remaining monthly instance credits (zero for anonymous requests)","schema":{"type":"number"}},"X-Sneakers-Rate-Limit-Reset":{"description":"UTC month boundary as Unix seconds","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown endpoint or product","headers":{"X-Sneakers-Request-Id":{"description":"Request correlation UUID","schema":{"type":"string","format":"uuid"}},"X-Sneakers-Request-Cost":{"description":"Credits charged: operation cost on success, zero on failure","schema":{"type":"number"}},"X-Sneakers-Cache-Status":{"description":"hit means unexpired instance memory; live means no cache served","schema":{"type":"string","enum":["live","hit"]}},"X-Sneakers-Rate-Limit-Remaining":{"description":"Remaining monthly instance credits (zero for anonymous requests)","schema":{"type":"number"}},"X-Sneakers-Rate-Limit-Reset":{"description":"UTC month boundary as Unix seconds","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"GET required","headers":{"X-Sneakers-Request-Id":{"description":"Request correlation UUID","schema":{"type":"string","format":"uuid"}},"X-Sneakers-Request-Cost":{"description":"Credits charged: operation cost on success, zero on failure","schema":{"type":"number"}},"X-Sneakers-Cache-Status":{"description":"hit means unexpired instance memory; live means no cache served","schema":{"type":"string","enum":["live","hit"]}},"X-Sneakers-Rate-Limit-Remaining":{"description":"Remaining monthly instance credits (zero for anonymous requests)","schema":{"type":"number"}},"X-Sneakers-Rate-Limit-Reset":{"description":"UTC month boundary as Unix seconds","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid query or nonpublic store","headers":{"X-Sneakers-Request-Id":{"description":"Request correlation UUID","schema":{"type":"string","format":"uuid"}},"X-Sneakers-Request-Cost":{"description":"Credits charged: operation cost on success, zero on failure","schema":{"type":"number"}},"X-Sneakers-Cache-Status":{"description":"hit means unexpired instance memory; live means no cache served","schema":{"type":"string","enum":["live","hit"]}},"X-Sneakers-Rate-Limit-Remaining":{"description":"Remaining monthly instance credits (zero for anonymous requests)","schema":{"type":"number"}},"X-Sneakers-Rate-Limit-Reset":{"description":"UTC month boundary as Unix seconds","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"426":{"description":"Monthly instance credits exhausted","headers":{"X-Sneakers-Request-Id":{"description":"Request correlation UUID","schema":{"type":"string","format":"uuid"}},"X-Sneakers-Request-Cost":{"description":"Credits charged: operation cost on success, zero on failure","schema":{"type":"number"}},"X-Sneakers-Cache-Status":{"description":"hit means unexpired instance memory; live means no cache served","schema":{"type":"string","enum":["live","hit"]}},"X-Sneakers-Rate-Limit-Remaining":{"description":"Remaining monthly instance credits (zero for anonymous requests)","schema":{"type":"number"}},"X-Sneakers-Rate-Limit-Reset":{"description":"UTC month boundary as Unix seconds","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","headers":{"X-Sneakers-Request-Id":{"description":"Request correlation UUID","schema":{"type":"string","format":"uuid"}},"X-Sneakers-Request-Cost":{"description":"Credits charged: operation cost on success, zero on failure","schema":{"type":"number"}},"X-Sneakers-Cache-Status":{"description":"hit means unexpired instance memory; live means no cache served","schema":{"type":"string","enum":["live","hit"]}},"X-Sneakers-Rate-Limit-Remaining":{"description":"Remaining monthly instance credits (zero for anonymous requests)","schema":{"type":"number"}},"X-Sneakers-Rate-Limit-Reset":{"description":"UTC month boundary as Unix seconds","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Source disabled, blocked, malformed, timed out, or misconfigured","headers":{"X-Sneakers-Request-Id":{"description":"Request correlation UUID","schema":{"type":"string","format":"uuid"}},"X-Sneakers-Request-Cost":{"description":"Credits charged: operation cost on success, zero on failure","schema":{"type":"number"}},"X-Sneakers-Cache-Status":{"description":"hit means unexpired instance memory; live means no cache served","schema":{"type":"string","enum":["live","hit"]}},"X-Sneakers-Rate-Limit-Remaining":{"description":"Remaining monthly instance credits (zero for anonymous requests)","schema":{"type":"number"}},"X-Sneakers-Rate-Limit-Reset":{"description":"UTC month boundary as Unix seconds","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/stockx/search":{"get":{"operationId":"stockx_search","summary":"stockx search","description":"Phase 0 locked disabled: returns the existing zero-cost 503 even if STOCKX_ENABLED is true. No transport is reachable.","tags":["stockx"],"x-request-cost":1,"parameters":[{"name":"query","in":"query","required":true,"description":"Search words","schema":{"type":"string","minLength":1,"maxLength":200}},{"name":"include","in":"query","required":false,"schema":{"type":"string"},"description":"Optional comma-separated layers: market.alias, market.stockx, identity.retailers, retailers, proxies.median. These layers are disabled. Each requested missing layer appears in unavailable; no enrichment or additional charge occurs. Unrequested layers are omitted; unknown names report unsupported."}],"responses":{"200":{"description":"Success; instance cache TTL 60s; cache hits cost 1 credits","headers":{"X-Sneakers-Request-Id":{"description":"Request correlation UUID","schema":{"type":"string","format":"uuid"}},"X-Sneakers-Request-Cost":{"description":"Credits charged: operation cost on success, zero on failure","schema":{"type":"number"}},"X-Sneakers-Cache-Status":{"description":"hit means unexpired instance memory; live means no cache served","schema":{"type":"string","enum":["live","hit"]}},"X-Sneakers-Rate-Limit-Remaining":{"description":"Remaining monthly instance credits (zero for anonymous requests)","schema":{"type":"number"}},"X-Sneakers-Rate-Limit-Reset":{"description":"UTC month boundary as Unix seconds","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","required":["status","data","contractVersion","unavailable"],"additionalProperties":false,"properties":{"contractVersion":{"const":"hybrid-1"},"unavailable":{"type":"array","items":{"$ref":"#/components/schemas/Unavailable"}},"status":{"const":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}}}}}}},"401":{"description":"Invalid credentials","headers":{"X-Sneakers-Request-Id":{"description":"Request correlation UUID","schema":{"type":"string","format":"uuid"}},"X-Sneakers-Request-Cost":{"description":"Credits charged: operation cost on success, zero on failure","schema":{"type":"number"}},"X-Sneakers-Cache-Status":{"description":"hit means unexpired instance memory; live means no cache served","schema":{"type":"string","enum":["live","hit"]}},"X-Sneakers-Rate-Limit-Remaining":{"description":"Remaining monthly instance credits (zero for anonymous requests)","schema":{"type":"number"}},"X-Sneakers-Rate-Limit-Reset":{"description":"UTC month boundary as Unix seconds","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown endpoint or product","headers":{"X-Sneakers-Request-Id":{"description":"Request correlation UUID","schema":{"type":"string","format":"uuid"}},"X-Sneakers-Request-Cost":{"description":"Credits charged: operation cost on success, zero on failure","schema":{"type":"number"}},"X-Sneakers-Cache-Status":{"description":"hit means unexpired instance memory; live means no cache served","schema":{"type":"string","enum":["live","hit"]}},"X-Sneakers-Rate-Limit-Remaining":{"description":"Remaining monthly instance credits (zero for anonymous requests)","schema":{"type":"number"}},"X-Sneakers-Rate-Limit-Reset":{"description":"UTC month boundary as Unix seconds","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"GET required","headers":{"X-Sneakers-Request-Id":{"description":"Request correlation UUID","schema":{"type":"string","format":"uuid"}},"X-Sneakers-Request-Cost":{"description":"Credits charged: operation cost on success, zero on failure","schema":{"type":"number"}},"X-Sneakers-Cache-Status":{"description":"hit means unexpired instance memory; live means no cache served","schema":{"type":"string","enum":["live","hit"]}},"X-Sneakers-Rate-Limit-Remaining":{"description":"Remaining monthly instance credits (zero for anonymous requests)","schema":{"type":"number"}},"X-Sneakers-Rate-Limit-Reset":{"description":"UTC month boundary as Unix seconds","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid query or nonpublic store","headers":{"X-Sneakers-Request-Id":{"description":"Request correlation UUID","schema":{"type":"string","format":"uuid"}},"X-Sneakers-Request-Cost":{"description":"Credits charged: operation cost on success, zero on failure","schema":{"type":"number"}},"X-Sneakers-Cache-Status":{"description":"hit means unexpired instance memory; live means no cache served","schema":{"type":"string","enum":["live","hit"]}},"X-Sneakers-Rate-Limit-Remaining":{"description":"Remaining monthly instance credits (zero for anonymous requests)","schema":{"type":"number"}},"X-Sneakers-Rate-Limit-Reset":{"description":"UTC month boundary as Unix seconds","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"426":{"description":"Monthly instance credits exhausted","headers":{"X-Sneakers-Request-Id":{"description":"Request correlation UUID","schema":{"type":"string","format":"uuid"}},"X-Sneakers-Request-Cost":{"description":"Credits charged: operation cost on success, zero on failure","schema":{"type":"number"}},"X-Sneakers-Cache-Status":{"description":"hit means unexpired instance memory; live means no cache served","schema":{"type":"string","enum":["live","hit"]}},"X-Sneakers-Rate-Limit-Remaining":{"description":"Remaining monthly instance credits (zero for anonymous requests)","schema":{"type":"number"}},"X-Sneakers-Rate-Limit-Reset":{"description":"UTC month boundary as Unix seconds","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","headers":{"X-Sneakers-Request-Id":{"description":"Request correlation UUID","schema":{"type":"string","format":"uuid"}},"X-Sneakers-Request-Cost":{"description":"Credits charged: operation cost on success, zero on failure","schema":{"type":"number"}},"X-Sneakers-Cache-Status":{"description":"hit means unexpired instance memory; live means no cache served","schema":{"type":"string","enum":["live","hit"]}},"X-Sneakers-Rate-Limit-Remaining":{"description":"Remaining monthly instance credits (zero for anonymous requests)","schema":{"type":"number"}},"X-Sneakers-Rate-Limit-Reset":{"description":"UTC month boundary as Unix seconds","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Source disabled, blocked, malformed, timed out, or misconfigured","headers":{"X-Sneakers-Request-Id":{"description":"Request correlation UUID","schema":{"type":"string","format":"uuid"}},"X-Sneakers-Request-Cost":{"description":"Credits charged: operation cost on success, zero on failure","schema":{"type":"number"}},"X-Sneakers-Cache-Status":{"description":"hit means unexpired instance memory; live means no cache served","schema":{"type":"string","enum":["live","hit"]}},"X-Sneakers-Rate-Limit-Remaining":{"description":"Remaining monthly instance credits (zero for anonymous requests)","schema":{"type":"number"}},"X-Sneakers-Rate-Limit-Reset":{"description":"UTC month boundary as Unix seconds","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/stockx/product":{"get":{"operationId":"stockx_product","summary":"stockx product","description":"Phase 0 locked disabled: returns the existing zero-cost 503 even if STOCKX_ENABLED is true. No transport is reachable.","tags":["stockx"],"x-request-cost":1,"parameters":[{"name":"id","in":"query","required":true,"description":"Product ID or handle / StockX urlKey","schema":{"type":"string","minLength":1,"maxLength":253}},{"name":"include","in":"query","required":false,"schema":{"type":"string"},"description":"Optional comma-separated layers: market.alias, market.stockx, identity.retailers, retailers, proxies.median. These layers are disabled. Each requested missing layer appears in unavailable; no enrichment or additional charge occurs. Unrequested layers are omitted; unknown names report unsupported."}],"responses":{"200":{"description":"Success; instance cache TTL 120s; cache hits cost 1 credits","headers":{"X-Sneakers-Request-Id":{"description":"Request correlation UUID","schema":{"type":"string","format":"uuid"}},"X-Sneakers-Request-Cost":{"description":"Credits charged: operation cost on success, zero on failure","schema":{"type":"number"}},"X-Sneakers-Cache-Status":{"description":"hit means unexpired instance memory; live means no cache served","schema":{"type":"string","enum":["live","hit"]}},"X-Sneakers-Rate-Limit-Remaining":{"description":"Remaining monthly instance credits (zero for anonymous requests)","schema":{"type":"number"}},"X-Sneakers-Rate-Limit-Reset":{"description":"UTC month boundary as Unix seconds","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","required":["status","data","contractVersion","unavailable"],"additionalProperties":false,"properties":{"contractVersion":{"const":"hybrid-1"},"unavailable":{"type":"array","items":{"$ref":"#/components/schemas/Unavailable"}},"status":{"const":true},"data":{"$ref":"#/components/schemas/Product"}}}}}},"401":{"description":"Invalid credentials","headers":{"X-Sneakers-Request-Id":{"description":"Request correlation UUID","schema":{"type":"string","format":"uuid"}},"X-Sneakers-Request-Cost":{"description":"Credits charged: operation cost on success, zero on failure","schema":{"type":"number"}},"X-Sneakers-Cache-Status":{"description":"hit means unexpired instance memory; live means no cache served","schema":{"type":"string","enum":["live","hit"]}},"X-Sneakers-Rate-Limit-Remaining":{"description":"Remaining monthly instance credits (zero for anonymous requests)","schema":{"type":"number"}},"X-Sneakers-Rate-Limit-Reset":{"description":"UTC month boundary as Unix seconds","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown endpoint or product","headers":{"X-Sneakers-Request-Id":{"description":"Request correlation UUID","schema":{"type":"string","format":"uuid"}},"X-Sneakers-Request-Cost":{"description":"Credits charged: operation cost on success, zero on failure","schema":{"type":"number"}},"X-Sneakers-Cache-Status":{"description":"hit means unexpired instance memory; live means no cache served","schema":{"type":"string","enum":["live","hit"]}},"X-Sneakers-Rate-Limit-Remaining":{"description":"Remaining monthly instance credits (zero for anonymous requests)","schema":{"type":"number"}},"X-Sneakers-Rate-Limit-Reset":{"description":"UTC month boundary as Unix seconds","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"GET required","headers":{"X-Sneakers-Request-Id":{"description":"Request correlation UUID","schema":{"type":"string","format":"uuid"}},"X-Sneakers-Request-Cost":{"description":"Credits charged: operation cost on success, zero on failure","schema":{"type":"number"}},"X-Sneakers-Cache-Status":{"description":"hit means unexpired instance memory; live means no cache served","schema":{"type":"string","enum":["live","hit"]}},"X-Sneakers-Rate-Limit-Remaining":{"description":"Remaining monthly instance credits (zero for anonymous requests)","schema":{"type":"number"}},"X-Sneakers-Rate-Limit-Reset":{"description":"UTC month boundary as Unix seconds","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid query or nonpublic store","headers":{"X-Sneakers-Request-Id":{"description":"Request correlation UUID","schema":{"type":"string","format":"uuid"}},"X-Sneakers-Request-Cost":{"description":"Credits charged: operation cost on success, zero on failure","schema":{"type":"number"}},"X-Sneakers-Cache-Status":{"description":"hit means unexpired instance memory; live means no cache served","schema":{"type":"string","enum":["live","hit"]}},"X-Sneakers-Rate-Limit-Remaining":{"description":"Remaining monthly instance credits (zero for anonymous requests)","schema":{"type":"number"}},"X-Sneakers-Rate-Limit-Reset":{"description":"UTC month boundary as Unix seconds","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"426":{"description":"Monthly instance credits exhausted","headers":{"X-Sneakers-Request-Id":{"description":"Request correlation UUID","schema":{"type":"string","format":"uuid"}},"X-Sneakers-Request-Cost":{"description":"Credits charged: operation cost on success, zero on failure","schema":{"type":"number"}},"X-Sneakers-Cache-Status":{"description":"hit means unexpired instance memory; live means no cache served","schema":{"type":"string","enum":["live","hit"]}},"X-Sneakers-Rate-Limit-Remaining":{"description":"Remaining monthly instance credits (zero for anonymous requests)","schema":{"type":"number"}},"X-Sneakers-Rate-Limit-Reset":{"description":"UTC month boundary as Unix seconds","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","headers":{"X-Sneakers-Request-Id":{"description":"Request correlation UUID","schema":{"type":"string","format":"uuid"}},"X-Sneakers-Request-Cost":{"description":"Credits charged: operation cost on success, zero on failure","schema":{"type":"number"}},"X-Sneakers-Cache-Status":{"description":"hit means unexpired instance memory; live means no cache served","schema":{"type":"string","enum":["live","hit"]}},"X-Sneakers-Rate-Limit-Remaining":{"description":"Remaining monthly instance credits (zero for anonymous requests)","schema":{"type":"number"}},"X-Sneakers-Rate-Limit-Reset":{"description":"UTC month boundary as Unix seconds","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Source disabled, blocked, malformed, timed out, or misconfigured","headers":{"X-Sneakers-Request-Id":{"description":"Request correlation UUID","schema":{"type":"string","format":"uuid"}},"X-Sneakers-Request-Cost":{"description":"Credits charged: operation cost on success, zero on failure","schema":{"type":"number"}},"X-Sneakers-Cache-Status":{"description":"hit means unexpired instance memory; live means no cache served","schema":{"type":"string","enum":["live","hit"]}},"X-Sneakers-Rate-Limit-Remaining":{"description":"Remaining monthly instance credits (zero for anonymous requests)","schema":{"type":"number"}},"X-Sneakers-Rate-Limit-Reset":{"description":"UTC month boundary as Unix seconds","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}},"schemas":{"Unavailable":{"type":"object","required":["layer","reason"],"additionalProperties":false,"properties":{"layer":{"type":"string"},"reason":{"type":"string","enum":["disabled","unsupported"]}}},"SourceHealth":{"type":"object","required":["enabled","state","layers","certifiedCapabilities","lastSuccessfulIngest","observationWatermark","coverage","reason"],"additionalProperties":false,"properties":{"enabled":{"type":"boolean"},"state":{"type":"string","enum":["disabled","blocked","healthy","degraded","stale"]},"layers":{"type":"array","items":{"type":"string"}},"certifiedCapabilities":{"type":"array","items":{"type":"string"}},"lastSuccessfulIngest":{"type":["string","null"],"format":"date-time"},"observationWatermark":{"type":["string","null"],"format":"date-time"},"coverage":{"type":"string"},"reason":{"type":"string"}}},"PriceProvenance":{"type":"object","required":["provider","sourceMarketplace","region","currency","size","condition","observedAt","ingestedAt","feeBasis","semanticType"],"additionalProperties":false,"properties":{"provider":{"type":"string","minLength":1},"sourceMarketplace":{"type":"string","minLength":1},"region":{"type":"string","minLength":1},"currency":{"type":"string","pattern":"^(?:[A-Z]{3}|unknown)$","description":"ISO 4217 code if declared upstream, otherwise unknown; legacy currency remains null when absent."},"size":{"type":"object","required":["system","value","audience"],"additionalProperties":false,"properties":{"system":{"type":"string","enum":["US","UK","EU","unknown"]},"value":{"type":"string","minLength":1},"audience":{"type":"string","enum":["mens","womens","kids","unknown"]},"group":{"type":"string","enum":["infant","toddler","youth","unknown"]},"scope":{"const":"aggregate"},"chart_id":{"type":"string"}}},"condition":{"type":"string","minLength":1},"observedAt":{"type":"string","format":"date-time"},"ingestedAt":{"type":"string","format":"date-time"},"feeBasis":{"type":"string","minLength":1},"semanticType":{"type":"string","enum":["retailerOffer","lowest_executable_ask","highest_executable_bid","lastSale","latestObservedSale","resaleMedianProxy"]}},"description":"Shopify emits retailerOffer only. Fetch time is observedAt; ingestion is separate. Cache hits retain both. Unknown sizing, condition, region and fees do not qualify for live market comparison. lowestPrice provenance is aggregate across listed variants, including unavailable variants."},"Error":{"type":"object","required":["status","message"],"additionalProperties":false,"properties":{"status":{"const":false},"message":{"type":"string"}}},"Health":{"type":"object","required":["status","sources"],"additionalProperties":false,"properties":{"status":{"const":true},"sources":{"type":"object","required":["shopify","stockx"],"additionalProperties":false,"properties":{"shopify":{"const":"live"},"stockx":{"const":"disabled"},"details":{"type":"object","required":["shopify","stockx","alias","retailer-identity","retailer-asks","median-proxy"],"additionalProperties":false,"properties":{"shopify":{"$ref":"#/components/schemas/SourceHealth"},"stockx":{"$ref":"#/components/schemas/SourceHealth"},"alias":{"$ref":"#/components/schemas/SourceHealth"},"retailer-identity":{"$ref":"#/components/schemas/SourceHealth"},"retailer-asks":{"$ref":"#/components/schemas/SourceHealth"},"median-proxy":{"$ref":"#/components/schemas/SourceHealth"}}}}}}},"Variant":{"type":"object","additionalProperties":false,"required":["id","title","size","price","available"],"properties":{"id":{"type":["string","null"]},"title":{"type":["string","null"]},"size":{"type":["string","null"]},"price":{"type":["number","null"],"minimum":0},"priceProvenance":{"$ref":"#/components/schemas/PriceProvenance"},"available":{"type":["boolean","null"]}}},"Product":{"type":"object","additionalProperties":false,"required":["id","source","title","brand","handle","urlKey","url","image","retailPrice","currency","variants","lowestPrice"],"properties":{"id":{"type":["string","null"]},"source":{"type":"string","enum":["shopify","stockx"]},"title":{"type":["string","null"]},"brand":{"type":["string","null"]},"handle":{"type":["string","null"]},"urlKey":{"type":["string","null"]},"url":{"type":["string","null"]},"image":{"type":["string","null"]},"retailPrice":{"type":["number","null"],"minimum":0},"currency":{"type":["string","null"]},"variants":{"type":"array","items":{"$ref":"#/components/schemas/Variant"}},"lowestPrice":{"type":["number","null"],"minimum":0},"lowestPriceProvenance":{"$ref":"#/components/schemas/PriceProvenance"}}}}}}