{"openapi":"3.0.3","info":{"title":"WineAPI","description":"Access detailed wine data including tasting profiles, critic scores, pricing, food pairings, and more. Explore wines by name, region, or grape variety.","version":"1.0.0"},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","name":"X-API-Key","in":"header"}},"schemas":{}},"paths":{"/wines/search":{"get":{"operationId":"searchWines","summary":"Search wines","tags":["Wines"],"description":"Search our wine catalog by name, winery, or appellation. Returns matching wines with ratings and relevance scores.","parameters":[{"schema":{"type":"string"},"in":"query","name":"q","required":true,"description":"Wine name, winery, or appellation to search for"},{"schema":{"type":"integer","default":20,"minimum":1,"maximum":100},"in":"query","name":"limit","required":false,"description":"Maximum number of results to return"},{"schema":{"type":"integer","default":0,"minimum":0,"maximum":2147483647},"in":"query","name":"offset","required":false,"description":"Number of results to skip for pagination"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"vintage":{"type":"integer","nullable":true},"type":{"type":"string"},"winery":{"type":"string","nullable":true},"region":{"type":"string","nullable":true},"country":{"type":"string","nullable":true},"averageRating":{"type":"number","nullable":true},"ratingsCount":{"type":"integer","nullable":true},"confidence":{"type":"number"}}}},"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"}}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"type":"object","description":"Bad request","properties":{"error":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"integer"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","description":"Missing or invalid API key","properties":{"error":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"integer"}}}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","description":"Rate limit exceeded","properties":{"error":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"integer"}}}}}}}}},"/wines/{id}":{"get":{"operationId":"getWineById","summary":"Get wine details","tags":["Wines"],"description":"Retrieve a complete wine profile including tasting notes, critic scores, pricing, and food pairings.\n\nIf the wine has not yet been updated, the response will include an `X-Update-Status: pending` header and a `Retry-After` header indicating when to re-fetch for complete data.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Wine ID"}],"responses":{"200":{"description":"Wine detail. Check `X-Update-Status` header — if `pending`, the wine is being updated in the background. Re-fetch after `Retry-After` seconds for complete data.","headers":{"X-Update-Status":{"schema":{"type":"string"},"description":"Set to `pending` when enrichment has been queued. Absent when the wine already has complete data."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before re-fetching for updated data. Only present when `X-Update-Status` is `pending`."}},"content":{"application/json":{"schema":{"type":"object","description":"Wine detail. Check `X-Update-Status` header — if `pending`, the wine is being updated in the background. Re-fetch after `Retry-After` seconds for complete data.","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"vintage":{"type":"integer","nullable":true},"type":{"type":"string"},"body":{"type":"string","nullable":true},"acidity":{"type":"string","nullable":true},"elaborate":{"type":"string","nullable":true},"classification":{"type":"string","nullable":true},"averageRating":{"type":"number","nullable":true},"ratingsCount":{"type":"integer","nullable":true},"winery":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"name":{"type":"string"}}},"region":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"name":{"type":"string"},"country":{"type":"string"}}},"appellation":{"type":"string","nullable":true},"grapes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"color":{"type":"string","nullable":true}}}},"alcoholContent":{"type":"number","nullable":true},"description":{"type":"string","nullable":true},"lwinCode":{"type":"string","nullable":true},"imageUrl":{"type":"string","nullable":true},"priceRange":{"type":"object","nullable":true,"properties":{"min":{"type":"number"},"max":{"type":"number"},"currency":{"type":"string"}}},"prices":{"type":"array","items":{"type":"object","properties":{"merchantName":{"type":"string"},"price":{"type":"number"},"currency":{"type":"string"},"url":{"type":"string","nullable":true},"fetchedAt":{"type":"string","format":"date-time"}}}},"scores":{"type":"array","items":{"type":"object","properties":{"score":{"type":"number","nullable":true},"scoreText":{"type":"string","nullable":true},"reviewer":{"type":"string"},"reviewDate":{"type":"string","format":"date-time","nullable":true}}}},"pairings":{"type":"array","items":{"type":"object","properties":{"food":{"type":"string"},"confidence":{"type":"number","nullable":true},"notes":{"type":"string","nullable":true}}}}}}}}},"400":{"description":"Bad request (invalid UUID)","content":{"application/json":{"schema":{"type":"object","description":"Bad request (invalid UUID)","properties":{"error":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"integer"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","description":"Missing or invalid API key","properties":{"error":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"integer"}}}}}},"404":{"description":"Wine not found","content":{"application/json":{"schema":{"type":"object","description":"Wine not found","properties":{"error":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"integer"}}}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","description":"Rate limit exceeded","properties":{"error":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"integer"}}}}}}}}},"/wines/{id}/prices":{"get":{"operationId":"getWinePrices","summary":"Get wine prices","tags":["Prices"],"description":"Get current retail prices for a wine from merchants worldwide.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Wine ID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"wineId":{"type":"string"},"prices":{"type":"array","items":{"type":"object","properties":{"merchantName":{"type":"string","nullable":true},"price":{"type":"string"},"currency":{"type":"string"},"url":{"type":"string","nullable":true},"fetchedAt":{"type":"string"}}}}}}}}},"400":{"description":"Bad request (invalid UUID)","content":{"application/json":{"schema":{"type":"object","description":"Bad request (invalid UUID)","properties":{"error":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"integer"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","description":"Missing or invalid API key","properties":{"error":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"integer"}}}}}},"404":{"description":"Wine not found","content":{"application/json":{"schema":{"type":"object","description":"Wine not found","properties":{"error":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"integer"}}}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","description":"Rate limit exceeded","properties":{"error":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"integer"}}}}}}}}},"/wines/{id}/price-history":{"get":{"operationId":"getWinePriceHistory","summary":"Get wine price history","tags":["Prices"],"description":"View how a wine's retail price has changed over time. Available on Pro plans and above.","parameters":[{"schema":{"type":"string","format":"date"},"in":"query","name":"from","required":false,"description":"Start date for the price history range (YYYY-MM-DD)"},{"schema":{"type":"string","format":"date"},"in":"query","name":"to","required":false,"description":"End date for the price history range (YYYY-MM-DD)"},{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Wine ID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"wineId":{"type":"string"},"history":{"type":"array","items":{"type":"object","properties":{"merchantName":{"type":"string","nullable":true},"price":{"type":"string"},"currency":{"type":"string"},"snapshotDate":{"type":"string","format":"date-time"}}}}}}}}},"400":{"description":"Bad request (invalid UUID or date format)","content":{"application/json":{"schema":{"type":"object","description":"Bad request (invalid UUID or date format)","properties":{"error":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"integer"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","description":"Missing or invalid API key","properties":{"error":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"integer"}}}}}},"403":{"description":"Pro plan required","content":{"application/json":{"schema":{"type":"object","description":"Pro plan required","properties":{"error":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"integer"}}}}}},"404":{"description":"Wine not found","content":{"application/json":{"schema":{"type":"object","description":"Wine not found","properties":{"error":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"integer"}}}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","description":"Rate limit exceeded","properties":{"error":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"integer"}}}}}}}}},"/wines/{id}/pairings":{"get":{"operationId":"getWinePairings","summary":"Get wine food pairings","tags":["Pairings"],"description":"Get recommended food pairings for a wine, including pairing notes and confidence levels.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Wine ID"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"wineId":{"type":"string"},"pairings":{"type":"array","items":{"type":"object","properties":{"food":{"type":"string"},"confidence":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true}}}}}}}}},"400":{"description":"Bad request (invalid UUID)","content":{"application/json":{"schema":{"type":"object","description":"Bad request (invalid UUID)","properties":{"error":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"integer"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","description":"Missing or invalid API key","properties":{"error":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"integer"}}}}}},"404":{"description":"Wine not found","content":{"application/json":{"schema":{"type":"object","description":"Wine not found","properties":{"error":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"integer"}}}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","description":"Rate limit exceeded","properties":{"error":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"integer"}}}}}}}}},"/identify/text":{"post":{"operationId":"identifyWineByText","summary":"Identify wine from text","tags":["Identification"],"description":"Identify a wine from a text description. Provide details like the name, vintage, or label text and we'll match it to our catalog.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","minLength":2,"description":"A description of the wine — include any details from the label, name, vintage, or winery"}},"required":["query"]}}}},"responses":{"200":{"description":"Identification result","content":{"application/json":{"schema":{"type":"object","description":"Identification result","properties":{"confidence":{"type":"number"},"wine":{"type":"object","additionalProperties":true,"nullable":true},"suggestions":{"type":"array","items":{"type":"object","additionalProperties":true}},"autoAdded":{"type":"boolean"},"pendingEnrichment":{"type":"boolean"}}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"type":"object","description":"Bad request","properties":{"error":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"integer"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","description":"Missing or invalid API key","properties":{"error":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"integer"}}}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","description":"Rate limit exceeded","properties":{"error":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"integer"}}}}}}}}},"/identify/image":{"post":{"operationId":"identifyWineByImage","summary":"Identify wine from image","tags":["Identification"],"description":"Identify a wine by uploading a photo of its label. Accepts JPEG or PNG images up to 10 MB.","responses":{"200":{"description":"Identification result","content":{"application/json":{"schema":{"type":"object","description":"Identification result","properties":{"submissionId":{"type":"string","format":"uuid"},"confidence":{"type":"number"},"wine":{"type":"object","additionalProperties":true,"nullable":true},"suggestions":{"type":"array","items":{"type":"object","additionalProperties":true}},"visionDetails":{"type":"object","additionalProperties":true},"autoAdded":{"type":"boolean"},"pendingEnrichment":{"type":"boolean"}}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"type":"object","description":"Bad request","properties":{"error":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"integer"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","description":"Missing or invalid API key","properties":{"error":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"integer"}}}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","description":"Rate limit exceeded","properties":{"error":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"integer"}}}}}}}}},"/submissions":{"post":{"operationId":"createSubmission","summary":"Submit a wine","tags":["Submissions"],"description":"Request that a wine be added to our catalog. Requires a Pro or Enterprise plan.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"wineName":{"type":"string","maxLength":500,"description":"Name of the wine"},"vineyard":{"type":"string","maxLength":500,"description":"Vineyard or estate name"},"wineryUrl":{"type":"string","maxLength":1000,"description":"URL of the winery's website"},"freeText":{"type":"string","description":"Any additional details about the wine"}},"required":["wineName"]}}}},"responses":{"200":{"description":"Submission created","content":{"application/json":{"schema":{"type":"object","description":"Submission created","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Bad request (validation error)","content":{"application/json":{"schema":{"type":"object","description":"Bad request (validation error)","properties":{"error":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"integer"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","description":"Missing or invalid API key","properties":{"error":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"integer"}}}}}},"403":{"description":"Pro or Enterprise plan required","content":{"application/json":{"schema":{"type":"object","description":"Pro or Enterprise plan required","properties":{"error":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"integer"}}}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","description":"Rate limit exceeded","properties":{"error":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"integer"}}}}}}}}},"/submissions/upload":{"post":{"operationId":"createSubmissionWithImage","summary":"Submit a wine with image","tags":["Submissions"],"description":"Request that a wine be added to our catalog with a label image. Requires a Pro or Enterprise plan.","responses":{"200":{"description":"Submission created","content":{"application/json":{"schema":{"type":"object","description":"Submission created","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"type":"object","description":"Bad request","properties":{"error":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"integer"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","description":"Missing or invalid API key","properties":{"error":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"integer"}}}}}},"403":{"description":"Pro or Enterprise plan required","content":{"application/json":{"schema":{"type":"object","description":"Pro or Enterprise plan required","properties":{"error":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"integer"}}}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","description":"Rate limit exceeded","properties":{"error":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"integer"}}}}}}}}},"/submissions/{id}":{"get":{"operationId":"getSubmissionById","summary":"Get submission status","tags":["Submissions"],"description":"Check the status of a wine submission request.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"id","required":true,"description":"Submission ID"}],"responses":{"200":{"description":"Submission details","content":{"application/json":{"schema":{"type":"object","description":"Submission details","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string"},"status":{"type":"string"},"wineName":{"type":"string","nullable":true},"vineyard":{"type":"string","nullable":true},"wineryUrl":{"type":"string","nullable":true},"freeText":{"type":"string","nullable":true},"input":{"type":"string","nullable":true},"resultData":{"type":"object","nullable":true,"additionalProperties":true},"confidence":{"type":"string","nullable":true},"verified":{"type":"string","nullable":true},"errorMessage":{"type":"string","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Bad request (invalid UUID)","content":{"application/json":{"schema":{"type":"object","description":"Bad request (invalid UUID)","properties":{"error":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"integer"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","description":"Missing or invalid API key","properties":{"error":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"integer"}}}}}},"404":{"description":"Submission not found","content":{"application/json":{"schema":{"type":"object","description":"Submission not found","properties":{"error":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"integer"}}}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","description":"Rate limit exceeded","properties":{"error":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"integer"}}}}}}}}},"/regions":{"get":{"operationId":"listRegions","summary":"List wine regions","tags":["Reference"],"description":"Browse wine regions around the world. Optionally filter by country.","parameters":[{"schema":{"type":"string"},"in":"query","name":"country","required":false,"description":"Filter regions by country name"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"regions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"country":{"type":"string"},"code":{"type":"string","nullable":true},"description":{"type":"string","nullable":true}}}}}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"type":"object","description":"Bad request","properties":{"error":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"integer"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","description":"Missing or invalid API key","properties":{"error":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"integer"}}}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","description":"Rate limit exceeded","properties":{"error":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"integer"}}}}}}}}},"/grapes":{"get":{"operationId":"listGrapes","summary":"List grape varieties","tags":["Reference"],"description":"Browse grape varieties. Filter by name or color (red, white, rosé).","parameters":[{"schema":{"type":"string"},"in":"query","name":"q","required":false,"description":"Search grapes by name"},{"schema":{"type":"string","enum":["red","white","rosé"]},"in":"query","name":"color","required":false,"description":"Filter by grape color"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"grapes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"color":{"type":"string"},"description":{"type":"string","nullable":true}}}}}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"type":"object","description":"Bad request","properties":{"error":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"integer"}}}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","description":"Missing or invalid API key","properties":{"error":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"integer"}}}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"type":"object","description":"Rate limit exceeded","properties":{"error":{"type":"string"},"code":{"type":"string"},"statusCode":{"type":"integer"}}}}}}}}}},"servers":[{"url":"https://api.wineapi.io"}],"security":[{"ApiKeyAuth":[]}],"tags":[{"name":"Wines","description":"Search for wines and retrieve detailed profiles including ratings, tasting notes, and producer information"},{"name":"Prices","description":"Current retail prices and historical price trends from merchants worldwide"},{"name":"Pairings","description":"Discover recommended food pairings for any wine in our catalog"},{"name":"Identification","description":"Identify wines from a text description or a photo of the label"},{"name":"Submissions","description":"Request a wine to be added to our catalog and track its review status"},{"name":"Reference","description":"Browse wine regions and grape varieties to explore the world of wine"}]}