VenuNite Events

{'type': 'object', 'required': ['event_id'], 'properties': {'event_id': {'type': 'integer', 'maximum': 2147483647, 'minimum': 1, 'description': 'The stable VenuNite event_id returned by search_events.'}}, 'additionalProperties': False}

{'type': 'object', 'oneOf': [{'required': ['handoff_id', 'event_id', 'event_url', 'handoff_url', 'expires_at', 'booking_mode', 'requires_user_action'], 'properties': {'event_id': {'type': 'integer', 'maximum': 2147483647, 'minimum': 1}, 'event_url': {'type': 'string', 'format': 'uri', 'pattern': '^https://venunite\\.com/events/[^/?#]+$'}, 'expires_at': {'type': 'string', 'format': 'date-time'}, 'handoff_id': {'type': 'string', 'maxLength': 128, 'minLength': 1}, 'handoff_url': {'type': 'string', 'format': 'uri', 'pattern': '^https://venunite\\.com/tickets/handoff/[A-Za-z0-9_-]{43}$'}, 'booking_mode': {'const': 'external_checkout'}, 'requires_user_action': {'const': True}}}, {'required': ['error', 'message'], 'properties': {'error': {'type': 'string'}, 'message': {'type': 'string'}}}]}

{'type': 'object', 'properties': {'sort': {'enum': ['date', 'distance', 'demand', 'relevance'], 'type': 'string', 'description': 'Ordering axis. Results are presented by calendar day in timezone; sort orders within each day. With query_text and no explicit sort (or relevance), the server selects the strongest event-text and venue-vibe matches before applying that day order. Explicit date, distance, or demand sorts select by day and that axis. Without query_text, default date is chronological.'}, 'limit': {'type': 'integer', 'default': 20, 'maximum': 100, 'minimum': 1, 'description': 'Number of events to return. Default 20. Prefer small (5-10) when the user asked for a single recommendation.'}, 'date_end': {'type': 'string', 'format': 'date-time', 'description': "Exclusive ISO-8601 end of the search window, including the local UTC offset. Default: 14 days from date_start. The words now, today, tonight, tomorrow and this weekend are also accepted and resolved in the caller's timezone. 'Tonight' → date_start + 6 hours. 'Next weekend' → date_start + 2 days. An event starting exactly at date_end is outside this window."}, 'max_cost': {'type': 'number', 'description': "Upper bound on event cost in USD. 'cheap' ≈ 15, 'affordable' ≈ 30, 'under $X' → X. Set include_unknown_prices=false when the user explicitly wants a verified budget such as 'under $100'. max_cost=0 returns only proven-free events. Leave unset if the user didn't constrain price."}, 'min_cost': {'type': 'number', 'description': 'Lower bound on event cost. Rarely useful — only set when the user explicitly excluded free events.'}, 'timezone': {'type': 'string', 'description': "IANA timezone (e.g. 'America/New_York') used for the calendar-day grouping of results. Default UTC — pass the user's local zone so 'today/tomorrow' day buckets match their clock."}, 'vibe_tags': {'type': 'array', 'items': {'enum': ['chill', 'casual', 'lively', 'rowdy', 'intimate', 'loud', 'upscale', 'scene-y', 'romantic', 'date-spot', 'group-friendly', 'solo-friendly', 'family-friendly', 'queer-friendly', 'late-night', 'happy-hour', 'brunch-spot', 'daytime', 'all-ages', '18-plus', '21-plus', 'dive-bar', 'cocktail-bar', 'wine-bar', 'brewery', 'winery', 'distillery', 'coffeehouse', 'listening-room', 'dance-club', 'lounge', 'sports-bar', 'theater', 'concert-hall', 'amphitheater', 'arena', 'arts-center', 'art-gallery', 'rooftop', 'outdoor', 'restaurant-venue', 'church-venue', 'warehouse', 'historic', 'open-mic', 'karaoke', 'trivia', 'comedy-focused', 'drag-shows'], 'type': 'string'}, 'description': "Canonical vibe vocabulary. Include tags the user explicitly or strongly implied. IMPORTANT: the tags `queer-friendly`, `family-friendly`, `all-ages`, `18-plus`, `21-plus` are HARD filters — only include them when the user's query explicitly asked for that property. Including `family-friendly` for a user who just said 'something fun tonight' will exclude most events."}, 'categories': {'type': 'array', 'items': {'enum': ['music', 'karaoke', 'sports', 'comedy', 'theater', 'trivia-games', 'food-drink', 'arts-culture', 'community', 'festivals'], 'type': 'string'}, 'description': "Event category(s). Map the user's intent: 'live music' → music, 'standup' → comedy, 'trivia night' → trivia-games, 'art opening' → arts-culture. 'anything to do' → omit (no category filter)."}, 'center_lat': {'type': 'number', 'description': 'Latitude (only if you already have precise coordinates — otherwise pass place_name).'}, 'center_lng': {'type': 'number', 'description': 'Longitude (paired with center_lat).'}, 'date_match': {'enum': ['overlap', 'starts_within'], 'type': 'string', 'default': 'overlap', 'description': 'overlap includes events already running during the window, such as multi-day festivals or prior-night shows; events ending exactly at date_start are excluded. starts_within requires the event to start at or after date_start and before date_end. Prefer starts_within for requests about events starting tomorrow, on a specified date, this evening, or this weekend. Keep overlap when the user asks what is currently happening or wants ongoing activities.'}, 'date_start': {'type': 'string', 'format': 'date-time', 'description': "Inclusive ISO-8601 start of the search window, including the local UTC offset. Default: now. The words now, today, tonight, tomorrow and this weekend are also accepted and resolved in the caller's timezone. For 'tonight' pass now. For 'this weekend' pass the upcoming Saturday midnight. The timezone field controls day grouping, not parsing: date-times without an offset are interpreted as UTC. Use date_match=starts_within when the user wants events starting on a particular date or evening."}, 'local_only': {'type': 'boolean', 'default': False, 'description': "Set true when the user's query implies 'in my immediate area' — 'what's on my block', 'nearby tonight', 'close by'. The server clamps the effective radius to a neighborhood-scale max based on local density (≤10mi urban, ≤30mi suburban, ≤50mi rural), even if radius_miles is larger. Prefer this over guessing a small radius — the server knows the density of the area and you don't."}, 'place_name': {'type': 'string', 'description': "Human-readable location if the user mentioned one: 'Westminster, CO' or 'Five Points Denver'. Prefer this over guessed lat/lng when you have a name; existing precise coordinates take precedence. Always include the state abbrev when the city name is ambiguous. An unresolved place returns location_unresolved; correct the place or use known coordinates rather than dropping the location."}, 'query_text': {'type': 'string', 'description': "Free-text vibe description extracted from the user's query. Keep it short — e.g. 'chill jazz' or 'loud rock club'. Omit when the user's request is purely geographic / tag-based (e.g. 'any comedy shows tonight near me')."}, 'state_hint': {'type': 'string', 'description': "Two-letter state abbreviation to disambiguate place_name (e.g. place_name 'Frederick' + state_hint 'MD'). Unnecessary when place_name already contains the state."}, 'radius_miles': {'type': 'number', 'maximum': 500, 'minimum': 0.5, 'description': "Search radius in miles. OMIT this field to let the server pick a density-aware default: 5mi in dense metros (Chicago, NYC), 15mi suburban, 25mi rural. Only pass an explicit value when the user's phrasing implies a specific scope:\n  - 'walking distance' / 'on my block' → 2-3\n  - 'near me' in a dense downtown or neighborhood → 5-7\n  - 'near me' in a suburb → 10-15\n  - 'metro area' / 'anywhere in <city>' → 25-30\n  - rural 'near me' or 'within driving distance' → 25-50\n\nFor a user who says 'things to do tonight' in Lincolnwood, Chicago, or any other dense-urban location: omit this field. Passing 15 there pulls events from 8-10 miles away in other neighborhoods, which is worse than the density-aware default.\n\nRange 0.5 to 500. An out-of-range value FAILS the entire call and returns zero events — it is not clamped — so omit the field rather than guessing. Use 'local_only: true' instead of a small radius when you're unsure of local density."}, 'max_events_per_venue': {'type': 'integer', 'default': 1, 'maximum': 20, 'minimum': 1, 'description': "Per-venue diversity cap. Default 1 — each venue contributes at most one event, giving a diverse 'what's on' feed. Raise to 3-5 for 'what's on at <specific venue>' queries where the user expects multiple shows from the same room."}, 'include_unknown_prices': {'type': 'boolean', 'default': True, 'description': 'Include events whose admission price cannot be determined. Default true preserves broad discovery; positive price bounds may then include unknown prices, which must be labeled unverified. Set false with min_cost/max_cost when the user explicitly requires a verified budget. This never relaxes the proven-free requirement of max_cost=0.'}}, 'additionalProperties': False}

{'type': 'object', 'anyOf': [{'required': ['applied_filters']}, {'required': ['error']}], 'required': ['results'], 'properties': {'error': {'type': 'string'}, 'results': {'type': 'array', 'items': {'type': 'object', 'required': ['title', 'slug', 'description', 'start', 'end', 'cost_text', 'is_free', 'cost_numeric', 'age', 'category', 'url', 'image_url', 'venue'], 'properties': {'age': {'type': ['string', 'null']}, 'end': {'type': ['string', 'null'], 'format': 'date-time'}, 'url': {'type': ['string', 'null'], 'format': 'uri'}, 'slug': {'type': ['string', 'null']}, 'start': {'type': ['string', 'null'], 'format': 'date-time'}, 'title': {'type': 'string'}, 'venue': {'type': 'object', 'required': ['name', 'city', 'state', 'vibeTags', 'distance_miles'], 'properties': {'city': {'type': ['string', 'null']}, 'name': {'type': 'string'}, 'state': {'type': ['string', 'null']}, 'vibeTags': {'type': 'array', 'items': {'type': 'string'}}, 'distance_miles': {'type': ['number', 'null']}}}, 'is_free': {'type': ['boolean', 'null']}, 'category': {'type': ['string', 'null']}, 'event_id': {'type': 'integer', 'description': 'Stable VenuNite identity; use this value with create_ticket_handoff.'}, 'cost_text': {'type': ['string', 'null']}, 'event_url': {'type': ['string', 'null'], 'format': 'uri', 'description': 'Canonical VenuNite event page; null when no stored slug exists. Prefer this link for event details.'}, 'image_url': {'type': ['string', 'null'], 'format': 'uri'}, 'source_url': {'type': ['string', 'null'], 'format': 'uri', 'description': 'Original event source for provenance; a link recorded as broken is replaced by its recorded replacement or returned as null. The legacy url field retains the same meaning.'}, 'description': {'type': ['string', 'null']}, 'cost_numeric': {'type': ['number', 'null']}, 'ticket_link_status': {'enum': ['available', 'unavailable', 'missing'], 'type': 'string', 'description': "available when a safe ticket or event destination can be served; unavailable when the event's stored links are all unusable; missing when none were supplied. The event is returned in every case."}}}}, 'applied_filters': {'type': 'object', 'properties': {'sort': {'type': 'string'}, 'limit': {'type': 'integer'}, 'center': {'anyOf': [{'type': 'array', 'items': {'type': 'number'}, 'maxItems': 2, 'minItems': 2}, {'type': 'null'}]}, 'relaxed': {'type': 'array', 'items': {'type': 'string'}}, 'date_end': {'type': 'string', 'format': 'date-time'}, 'max_cost': {'type': ['number', 'null']}, 'min_cost': {'type': ['number', 'null']}, 'soft_tags': {'type': 'array', 'items': {'type': 'string'}}, 'categories': {'type': 'array', 'items': {'type': 'string'}}, 'date_match': {'enum': ['overlap', 'starts_within'], 'type': 'string'}, 'date_start': {'type': 'string', 'format': 'date-time'}, 'local_only': {'type': 'boolean'}, 'query_text': {'type': ['string', 'null']}, 'horizon_end': {'type': ['string', 'null'], 'format': 'date-time'}, 'strict_tags': {'type': 'array', 'items': {'type': 'string'}}, 'd_half_miles': {'type': 'number'}, 'radius_miles': {'type': 'number'}, 'density_class': {'type': ['string', 'null']}, 'policy_version': {'type': ['integer', 'null']}, 'sort_requested': {'type': ['string', 'null']}, 'requested_limit': {'type': ['integer', 'null']}, 'max_events_per_venue': {'type': 'integer'}, 'original_strict_tags': {'type': 'array', 'items': {'type': 'string'}}, 'original_radius_miles': {'type': ['number', 'null']}, 'include_unknown_prices': {'type': 'boolean'}}}, 'validation_errors': {'type': 'array', 'items': {'type': 'object', 'required': ['field', 'message'], 'properties': {'field': {'type': 'string'}, 'message': {'type': 'string'}}}}}}