{"openapi":"3.0.3","info":{"title":"TheWineTrip API","version":"1.1.0","description":"The only global wine trip planning API. 18 wine regions, 45,000+ GPS-mapped wineries, AI-ready itinerary generation. Anonymous: 20 req/day per IP. Free key: 100 req/day (instant signup at /developers). Pro: 10,000 req/day, $29/mo.","contact":{"name":"TheWineTrip Developers","url":"https://thewinetrip.com/developers"}},"servers":[{"url":"https://thewinetrip.com/api/v1","description":"Production"}],"security":[{"bearerAuth":[]},{}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"twt_live_...","description":"Free API key (100 req/day). Get one instantly at /developers — no payment. Pass as `Authorization: Bearer twt_live_...`. Anonymous requests are allowed but capped at 20/day per IP."}}},"paths":{"/regions-list":{"get":{"summary":"List all regions","description":"Returns all 18 wine regions with slug, name, country, and winery count.","operationId":"listRegions","tags":["Regions"],"responses":{"200":{"description":"Array of region summaries","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Daily request quota for the current identity (key tier or anonymous)."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests remaining today."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Unix epoch seconds when the quota resets (next UTC midnight)."},"X-RateLimit-Plan":{"schema":{"type":"string","enum":["anon","free","pro","enterprise"]},"description":"Tier of the requesting identity."},"X-RateLimit-Identity":{"schema":{"type":"string","enum":["anon","key"]},"description":"Whether the request was authenticated by API key or counted as anonymous."}},"content":{"application/json":{"schema":{"type":"object","properties":{"regions":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string","example":"napa"},"name":{"type":"string","example":"Napa Valley"},"country":{"type":"string","example":"USA"},"winery_count":{"type":"integer","example":1188}}}}}}}}},"401":{"description":"Invalid or revoked API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"429":{"description":"Rate limit exceeded — daily quota reached. Reset at next UTC midnight.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Daily request quota for the current identity (key tier or anonymous)."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests remaining today."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Unix epoch seconds when the quota resets (next UTC midnight)."},"X-RateLimit-Plan":{"schema":{"type":"string","enum":["anon","free","pro","enterprise"]},"description":"Tier of the requesting identity."},"X-RateLimit-Identity":{"schema":{"type":"string","enum":["anon","key"]},"description":"Whether the request was authenticated by API key or counted as anonymous."}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Rate limit exceeded"},"message":{"type":"string"},"limit":{"type":"integer"},"reset":{"type":"integer"}}}}}}}}},"/regions/{slug}":{"get":{"summary":"Get region guide","description":"Full region data: climate, wine styles, highlights, best months, budget, affiliate hotel/tour links.","operationId":"getRegion","tags":["Regions"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","enum":["napa","bordeaux","tuscany","rioja","barossa","champagne","burgundy","douro","mendoza","willamette","alsace","mosel","priorat","rioja-alta","mclaren-vale","hunter-valley","stellenbosch","wachau"]},"description":"Region slug"}],"responses":{"200":{"description":"Region guide data","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Daily request quota for the current identity (key tier or anonymous)."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests remaining today."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Unix epoch seconds when the quota resets (next UTC midnight)."},"X-RateLimit-Plan":{"schema":{"type":"string","enum":["anon","free","pro","enterprise"]},"description":"Tier of the requesting identity."},"X-RateLimit-Identity":{"schema":{"type":"string","enum":["anon","key"]},"description":"Whether the request was authenticated by API key or counted as anonymous."}},"content":{"application/json":{"schema":{"type":"object","properties":{"region":{"type":"object"},"affiliate":{"type":"object"}}}}}},"401":{"description":"Invalid or revoked API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"404":{"description":"Region not found"},"429":{"description":"Rate limit exceeded — daily quota reached. Reset at next UTC midnight.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Daily request quota for the current identity (key tier or anonymous)."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests remaining today."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Unix epoch seconds when the quota resets (next UTC midnight)."},"X-RateLimit-Plan":{"schema":{"type":"string","enum":["anon","free","pro","enterprise"]},"description":"Tier of the requesting identity."},"X-RateLimit-Identity":{"schema":{"type":"string","enum":["anon","key"]},"description":"Whether the request was authenticated by API key or counted as anonymous."}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Rate limit exceeded"},"message":{"type":"string"},"limit":{"type":"integer"},"reset":{"type":"integer"}}}}}}}}},"/wineries":{"get":{"summary":"Search wineries","description":"Search GPS-mapped wineries by region. 45,000+ records from the alphadev-travel database.","operationId":"getWineries","tags":["Wineries"],"parameters":[{"name":"region","in":"query","required":true,"schema":{"type":"string","example":"napa"},"description":"Region slug"},{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"Search by winery name (optional)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50,"maximum":200}}],"responses":{"200":{"description":"Winery list with GPS coordinates","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Daily request quota for the current identity (key tier or anonymous)."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests remaining today."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Unix epoch seconds when the quota resets (next UTC midnight)."},"X-RateLimit-Plan":{"schema":{"type":"string","enum":["anon","free","pro","enterprise"]},"description":"Tier of the requesting identity."},"X-RateLimit-Identity":{"schema":{"type":"string","enum":["anon","key"]},"description":"Whether the request was authenticated by API key or counted as anonymous."}},"content":{"application/json":{"schema":{"type":"object","properties":{"region":{"type":"object"},"wineries":{"type":"array","items":{"type":"object"}},"meta":{"type":"object"}}}}}},"401":{"description":"Invalid or revoked API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"429":{"description":"Rate limit exceeded — daily quota reached. Reset at next UTC midnight.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Daily request quota for the current identity (key tier or anonymous)."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests remaining today."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Unix epoch seconds when the quota resets (next UTC midnight)."},"X-RateLimit-Plan":{"schema":{"type":"string","enum":["anon","free","pro","enterprise"]},"description":"Tier of the requesting identity."},"X-RateLimit-Identity":{"schema":{"type":"string","enum":["anon","key"]},"description":"Whether the request was authenticated by API key or counted as anonymous."}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Rate limit exceeded"},"message":{"type":"string"},"limit":{"type":"integer"},"reset":{"type":"integer"}}}}}}}}},"/plan":{"post":{"summary":"Generate itinerary","description":"AI-powered day-by-day wine trip itinerary. Returns structured JSON with daily stops, winery recommendations, and affiliate accommodation/tour links.","operationId":"generateItinerary","tags":["Itinerary"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["region","days"],"properties":{"region":{"type":"string","example":"napa","description":"Region slug"},"days":{"type":"integer","minimum":2,"maximum":10,"example":3},"style":{"type":"string","enum":["romantic","serious","budget","luxury"],"default":"romantic"},"interests":{"type":"array","items":{"type":"string"},"example":["food pairing","architecture"]}}}}}},"responses":{"200":{"description":"Day-by-day itinerary with affiliate links","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Daily request quota for the current identity (key tier or anonymous)."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests remaining today."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Unix epoch seconds when the quota resets (next UTC midnight)."},"X-RateLimit-Plan":{"schema":{"type":"string","enum":["anon","free","pro","enterprise"]},"description":"Tier of the requesting identity."},"X-RateLimit-Identity":{"schema":{"type":"string","enum":["anon","key"]},"description":"Whether the request was authenticated by API key or counted as anonymous."}},"content":{"application/json":{"schema":{"type":"object","properties":{"itinerary":{"type":"object"},"affiliate":{"type":"object"}}}}}},"400":{"description":"Invalid request parameters"},"401":{"description":"Invalid or revoked API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"429":{"description":"Rate limit exceeded — daily quota reached. Reset at next UTC midnight.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Daily request quota for the current identity (key tier or anonymous)."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests remaining today."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Unix epoch seconds when the quota resets (next UTC midnight)."},"X-RateLimit-Plan":{"schema":{"type":"string","enum":["anon","free","pro","enterprise"]},"description":"Tier of the requesting identity."},"X-RateLimit-Identity":{"schema":{"type":"string","enum":["anon","key"]},"description":"Whether the request was authenticated by API key or counted as anonymous."}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Rate limit exceeded"},"message":{"type":"string"},"limit":{"type":"integer"},"reset":{"type":"integer"}}}}}}}}},"/festivals":{"get":{"summary":"List wine festivals","description":"Wine festivals near TWT-supported regions. Filter by region, month, type, or minimum worth-traveling-for score.","operationId":"getFestivals","tags":["Festivals"],"parameters":[{"name":"region","in":"query","required":false,"schema":{"type":"string"}},{"name":"month","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":12}},{"name":"type","in":"query","required":false,"schema":{"type":"string"}},{"name":"min_score","in":"query","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Festival list","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Daily request quota for the current identity (key tier or anonymous)."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests remaining today."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Unix epoch seconds when the quota resets (next UTC midnight)."},"X-RateLimit-Plan":{"schema":{"type":"string","enum":["anon","free","pro","enterprise"]},"description":"Tier of the requesting identity."},"X-RateLimit-Identity":{"schema":{"type":"string","enum":["anon","key"]},"description":"Whether the request was authenticated by API key or counted as anonymous."}},"content":{"application/json":{"schema":{"type":"object","properties":{"festivals":{"type":"array","items":{"type":"object"}},"meta":{"type":"object"}}}}}},"401":{"description":"Invalid or revoked API key.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}},"429":{"description":"Rate limit exceeded — daily quota reached. Reset at next UTC midnight.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Daily request quota for the current identity (key tier or anonymous)."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests remaining today."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Unix epoch seconds when the quota resets (next UTC midnight)."},"X-RateLimit-Plan":{"schema":{"type":"string","enum":["anon","free","pro","enterprise"]},"description":"Tier of the requesting identity."},"X-RateLimit-Identity":{"schema":{"type":"string","enum":["anon","key"]},"description":"Whether the request was authenticated by API key or counted as anonymous."}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Rate limit exceeded"},"message":{"type":"string"},"limit":{"type":"integer"},"reset":{"type":"integer"}}}}}}}}}},"tags":[{"name":"Regions","description":"18 global wine regions"},{"name":"Wineries","description":"GPS-mapped winery database"},{"name":"Itinerary","description":"AI trip planning"},{"name":"Festivals","description":"Wine events near TWT regions"}]}