{"openapi":"3.1.0","info":{"title":"Spectrum Wine public discovery APIs","version":"1.1.0","description":"Read-only retail inventory search, current-auction search, search options and highlights. Availability may vary; responses do not reserve inventory or establish transaction eligibility."},"servers":[{"url":"https://www.spectrumwine.com"}],"externalDocs":{"url":"https://www.spectrumwine.com/developers/api"},"paths":{"/api/auctions/search":{"get":{"operationId":"searchCurrentAuction","summary":"Search public lots in the current operator-open auction","security":[],"description":"The merchant selects its current auction from authoritative active session status 99/97. Callers cannot choose an auction ID; past auctions and historical fallback are excluded. Only currently public lots in operator-open sessions are included. A session status is not bidding eligibility. Search is bounded to prepared catalog metadata and current native public bid/state reads; no filtered catalog rebuild or scan is started. Producer matches public lot-heading words. Results use increasing lot ID order. Amounts are per lot in the auction's native currency units, not retail cents or final transaction totals. The upstream public contract does not provide an ISO currency code, so currencyCode is null; no currency conversion is performed.","parameters":[{"name":"q","in":"query","schema":{"type":"string","minLength":1,"maxLength":200},"description":"1–8 searchable word prefixes of 2–80 characters, accent-insensitive. One-letter fragments such as d in d'Yquem are ignored."},{"name":"producer","in":"query","schema":{"type":"string","minLength":1,"maxLength":160},"description":"1–8 searchable word prefixes of 2–80 characters, accent-insensitive. One-letter fragments such as d in d'Yquem are ignored."},{"name":"country","in":"query","schema":{"type":"string","minLength":1,"maxLength":160},"description":"Exact geography label; canonical spelling aliases are accepted."},{"name":"region","in":"query","schema":{"type":"string","minLength":1,"maxLength":160},"description":"Exact geography label; canonical spelling aliases are accepted."},{"name":"subregion","in":"query","schema":{"type":"string","minLength":1,"maxLength":160},"description":"Exact geography label; canonical spelling aliases are accepted."},{"name":"vintageMin","in":"query","schema":{"type":"integer","minimum":1,"maximum":9999}},{"name":"vintageMax","in":"query","schema":{"type":"integer","minimum":1,"maximum":9999}},{"name":"scoreMin","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"scoreMax","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"bidMin","in":"query","schema":{"type":"number","minimum":0,"maximum":1000000,"multipleOf":0.01},"description":"Inclusive effective bid: current bid when positive, otherwise opening bid. Native auction units per lot."},{"name":"bidMax","in":"query","schema":{"type":"number","minimum":0,"maximum":1000000,"multipleOf":0.01},"description":"Inclusive effective bid: current bid when positive, otherwise opening bid. Native auction units per lot."},{"name":"estimateMin","in":"query","schema":{"type":"number","minimum":0,"maximum":1000000,"multipleOf":0.01},"description":"Inclusive public estimate in native auction units per lot."},{"name":"estimateMax","in":"query","schema":{"type":"number","minimum":0,"maximum":1000000,"multipleOf":0.01},"description":"Inclusive public estimate in native auction units per lot."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":25,"default":10}},{"name":"cursor","in":"query","schema":{"type":"string","maxLength":400},"description":"Opaque nextCursor; reuse exact filters and limit. It is bound to the current auction and prepared catalog version. Restart on 409."}],"responses":{"200":{"description":"A page of current-auction public lot summaries, or explicit no_current_auction when none is operator-open.","content":{"application/json":{"schema":{"type":"object","required":["auction","status","lots","total","observedAt","nextCursor"],"properties":{"auction":{"type":["object","null"],"properties":{"id":{"type":"integer","minimum":1},"title":{"type":"string"},"url":{"type":"string"}}},"status":{"type":"string","enum":["current_auction","no_current_auction"]},"currencyCode":{"type":"null"},"catalogVersion":{"type":"string","pattern":"^[a-f0-9]{64}$"},"lots":{"type":"array","maxItems":25,"items":{"type":"object","required":["id","lotNumber","sessionId","sessionStatusId","title","openingBid","currentBid","effectiveBid","estimate","url"],"properties":{"id":{"type":"integer","minimum":1},"lotNumber":{"type":"integer","minimum":0},"sessionId":{"type":"integer","minimum":1},"sessionStatusId":{"type":"integer","minimum":1},"title":{"type":"string"},"vintage":{"type":"string"},"country":{"type":"string"},"region":{"type":"string"},"subregion":{"type":"string"},"size":{"type":"string"},"score":{"type":"string"},"provenance":{"type":"string"},"url":{"type":"string"},"openingBid":{"type":["number","null"],"minimum":0},"currentBid":{"type":["number","null"],"minimum":0},"effectiveBid":{"type":["number","null"],"minimum":0},"estimate":{"type":["number","null"],"minimum":0},"quantity":{"type":["number","null"],"minimum":0}}}},"total":{"type":"integer","minimum":0},"observedAt":{"type":"string","format":"date-time"},"nextCursor":{"type":["string","null"]}}}}}},"400":{"description":"Invalid/repeated/unsupported parameter or cursor. Auction selectors and historical scope are not supported.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"403":{"description":"Discovery access denied for this connection.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"409":{"description":"The current auction or prepared catalog changed. Restart pagination.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"414":{"description":"The encoded request URL exceeds4096characters.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"429":{"description":"Combined discovery or additional auction source budget exhausted. Respect Retry-After.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}},"headers":{"Retry-After":{"description":"When present, minimum delay in seconds before retrying. Use backoff and avoid concurrent retries.","schema":{"type":"string","pattern":"^[0-9]+$"}}}},"503":{"description":"Prepared current-auction metadata, native state or bounded source capacity unavailable.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}},"headers":{"Retry-After":{"description":"When present, minimum delay in seconds before retrying. Use backoff and avoid concurrent retries.","schema":{"type":"string","pattern":"^[0-9]+$"}}}}}}},"/api/catalog/search":{"get":{"operationId":"searchRetailInventory","summary":"Search public retail inventory with structured filters","security":[],"description":"Uses the website's complete validated retail snapshot, observed less than five minutes ago. Never starts an upstream catalog scan. Only public simple products with visible prices and consistent known geography are included; custom-selection and hidden-price products remain on the website. Default is in-stock only, in increasing product ID order. All filters combine with AND. Word matching is accent-insensitive word-prefix matching. Producer searches words in the product name, not an authoritative producer taxonomy. Score ranges use the lower bound of the highest published critic score. Prices are USD minor units; price filters are USD major units. Pagination is a live keyset view, not a reserved/frozen inventory snapshot.","parameters":[{"name":"q","in":"query","schema":{"type":"string","minLength":1,"maxLength":200},"description":"1–8 searchable words, each 2–80 characters. One-letter fragments are ignored. Producer matches product-name words; q also matches SKU, vintage and geography words."},{"name":"producer","in":"query","schema":{"type":"string","minLength":1,"maxLength":160},"description":"1–8 searchable words, each 2–80 characters. One-letter fragments are ignored. Producer matches product-name words; q also matches SKU, vintage and geography words."},{"name":"country","in":"query","schema":{"type":"string","minLength":1,"maxLength":160},"description":"Exact geography label; documented spelling aliases are accepted."},{"name":"region","in":"query","schema":{"type":"string","minLength":1,"maxLength":160},"description":"Exact geography label; documented spelling aliases are accepted."},{"name":"subregion","in":"query","schema":{"type":"string","minLength":1,"maxLength":160},"description":"Exact geography label; documented spelling aliases are accepted."},{"name":"section","in":"query","schema":{"type":"string","enum":["wines","spirits","sake","gear"]}},{"name":"vintageMin","in":"query","schema":{"type":"integer","minimum":1,"maximum":9999}},{"name":"vintageMax","in":"query","schema":{"type":"integer","minimum":1,"maximum":9999}},{"name":"scoreMin","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"scoreMax","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"priceMin","in":"query","schema":{"type":"number","minimum":0,"maximum":1000000,"multipleOf":0.01},"description":"Inclusive current displayed selling price in USD, up to two decimal places."},{"name":"priceMax","in":"query","schema":{"type":"number","minimum":0,"maximum":1000000,"multipleOf":0.01},"description":"Inclusive current displayed selling price in USD, up to two decimal places."},{"name":"inStock","in":"query","schema":{"type":"string","enum":["0","1"],"default":"1"},"description":"1 includes available products only; 0 includes both available and unavailable products."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":25,"default":10}},{"name":"cursor","in":"query","schema":{"type":"string","maxLength":256},"description":"Opaque nextCursor; reuse the exact same filters and limit. Membership, prices and stock can change between pages."}],"responses":{"200":{"description":"Public matching retail products. No inventory is reserved; inspect observedAt.","content":{"application/json":{"schema":{"type":"object","required":["products","total","observedAt","maxAgeSeconds","nextCursor"],"properties":{"products":{"type":"array","maxItems":25,"items":{"type":"object","required":["id","sku","name","section","price","available","url","country","region","subregion","vintage","size","scores"],"properties":{"id":{"type":"integer","minimum":1},"sku":{"type":"string"},"name":{"type":"string"},"section":{"type":"string","enum":["wines","spirits","sake","gear"]},"price":{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"integer","minimum":0},"currency":{"const":"USD"}}},"available":{"type":"boolean"},"url":{"type":"string","description":"Relative public product URL."},"country":{"type":"string"},"region":{"type":"string"},"subregion":{"type":"string"},"vintage":{"type":"string"},"size":{"type":"string"},"scores":{"type":"object","additionalProperties":{"type":["number","string"]}}}}},"total":{"type":"integer","minimum":0},"observedAt":{"type":"string","format":"date-time"},"maxAgeSeconds":{"const":300},"nextCursor":{"type":["string","null"]}}}}}},"400":{"description":"Invalid, repeated or unsupported parameter, range or cursor.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"403":{"description":"Discovery access denied for this connection.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"414":{"description":"The encoded request URL exceeds 4096 characters.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"422":{"description":"Word-prefix search exceeds the bounded index expansion budget. Narrow the words or filters.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"429":{"description":"The shared discovery request budget is exhausted. Respect Retry-After.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}},"headers":{"Retry-After":{"description":"When present, minimum delay in seconds before retrying. Use backoff and avoid concurrent retries.","schema":{"type":"string","pattern":"^[0-9]+$"}}}},"503":{"description":"The complete fresh retail snapshot, current discovery policy or request capacity is unavailable.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}},"headers":{"Retry-After":{"description":"When present, minimum delay in seconds before retrying. Use backoff and avoid concurrent retries.","schema":{"type":"string","pattern":"^[0-9]+$"}}}}}}},"/api/search/options":{"get":{"operationId":"getSearchOptions","summary":"Get available search geography labels","description":"Returns country, region and subregion options from the selected auction and retail sources. Inspect unavailable even on HTTP 200: failed sources are omitted from the options.","security":[],"parameters":[{"name":"country","in":"query","description":"Filter by country label.","schema":{"type":"string","maxLength":160}},{"name":"region","in":"query","description":"Filter by region label.","schema":{"type":"string","maxLength":160}},{"name":"labels","in":"query","description":"Source labels preserve existing customer form/saved-search mappings. Request canonical to normalize display aliases for agent discovery.","schema":{"type":"string","enum":["source","canonical"],"default":"source"}},{"name":"scope","in":"query","description":"Use custom to include only sources explicitly enabled with 1. Otherwise both sources are enabled unless set to 0.","schema":{"type":"string","enum":["custom"]}},{"name":"auction","in":"query","description":"Source selection: 1 enables, 0 disables. See scope for defaults.","schema":{"type":"string","enum":["0","1"]}},{"name":"retail","in":"query","description":"Source selection: 1 enables, 0 disables. See scope for defaults.","schema":{"type":"string","enum":["0","1"]}}],"responses":{"200":{"description":"Geography options, possibly partial when sources are unavailable.","content":{"application/json":{"schema":{"type":"object","required":["options","unavailable"],"properties":{"options":{"type":"object","required":["country","region","subregion"],"properties":{"country":{"type":"array","items":{"type":"string"}},"region":{"type":"array","items":{"type":"string"}},"subregion":{"type":"array","items":{"type":"string"}}}},"unavailable":{"type":"array","items":{"type":"string"},"description":"Sources that could not be loaded."}}}}}},"400":{"description":"Invalid or repeated geography label format.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"403":{"description":"Discovery access denied for this connection.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"414":{"description":"The encoded request URL exceeds 4096 characters.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"429":{"description":"The discovery request budget is exhausted. Respect Retry-After.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}},"headers":{"Retry-After":{"description":"When present, minimum delay in seconds before retrying. Use backoff and avoid concurrent retries.","schema":{"type":"string","pattern":"^[0-9]+$"}}}},"503":{"description":"Discovery request capacity is temporarily busy.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}},"headers":{"Retry-After":{"description":"When present, minimum delay in seconds before retrying. Use backoff and avoid concurrent retries.","schema":{"type":"string","pattern":"^[0-9]+$"}}}},"default":{"description":"The service could not complete the request. Retry later with backoff."}}}},"/api/auction-highlights":{"get":{"operationId":"getAuctionHighlights","summary":"Get a page of public auction highlights","description":"Returns up to 12 highlighted lots. Follow nextOffset until null. An empty page does not establish auction closure or a sale outcome.","security":[],"parameters":[{"name":"auctionId","in":"query","required":true,"schema":{"type":"integer","minimum":1,"maximum":9007199254740991}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"maximum":9007199254740991,"default":0}}],"responses":{"200":{"description":"A page of public highlighted lots.","content":{"application/json":{"schema":{"type":"object","required":["lots","total","nextOffset"],"properties":{"lots":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Public lot records as displayed on the website."},"total":{"type":"integer","minimum":0},"nextOffset":{"type":["integer","null"],"minimum":0}}}}}},"400":{"description":"Invalid auctionId or offset.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"403":{"description":"Discovery access denied for this connection.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"414":{"description":"The encoded request URL exceeds 4096 characters.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}},"429":{"description":"The discovery request budget is exhausted. Respect Retry-After.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}},"headers":{"Retry-After":{"description":"When present, minimum delay in seconds before retrying. Use backoff and avoid concurrent retries.","schema":{"type":"string","pattern":"^[0-9]+$"}}}},"503":{"description":"Highlights or discovery request capacity are temporarily unavailable.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}},"headers":{"Retry-After":{"description":"When present, minimum delay in seconds before retrying. Use backoff and avoid concurrent retries.","schema":{"type":"string","pattern":"^[0-9]+$"}}}}}}}}}