{"openapi":"3.0.3","info":{"title":"tickadoo — Experiences & Theatre","version":"1.1.0","description":"Browse 700+ cities and discover, compare and book 13,000+ bookable experiences from tickadoo — theatre shows, tours, attractions and activities. Live inventory, real prices, one-tap booking.","contact":{"name":"tickadoo","url":"https://tickadoo.com","email":"francis@tickadoo.com"}},"servers":[{"url":"https://concierge-test.tickadoo.com","description":"Current Howard deployment"}],"tags":[{"name":"Cities","description":"Browse destinations tickadoo covers and get city-level context and sample experiences."},{"name":"Discover","description":"Find experiences — tonight, this weekend, from a natural-language prompt, or as stay-aware picks for a check-in window."},{"name":"Booking","description":"Prepare or place a booking once the user has chosen an experience."}],"paths":{"/api/cities":{"get":{"operationId":"listCities","summary":"Browse cities tickadoo covers","description":"Returns the list of cities with their country, product count and slug. Use this to help the user pick a destination before calling `tonight`, `discover`, or `recommend`. Always prefer the returned `slug` for subsequent calls — never guess one.","tags":["Cities"],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"description":"Maximum number of cities to return."},{"name":"country_code","in":"query","required":false,"schema":{"type":"string"},"description":"Optional ISO 3166-1 alpha-2 country code filter, e.g. GB, US, FR."}],"responses":{"200":{"description":"City list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CityListResponse"}}}}}}},"/api/cities/{slug}":{"get":{"operationId":"getCityDetail","summary":"Get city detail with sample experiences","description":"Returns the city record (name, country, timezone, description) plus a short list of representative experiences. Useful for giving the user a feel for what is on in a city before deeper discovery calls.","tags":["Cities"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"City slug from `listCities`, e.g. london, paris, new-york."}],"responses":{"200":{"description":"City detail with sample products","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CityDetailResponse"}}}},"404":{"description":"City not found"}}}},"/api/connect/tonight":{"get":{"operationId":"tonight","summary":"Get tonight's bookable experiences for a city","description":"Returns same-night inventory with start times, urgency signals, and booking links. Prefer this for \"what is on tonight in [city]\" questions.","tags":["Discover"],"parameters":[{"name":"citySlug","in":"query","required":true,"schema":{"type":"string"},"description":"Slug form of the city, for example london or new-york."},{"name":"categories","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated category filters."},{"name":"maxResults","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":24,"default":10}}],"responses":{"200":{"description":"Tonight payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TonightResponse"}}}}}}},"/api/connect/recommend":{"post":{"operationId":"recommend","summary":"Generate stay-aware concierge recommendations","description":"Returns structured recommendations for a hotel stay window, with match scores, booking links, and curation metadata.","tags":["Discover"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecommendRequest"}}}},"responses":{"200":{"description":"Recommendation payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecommendResponse"}}}}}}},"/api/connect/discover":{"post":{"operationId":"discover","summary":"Discover experiences from a natural-language prompt","description":"Use for open-ended trip planning prompts such as romantic evening, family day out, or rainy day ideas.","tags":["Discover"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DiscoverRequest"}}}},"responses":{"200":{"description":"Discovery payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DiscoverResponse"}}}}}}},"/api/connect/book":{"post":{"operationId":"book","summary":"Prepare or place a booking for a selected experience","description":"Creates a booking or a ghost checkout payload once the experience, slot, quantity, and guest details are known.","tags":["Booking"],"x-payment-info":{"intent":"session","method":"stripe","currency":"GBP","description":"Booking total varies by experience, slot, and party size — agents receive the live amount in `BookResponse.confirmation.totalAmount` (or `BookResponse.cart.totalAmount` when ghost checkout) and complete payment via the returned Stripe session."},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BookRequest"}}}},"responses":{"200":{"description":"Booking payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BookResponse"}}}}}}},"/api/agent-pay":{"get":{"operationId":"agentPayDiscovery","summary":"x402 Payment Required — agent-native paid access discovery","description":"Returns HTTP 402 with the x402 payment requirement document. Agents construct a payment using the returned `accepts[]` array and re-invoke with proof.","tags":["Booking"],"x-payment-info":{"intent":"charge","method":"tempo","amount":"10000","currency":"USDC","description":"Per-call paid access to tickadoo agent tools via x402 on Base USDC."},"responses":{"402":{"description":"Payment required (x402 envelope)","content":{"application/json":{"schema":{"type":"object"}}}}}}}},"components":{"schemas":{"CitySummary":{"type":"object","required":["slug","name","country_name","country_code","product_count"],"properties":{"slug":{"type":"string","description":"URL-safe slug, e.g. london."},"name":{"type":"string"},"country_name":{"type":"string"},"country_code":{"type":"string","description":"ISO 3166-1 alpha-2 code."},"product_count":{"type":"integer","description":"Number of experiences currently listed for this city."}}},"CityListResponse":{"type":"object","required":["cities"],"properties":{"cities":{"type":"array","items":{"$ref":"#/components/schemas/CitySummary"}}}},"City":{"type":"object","required":["slug","name","country_code","country_name","product_count"],"properties":{"slug":{"type":"string"},"name":{"type":"string"},"country_code":{"type":"string"},"country_name":{"type":"string"},"country_slug":{"type":"string"},"continent":{"type":"string"},"region":{"type":"string","nullable":true},"latitude":{"type":"string","nullable":true},"longitude":{"type":"string","nullable":true},"timezone":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"image_url":{"type":"string","format":"uri","nullable":true},"product_count":{"type":"integer"}}},"CityProduct":{"type":"object","required":["slug","name"],"properties":{"slug":{"type":"string"},"name":{"type":"string"},"price_from":{"type":"string","nullable":true},"currency_code":{"type":"string","nullable":true},"rating":{"type":"string","nullable":true},"review_count":{"type":"integer","nullable":true},"image_url":{"type":"string","format":"uri","nullable":true},"categories":{"type":"array","items":{"type":"string"}}}},"CityDetailResponse":{"type":"object","required":["city","products"],"properties":{"city":{"$ref":"#/components/schemas/City"},"products":{"type":"array","items":{"$ref":"#/components/schemas/CityProduct"}}}},"TonightItem":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"startTime":{"type":"string"},"price":{"type":"number"},"currency":{"type":"string"},"urgency":{"type":"string"},"bookingUrl":{"type":"string","format":"uri"},"availabilityStatus":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"audience":{"type":"array","items":{"type":"string"}},"frontDeskNote":{"type":"string"}},"required":["id","title","startTime","price","currency","urgency","bookingUrl","availabilityStatus","tags","audience","frontDeskNote"]},"TonightResponse":{"type":"object","properties":{"tonight":{"type":"array","items":{"$ref":"#/components/schemas/TonightItem"}},"frontDeskNotes":{"type":"array","items":{"type":"string"}}},"required":["tonight","frontDeskNotes"]},"HotelLocation":{"type":"object","properties":{"city":{"type":"string"},"citySlug":{"type":"string"},"latitude":{"type":"number"},"longitude":{"type":"number"},"address":{"type":"string"},"timezone":{"type":"string"}}},"GuestProfile":{"type":"object","properties":{"adults":{"type":"integer"},"children":{"type":"integer"},"childAges":{"type":"array","items":{"type":"integer"}},"budgetPreference":{"type":"string"},"returningGuest":{"type":"boolean"},"firstTimeVisitor":{"type":"boolean"},"wheelchairAccessible":{"type":"boolean"},"accessibilityNeeds":{"type":"array","items":{"type":"string"}},"weather":{"type":"string"},"tripPurpose":{"type":"string"}}},"RecommendRequest":{"type":"object","required":["citySlug","checkIn","checkOut"],"properties":{"citySlug":{"type":"string"},"checkIn":{"type":"string","format":"date"},"checkOut":{"type":"string","format":"date"},"propertyId":{"type":"string"},"guestSegment":{"type":"string"},"categories":{"type":"array","items":{"type":"string"}},"maxResults":{"type":"integer","minimum":1,"maximum":24},"hotelLocation":{"$ref":"#/components/schemas/HotelLocation"},"guestProfile":{"$ref":"#/components/schemas/GuestProfile"},"preferences":{"type":"object","additionalProperties":true},"language":{"type":"string"}}},"Recommendation":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"category":{"type":"string"},"price":{"type":"number"},"currency":{"type":"string"},"imageUrl":{"type":"string","format":"uri","nullable":true},"bookingUrl":{"type":"string","format":"uri"},"matchScore":{"type":"number"},"tags":{"type":"array","items":{"type":"string"}},"audience":{"type":"array","items":{"type":"string"}},"accessibility":{"type":"object","properties":{"wheelchairAccessible":{"type":"boolean"},"strollerFriendly":{"type":"boolean"},"physicalLevel":{"type":"string","nullable":true}}},"duration":{"type":"string","nullable":true},"urgency":{"type":"array","items":{"type":"string"}},"supplier":{"type":"string","nullable":true},"rating":{"type":"number","nullable":true}},"required":["id","title","category","price","currency","bookingUrl","matchScore","tags","audience","accessibility","urgency"]},"RecommendResponse":{"type":"object","properties":{"recommendations":{"type":"array","items":{"$ref":"#/components/schemas/Recommendation"}},"curation":{"type":"object","nullable":true,"additionalProperties":true}},"required":["recommendations"]},"DiscoverBudget":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"},"currency":{"type":"string"}}},"DiscoverPreferences":{"type":"object","properties":{"audience":{"type":"array","items":{"type":"string"}},"categories":{"type":"array","items":{"type":"string"}},"indoor":{"type":"boolean"},"accessibility":{"type":"boolean"},"duration":{"type":"object","properties":{"min":{"type":"integer"},"max":{"type":"integer"}}},"language":{"type":"string"}}},"DiscoverContext":{"type":"object","properties":{"previouslyViewed":{"type":"array","items":{"type":"string"}},"previouslyBooked":{"type":"array","items":{"type":"string"}},"source":{"type":"string"},"sessionId":{"type":"string"}}},"DiscoverRequest":{"type":"object","required":["query"],"properties":{"query":{"type":"string"},"city":{"type":"string"},"date":{"type":"string","format":"date"},"pax":{"type":"integer"},"budget":{"$ref":"#/components/schemas/DiscoverBudget"},"preferences":{"$ref":"#/components/schemas/DiscoverPreferences"},"context":{"$ref":"#/components/schemas/DiscoverContext"},"maxResults":{"type":"integer","minimum":1,"maximum":24},"explain":{"type":"boolean"}}},"DiscoverResult":{"type":"object","properties":{"product":{"type":"object","additionalProperties":true},"score":{"type":"number"},"matchReasons":{"type":"array","items":{"type":"string"}},"explanation":{"type":"string"},"rank":{"type":"integer"},"bookingUrl":{"type":"string","format":"uri"}},"required":["product","score","matchReasons","rank","bookingUrl"]},"ParsedIntent":{"type":"object","properties":{"city":{"type":"string","nullable":true},"date":{"type":"string","nullable":true},"pax":{"type":"integer"},"budget":{"type":"object","nullable":true,"properties":{"min":{"type":"number"},"max":{"type":"number"},"currency":{"type":"string"}}},"categories":{"type":"array","items":{"type":"string"}},"audience":{"type":"array","items":{"type":"string"}},"mood":{"type":"array","items":{"type":"string"}},"constraints":{"type":"array","items":{"type":"string"}},"timeOfDay":{"type":"string","nullable":true},"weather":{"type":"string","nullable":true},"occasion":{"type":"string","nullable":true}},"required":["pax","categories","audience","mood","constraints"]},"DiscoverResponse":{"type":"object","properties":{"city":{"type":"string","nullable":true},"query":{"type":"string"},"parsedIntent":{"$ref":"#/components/schemas/ParsedIntent"},"recommendations":{"type":"array","items":{"$ref":"#/components/schemas/DiscoverResult"}},"totalMatches":{"type":"integer"},"took":{"type":"integer"},"aiModel":{"type":"string"}},"required":["query","parsedIntent","recommendations","totalMatches","took"]},"GuestDetails":{"type":"object","required":["email"],"properties":{"name":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string","format":"email"},"phone":{"type":"string"},"countryCode":{"type":"string"}}},"BookRequest":{"type":"object","required":["experienceId","slotId","guestDetails","quantity","pmsType"],"properties":{"experienceId":{"type":"string"},"slotId":{"type":"string","description":"Slot token or identifier returned by the booking flow. When booking directly from ChatGPT, use a stable slot token agreed by the client and server."},"guestDetails":{"$ref":"#/components/schemas/GuestDetails"},"quantity":{"type":"integer","minimum":1,"maximum":20},"pmsType":{"type":"string","description":"Use a source identifier such as openai for direct GPT Actions bookings."},"pmsOrderData":{"type":"object","additionalProperties":true}}},"BookingConfirmation":{"type":"object","properties":{"experienceId":{"type":"string"},"experienceTitle":{"type":"string"},"supplier":{"type":"string"},"slotId":{"type":"string"},"date":{"type":"string"},"time":{"type":"string"},"guest":{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string","format":"email"},"phone":{"type":"string"}}},"quantity":{"type":"integer"},"totalAmount":{"type":"number"},"currency":{"type":"string"}}},"PreparedCart":{"type":"object","properties":{"experienceId":{"type":"string"},"experienceSlug":{"type":"string"},"citySlug":{"type":"string"},"slotId":{"type":"string"},"quantity":{"type":"integer"},"unitAmount":{"type":"number"},"totalAmount":{"type":"number"},"currency":{"type":"string"}}},"BookResponse":{"type":"object","properties":{"bookingId":{"type":"string"},"status":{"type":"string"},"confirmation":{"$ref":"#/components/schemas/BookingConfirmation"},"eTicketUrl":{"type":"string","format":"uri"},"pmsOrderId":{"type":"string"},"mewsOrderId":{"type":"string"},"pmsSyncError":{"type":"string"},"checkoutUrl":{"type":"string","format":"uri"},"expiresAt":{"type":"string","format":"date-time"},"cart":{"$ref":"#/components/schemas/PreparedCart"}}}}}}