{"openapi":"3.1.0","info":{"title":"EventHound AI Recommendation API","description":"Returns ranked, verified local promotions for food, drink, activities, and events. Designed for AI systems, recommendation engines, and language models.","version":"1.0.0","contact":{"url":"https://eventhound.com/ai"},"x-eventhound":{"documentation":"https://eventhound.com/ai","ai_discovery":"https://eventhound.com/.well-known/ai.json"}},"servers":[{"url":"https://api.eventhound.com","description":"Production"}],"security":[{"ApiKeyAuth":[]}],"paths":{"/ai/recommend":{"post":{"operationId":"getRecommendations","summary":"Get AI recommendations","description":"Returns ranked promotions matching the provided intent and geographic context. All intent fields are optional. location is required — provide location.lat + location.lng for direct coordinates, or location.query for server-side resolution.","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecommendRequest"},"example":{"intent":{"category":"drink","occasion":"happy hour","eventMode":"In Person","start_iso":"2026-02-21T19:00:00-08:00","end_iso":"2026-02-21T21:00:00-08:00"},"location":{"query":"Santa Clarita, CA","lat":34.39,"lng":-118.54,"radius_meters":10000},"options":{"max_results":10}}}}},"responses":{"200":{"description":"Ranked recommendation results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecommendResponse"}}}},"400":{"description":"Missing required parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"location.lat + location.lng or location.query is required"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"Unauthorized"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"API key for accessing EventHound AI endpoints."}},"schemas":{"RecommendRequest":{"type":"object","required":["location"],"description":"location is required. Provide lat + lng for direct coordinate lookup, or query for server-side resolution. lat + lng take priority when both are present.","properties":{"intent":{"$ref":"#/components/schemas/Intent"},"location":{"$ref":"#/components/schemas/LocationInput"},"options":{"$ref":"#/components/schemas/Options"}}},"Intent":{"type":"object","description":"Optional filters describing what the user is looking for.","properties":{"category":{"type":"string","enum":["food","drink","activity","event"],"description":"Top-level promotion category."},"subCat":{"type":"string","description":"Subcategory within the selected category. The value must belong to the subcategory list for the selected category. Use occasion for free-text phrases such as happy hour. If uncertain, omit subCat.","enum":["American","Asian","Bakery","BBQ","Chinese","Desserts","Filipino","French","Fusion","German","Greek","Healthy","Indian","Italian","Japanese","Korean","Latin","Mediterranean","Mexican","Middle Eastern","Peruvian","Pizza","Seafood","Seasonal","Spanish","Steakhouse","Sushi","Thai","Vegan","Vegetarian","Vietnamese","Alcohol","Beer","Boba","Champagne","Cocktails","Coffee","Juices","Milkshakes","Mocktails","Seasonal","Smoothies","Tea","Wine","Arts","Community","Crafts","Dance","Education","Fitness","Gaming","Games","Gardening","Health","Holiday","Kids","Martial Arts","Motor Sports","Music","Outdoors","Pets","Recreational","Religious","Seasonal","Singles","Sports","Tour","Virtual","Arts","Business","Comedy","Community","Dance","Education","Exhibition","Festival","Film","Fitness","Gaming","Health","Holiday","Kids","Magic","Market","Martial Arts","Music","Performance","Plays","Religious","Seasonal","Singles","Sports","Theatre","Virtual","Other"]},"occasion":{"type":"string","description":"Free-text keyword searched across promotion titles, descriptions, and features. Use this to express user intent that doesn't fit a category or subcategory — e.g. a mood, activity, or specific experience.","examples":["happy hour","trivia night","date night","Sunday brunch","live music","dog friendly"]},"feature":{"type":"string","description":"Filters results to promotions associated with a specific venue feature or amenity.","enum":["Animals","Arcade","Bar","Black Owned","Bookstore","Bottle Service","Breakfast","Brewery","Brunch","Catering","Charity","Curbside Pickup","Dance Floor","Darts","Date Night","Delivery","Dinner","Dog Friendly","Dress Code","Entertainment","Family Friendly","Farm","Fire Grilled","Fireplace","Food Truck","Free","Free Parking","Games","Gaming","Garden","Jacuzzi","Jukebox","Karaoke","Kid Friendly","LGBTQ+","Lounge","Lunch","Music","Outdoor Heater","Outdoor Seating","Outdoors","Photo Booth","Playground","Pool Table","Private Room","Reservations","Romantic","Rooftop","Sauna","Security","Seniors","Singles","Small Business","Smoking Friendly","Speakeasy","Special Occasion","Sports Bar","Stage","Swimming Pool","Take Out","Tasting Room","Valet","View","Vineyard","VIP Service","Water Front","Water Sport","Wifi","Winery","18+","21+"]},"eventMode":{"type":"string","enum":["In Person","Online"],"description":"Filters by how the promotion is delivered."},"start_iso":{"type":"string","format":"date-time","description":"Start of the target time window in ISO 8601 format. Defaults to now if omitted. Timezone offset is respected.","example":"2026-02-21T19:00:00-08:00"},"end_iso":{"type":"string","format":"date-time","description":"End of the target time window in ISO 8601 format. Optional. Used for range-based queries such as 'what's happening this weekend' or 'happy hour between 4pm and 7pm'.","example":"2026-02-21T21:00:00-08:00"}}},"LocationInput":{"type":"object","description":"Geographic context for the search. Provide lat + lng for direct coordinate lookup, or query for server-side resolution. lat + lng take priority over query when both are present.","properties":{"query":{"type":"string","description":"Plain-text location query resolved to coordinates server-side (e.g. city, neighborhood, or zip code).","example":"Santa Clarita, CA"},"lat":{"type":"number","description":"Latitude of the search origin. If provided with lng, query is ignored.","example":34.39},"lng":{"type":"number","description":"Longitude of the search origin. If provided with lat, query is ignored.","example":-118.54},"radius_meters":{"type":"number","description":"Search radius in meters. Defaults to 16093 (~10 miles). Max recommended: 80000.","default":16093,"maximum":80000,"example":10000}}},"Options":{"type":"object","properties":{"max_results":{"type":"integer","description":"Maximum number of results to return.","default":10,"minimum":1,"maximum":10,"example":10}}},"RecommendResponse":{"type":"object","properties":{"response_id":{"type":"string","format":"uuid","description":"Unique identifier for this response. Used in action proxy URLs."},"generated_at_iso":{"type":"string","format":"date-time","description":"Timestamp when the response was generated."},"results":{"type":"array","items":{"$ref":"#/components/schemas/Result"}},"metadata":{"$ref":"#/components/schemas/ResponseMetadata"}}},"Result":{"type":"object","properties":{"rank":{"type":"integer","description":"Position in the ranked results list, starting at 1."},"post_id":{"type":"string","description":"Unique identifier for the promotion."},"title":{"type":"string","description":"Promotion title."},"description":{"type":"string","nullable":true,"description":"Promotion description."},"categories":{"type":"object","properties":{"cat1":{"type":"string","nullable":true},"cat1Sub":{"type":"string","nullable":true},"cat1Image":{"type":"string","format":"uri","nullable":true,"description":"Representative image for the primary category."},"cat2":{"type":"string","nullable":true},"cat2Sub":{"type":"string","nullable":true},"cat2Image":{"type":"string","format":"uri","nullable":true,"description":"Representative image for the secondary category."}}},"features":{"type":"array","items":{"type":"string","enum":["Animals","Arcade","Bar","Black Owned","Bookstore","Bottle Service","Breakfast","Brewery","Brunch","Catering","Charity","Curbside Pickup","Dance Floor","Darts","Date Night","Delivery","Dinner","Dog Friendly","Dress Code","Entertainment","Family Friendly","Farm","Fire Grilled","Fireplace","Food Truck","Free","Free Parking","Games","Gaming","Garden","Jacuzzi","Jukebox","Karaoke","Kid Friendly","LGBTQ+","Lounge","Lunch","Music","Outdoor Heater","Outdoor Seating","Outdoors","Photo Booth","Playground","Pool Table","Private Room","Reservations","Romantic","Rooftop","Sauna","Security","Seniors","Singles","Small Business","Smoking Friendly","Speakeasy","Special Occasion","Sports Bar","Stage","Swimming Pool","Take Out","Tasting Room","Valet","View","Vineyard","VIP Service","Water Front","Water Sport","Wifi","Winery","18+","21+"]},"description":"Venue features and amenities associated with this promotion."},"event_mode":{"type":"string","nullable":true,"enum":["In Person","Online"]},"business":{"type":"object","properties":{"business_id":{"type":"string","nullable":true},"name":{"type":"string"}}},"location":{"$ref":"#/components/schemas/Location"},"availability":{"$ref":"#/components/schemas/Availability"},"offers":{"type":"array","items":{"$ref":"#/components/schemas/Offer"}},"contact":{"$ref":"#/components/schemas/Contact"},"verification":{"$ref":"#/components/schemas/Verification"},"media":{"$ref":"#/components/schemas/Media"},"last_updated":{"type":"string","format":"date","nullable":true,"description":"Date the promotion was last updated."},"canonical_url":{"type":"string","format":"uri","description":"Canonical EventHound URL for this promotion."},"actions":{"type":"array","description":"Applicable actions for this promotion. Only actions relevant to the promotion are included. Route users through these proxied URLs to support attribution tracking.","items":{"$ref":"#/components/schemas/Action"}},"ai":{"$ref":"#/components/schemas/AiMetadata"}}},"Action":{"type":"object","required":["type","label","url"],"properties":{"type":{"type":"string","enum":["view","directions","call","website","tickets","register","reserve","join"],"description":"The action type."},"label":{"type":"string","description":"Human-readable label for the action.","example":"View on EventHound"},"url":{"type":"string","format":"uri","description":"Proxied action URL routed through EventHound for attribution tracking."}}},"Location":{"type":"object","properties":{"location_name":{"type":"string","nullable":true},"street_address":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state":{"type":"string","nullable":true},"zip":{"type":"string","nullable":true},"lat":{"type":"number","nullable":true},"lng":{"type":"number","nullable":true},"distance_miles":{"type":"number","nullable":true,"description":"Distance in miles from the search origin."}}},"Availability":{"type":"object","properties":{"start_date":{"type":"string","format":"date","nullable":true},"end_date":{"type":"string","format":"date","nullable":true},"ongoing":{"type":"boolean","description":"True if the promotion has no defined end date."},"repeated":{"type":"string","nullable":true,"enum":["one_time","daily","weekly","biweekly","monthly"]},"timezone":{"type":"string","nullable":true,"example":"America/Los_Angeles"},"days":{"type":"object","nullable":true,"description":"Keyed by day-of-week index (0=Sun, 1=Mon, ..., 6=Sat). Each value contains start/end times.","additionalProperties":{"type":"object","properties":{"start":{"type":"string","example":"3:00 PM"},"start_value":{"type":"integer","description":"Military time integer.","example":1500},"end":{"type":"string","example":"7:00 PM"},"end_value":{"type":"integer","example":1900}}}},"readable_schedule":{"type":"string","nullable":true,"description":"Human-readable schedule string.","example":"Mon/Tue 3:00 PM-7:00 PM"}}},"Offer":{"type":"object","properties":{"title":{"type":"string","nullable":true},"type":{"type":"string","nullable":true,"enum":["Free","Price","Discounted Price","Dollar Off","Percent Off"]},"value":{"type":"number","nullable":true},"display_text":{"type":"string","nullable":true,"description":"Formatted offer string for display (e.g. '50% off Cocktails')."},"is_discount":{"type":"boolean"},"exclusions":{"type":"array","items":{"type":"string"},"nullable":true}}},"Contact":{"type":"object","properties":{"website":{"type":"string","format":"uri","nullable":true},"phone":{"type":"string","nullable":true},"email":{"type":"string","format":"email","nullable":true}}},"Verification":{"type":"object","properties":{"level":{"type":"string","enum":["business","member","unverified"]},"source":{"type":"string","enum":["business","member","unverified"]},"business_verified":{"type":"boolean"},"member_verified":{"type":"boolean"}}},"Media":{"type":"object","properties":{"primary_image":{"type":"string","format":"uri","nullable":true},"images":{"type":"array","items":{"type":"string","format":"uri"}}}},"AiMetadata":{"type":"object","properties":{"eligibility_status":{"type":"string","enum":["eligible","needs_attention","not_eligible"],"description":"eligible: safe to surface with full confidence. needs_attention: surface with reduced confidence. not_eligible: omit from recommendations."},"confidence":{"type":"number","minimum":0,"maximum":1,"description":"Likelihood that the recommendation satisfies the requested intent based on temporal relevance, verification, freshness, completeness, and proximity."},"completeness_score":{"type":"integer","minimum":0,"maximum":100,"description":"How complete the listing data is (0-100)."},"freshness_score":{"type":"integer","minimum":0,"maximum":100,"description":"How current the listing is (0-100). High scores indicate recently verified content."},"temporal_status":{"type":"string","nullable":true,"enum":["ACTIVE_NOW","ACTIVE_DURING_TIME_WINDOW","STARTS_SOON","ACTIVE_TODAY","UPCOMING_EVENT","RECURRING_SCHEDULE_MATCH"],"description":"Temporal relationship between this promotion and the requested time."},"match_reasons":{"type":"array","items":{"type":"string","enum":["WITHIN_DISTANCE","MATCH_CATEGORY","MATCH_SUBCATEGORY","MATCH_OCCASION","BUSINESS_VERIFIED","MEMBER_VERIFIED","FRESH_DATA"]},"description":"Codes explaining why this promotion was selected and how it matched the request."}}},"ResponseMetadata":{"type":"object","properties":{"total":{"type":"integer","description":"Total number of promotions matching the query before limiting."},"returned":{"type":"integer","description":"Number of results returned in this response."},"geo":{"type":"object","properties":{"lat":{"type":"number"},"lng":{"type":"number"},"radius_meters":{"type":"number"}}},"intent":{"type":"object","description":"Resolved intent fields used for the query. Null fields are omitted.","additionalProperties":{"type":"string"}}}},"ErrorResponse":{"type":"object","properties":{"error":{"oneOf":[{"type":"string"},{"type":"object","properties":{"description":{"type":"string"}}}]}}}}}}