{"openapi":"3.1.0","info":{"title":"Winevery Wine API","version":"1.0.0","description":"Wine search, reference profiles, similarity and food pairing. Public catalogue positioning: up to 2 million wines. Actual coverage is available through GET /catalogue. Missing fields remain unknown. No live retail pricing or inventory.","termsOfService":"https://www.winevery.com/terms/api","contact":{"email":"hello@winevery.com"}},"servers":[{"url":"https://www.winevery.com/api/v1"}],"security":[{"ApiKey":[]}],"paths":{"/catalogue":{"get":{"operationId":"getCatalogue","summary":"Catalogue count, countries, wine types and field coverage.","description":"1 credits per successful request. Non-2xx responses do not consume credits.","parameters":[],"responses":{"200":{"description":"Successful response.","headers":{"X-Credits-Remaining":{"schema":{"type":"integer"}},"X-Credits-Limit":{"schema":{"type":"integer"}},"X-Quota-Reset":{"description":"Quota reset as Unix seconds.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Maximum requests per minute.","schema":{"type":"integer"}},"X-Request-Id":{"schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","properties":{"availableWineRecords":{"type":"integer"},"importedAt":{"type":"string"},"countries":{"type":"array","items":{"type":"array","items":{"oneOf":[{"type":"string"},{"type":"integer"}]}}},"types":{"type":"array","items":{"type":"array","items":{"oneOf":[{"type":"string"},{"type":"integer"}]}}},"fieldCoverage":{"type":"object","additionalProperties":true},"recordGrain":{"type":"string"},"missingValues":{"type":"string"}}},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"description":"Request rejected. Errors contain code, message and requestId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Request rejected. Errors contain code, message and requestId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Request rejected. Errors contain code, message and requestId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request rejected. Errors contain code, message and requestId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Request rejected. Errors contain code, message and requestId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request rejected. Errors contain code, message and requestId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until retry. code distinguishes rate_limit_exceeded and quota_exceeded."}}},"503":{"description":"Request rejected. Errors contain code, message and requestId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/wines":{"get":{"operationId":"searchWines","summary":"Search names, producers, grapes and regions. Up to 48 results per page.","description":"1 credits per successful request. Non-2xx responses do not consume credits.","parameters":[{"in":"query","name":"q","required":false,"schema":{"type":"string","minLength":2,"maxLength":120}},{"in":"query","name":"country","required":false,"schema":{"type":"string"}},{"in":"query","name":"type","required":false,"schema":{"type":"string","enum":["Red wine","White wine","Rosé wine","Sparkling wine","Dessert wine","Fortified Wine"]}},{"in":"query","name":"page","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":1}},{"in":"query","name":"limit","required":false,"schema":{"type":"integer","minimum":1,"maximum":48,"default":24}}],"responses":{"200":{"description":"Successful response.","headers":{"X-Credits-Remaining":{"schema":{"type":"integer"}},"X-Credits-Limit":{"schema":{"type":"integer"}},"X-Quota-Reset":{"description":"Quota reset as Unix seconds.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Maximum requests per minute.","schema":{"type":"integer"}},"X-Request-Id":{"schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","properties":{"wines":{"type":"array","items":{"$ref":"#/components/schemas/Wine"}},"pagination":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"hasNext":{"type":"boolean"}}}}},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"description":"Request rejected. Errors contain code, message and requestId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Request rejected. Errors contain code, message and requestId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Request rejected. Errors contain code, message and requestId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request rejected. Errors contain code, message and requestId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Request rejected. Errors contain code, message and requestId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request rejected. Errors contain code, message and requestId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until retry. code distinguishes rate_limit_exceeded and quota_exceeded."}}},"503":{"description":"Request rejected. Errors contain code, message and requestId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/wines/{id}":{"get":{"operationId":"getWine","summary":"A wine profile by stable Winevery ID or slug.","description":"1 credits per successful request. Non-2xx responses do not consume credits.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","minLength":1,"maxLength":200}}],"responses":{"200":{"description":"Successful response.","headers":{"X-Credits-Remaining":{"schema":{"type":"integer"}},"X-Credits-Limit":{"schema":{"type":"integer"}},"X-Quota-Reset":{"description":"Quota reset as Unix seconds.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Maximum requests per minute.","schema":{"type":"integer"}},"X-Request-Id":{"schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/Wine"},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"description":"Request rejected. Errors contain code, message and requestId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Request rejected. Errors contain code, message and requestId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Request rejected. Errors contain code, message and requestId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request rejected. Errors contain code, message and requestId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Request rejected. Errors contain code, message and requestId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request rejected. Errors contain code, message and requestId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until retry. code distinguishes rate_limit_exceeded and quota_exceeded."}}},"503":{"description":"Request rejected. Errors contain code, message and requestId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/wines/{id}/similar":{"get":{"operationId":"findSimilarWines","summary":"Up to 12 alternatives, with recorded matching reasons.","description":"3 credits per successful request. Non-2xx responses do not consume credits.","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","minLength":1,"maxLength":200}},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":12,"default":6}}],"responses":{"200":{"description":"Successful response.","headers":{"X-Credits-Remaining":{"schema":{"type":"integer"}},"X-Credits-Limit":{"schema":{"type":"integer"}},"X-Quota-Reset":{"description":"Quota reset as Unix seconds.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Maximum requests per minute.","schema":{"type":"integer"}},"X-Request-Id":{"schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","properties":{"wineId":{"type":"string"},"matches":{"type":"array","items":{"type":"object","properties":{"wine":{"$ref":"#/components/schemas/Wine"},"reasons":{"type":"array","items":{"type":"string"}}}}},"method":{"type":"string"}}},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"description":"Request rejected. Errors contain code, message and requestId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Request rejected. Errors contain code, message and requestId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Request rejected. Errors contain code, message and requestId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request rejected. Errors contain code, message and requestId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Request rejected. Errors contain code, message and requestId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request rejected. Errors contain code, message and requestId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until retry. code distinguishes rate_limit_exceeded and quota_exceeded."}}},"503":{"description":"Request rejected. Errors contain code, message and requestId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/pairings":{"post":{"operationId":"pairWineWithFood","summary":"Up to 12 wine suggestions for an English dish description.","description":"5 credits per successful request. Non-2xx responses do not consume credits.","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["dish"],"properties":{"dish":{"type":"string","minLength":2,"maxLength":500,"description":"English dish or ingredient description."},"limit":{"type":"integer","minimum":1,"maximum":12,"default":6},"heat":{"type":"string","enum":["as-described","mild","medium","hot"],"default":"as-described"}}}}}},"responses":{"200":{"description":"Successful response.","headers":{"X-Credits-Remaining":{"schema":{"type":"integer"}},"X-Credits-Limit":{"schema":{"type":"integer"}},"X-Quota-Reset":{"description":"Quota reset as Unix seconds.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Maximum requests per minute.","schema":{"type":"integer"}},"X-Request-Id":{"schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","properties":{"dish":{"type":"string"},"recognised":{"type":"boolean"},"message":{"type":["string","null"]},"matches":{"type":"array","items":{"type":"object","properties":{"wine":{"$ref":"#/components/schemas/Wine"},"reasons":{"type":"array","items":{"type":"string"}}}}},"method":{"type":"string"}}},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"description":"Request rejected. Errors contain code, message and requestId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Request rejected. Errors contain code, message and requestId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Request rejected. Errors contain code, message and requestId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request rejected. Errors contain code, message and requestId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Request rejected. Errors contain code, message and requestId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request rejected. Errors contain code, message and requestId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until retry. code distinguishes rate_limit_exceeded and quota_exceeded."}}},"503":{"description":"Request rejected. Errors contain code, message and requestId.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"wv_live_…","description":"Create and manage keys at /api/dashboard. Pass the key in the Authorization header, never in the URL."}},"schemas":{"Wine":{"type":"object","required":["id","name","producer","taste","foodPairings","url"],"properties":{"id":{"type":"string"},"slug":{"type":"string"},"name":{"type":"string"},"producer":{"type":"string"},"country":{"type":["string","null"]},"region":{"type":["string","null"]},"type":{"type":["string","null"]},"grapes":{"type":["string","null"]},"primaryGrape":{"type":["string","null"]},"style":{"type":["string","null"]},"abvPercent":{"type":["number","null"]},"rating":{"type":["number","null"]},"ratingCount":{"type":"integer"},"taste":{"type":"object","properties":{"scale":{"type":"string","const":"0–100"},"body":{"type":["number","null"],"minimum":0,"maximum":100},"tannin":{"type":["number","null"],"minimum":0,"maximum":100},"sweetness":{"type":["number","null"],"minimum":0,"maximum":100},"acidity":{"type":["number","null"],"minimum":0,"maximum":100}}},"foodPairings":{"type":"array","items":{"type":"string"}},"url":{"type":"string","format":"uri"}}},"Meta":{"type":"object","properties":{"requestId":{"type":"string","format":"uuid"},"creditsUsed":{"type":"integer"},"creditsRemaining":{"type":"integer"},"quotaResetsAt":{"type":"string","format":"date-time"}}},"Error":{"type":"object","properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"requestId":{"type":"string"}}}}}}}}