{"openapi":"3.1.0","info":{"title":"HappyKava Public API v1","version":"2026-09-01","description":"Read-only public API and CSV exports for HappyKava kava bar discovery, authoritative BestKavaBar search placement tiers, city aggregates, events, deals, aggregate menu prices, query-based brand matches, and public strain catalog rows. Responses use public directory and anon-safe API data only.","termsOfService":"https://happykava.app/kava-data/open-dataset#attribution","contact":{"name":"HappyKava","url":"https://happykava.app"}},"servers":[{"url":"https://happykava.app/api/public/v1","description":"Production public API v1"}],"externalDocs":{"description":"Open dataset documentation, attribution terms, and privacy boundaries.","url":"https://happykava.app/kava-data/open-dataset"},"tags":[{"name":"Discovery","description":"Public kava bar, city, event, and deal discovery resources."},{"name":"Dataset","description":"Machine-readable dataset metadata and CSV exports."},{"name":"Catalog","description":"Public catalog and structured-menu discovery resources."}],"paths":{"/":{"get":{"tags":["Dataset"],"summary":"List public API v1 resources","operationId":"getPublicApiV1Index","responses":{"200":{"description":"Public API v1 resource index.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiIndex"}}}}}}},"/openapi.json":{"get":{"tags":["Dataset"],"summary":"Get the OpenAPI contract for public API v1","operationId":"getPublicApiV1OpenApi","responses":{"200":{"description":"OpenAPI 3.1 contract for HappyKava public API v1.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/dataset":{"get":{"tags":["Dataset"],"summary":"Get the open dataset manifest","operationId":"getOpenDatasetManifest","responses":{"200":{"description":"Dataset resources, attribution terms, refresh policy, and privacy boundaries.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasetManifest"}}}}}}},"/bars":{"get":{"tags":["Discovery"],"summary":"Search public kava bar directory rows","operationId":"listPublicBars","parameters":[{"$ref":"#/components/parameters/State"},{"$ref":"#/components/parameters/City"},{"$ref":"#/components/parameters/Query"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Offset"}],"responses":{"200":{"description":"Paginated public kava bar rows.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BarsResponse"}}}},"400":{"description":"Invalid or missing query parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"The requested public dataset resource is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}}}}},"/bars/{barId}":{"get":{"tags":["Discovery"],"summary":"Get one public kava bar with visit details","operationId":"getPublicBarDetail","parameters":[{"$ref":"#/components/parameters/BarId"}],"responses":{"200":{"description":"Public bar detail with hours, menu, and recent reviews.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BarDetailResponse"}}}},"404":{"description":"No public bar matched the id or slug.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"The requested public dataset resource is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}}}}},"/reviews":{"get":{"tags":["Discovery"],"summary":"List published public community reviews","operationId":"listPublicReviews","parameters":[{"$ref":"#/components/parameters/BarIdQuery"},{"$ref":"#/components/parameters/State"},{"$ref":"#/components/parameters/City"},{"$ref":"#/components/parameters/Query"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Offset"}],"responses":{"200":{"description":"Paginated public reviews without user ids or moderation fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReviewsResponse"}}}},"400":{"description":"Invalid or missing query parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"The requested public dataset resource is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}}}}},"/bars.csv":{"get":{"tags":["Dataset"],"summary":"Export public kava bar directory rows as CSV","operationId":"exportPublicBarsCsv","parameters":[{"$ref":"#/components/parameters/State"},{"$ref":"#/components/parameters/City"},{"$ref":"#/components/parameters/Query"}],"responses":{"200":{"description":"Public kava bar directory CSV export.","content":{"text/csv":{"schema":{"type":"string","description":"Public kava bar directory CSV export."}}}},"400":{"description":"Invalid or missing query parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"The requested public dataset resource is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}}}}},"/open-now":{"get":{"tags":["Discovery"],"summary":"Search public kava bars that appear open now","operationId":"listPublicOpenNowBars","parameters":[{"$ref":"#/components/parameters/State"},{"$ref":"#/components/parameters/City"},{"$ref":"#/components/parameters/Query"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Offset"}],"responses":{"200":{"description":"Paginated public kava bars that appear open now from posted hours.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenNowResponse"}}}},"400":{"description":"Invalid or missing query parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"The requested public dataset resource is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}}}}},"/directory-highlights":{"get":{"tags":["Discovery"],"summary":"List sponsored directory placements","description":"Returns paid/sponsored Spotlight campaign placements and Featured bars whose effective HappyKava plan is exactly pro or premium. This resource is merchandising data, not an organic ranking.","operationId":"getDirectoryHighlights","parameters":[{"$ref":"#/components/parameters/State"},{"$ref":"#/components/parameters/SpotlightLimit"},{"$ref":"#/components/parameters/FeaturedLimit"}],"responses":{"200":{"description":"Eligible sponsored placements. Empty eligibility returns both arrays empty.","headers":{"Cache-Control":{"schema":{"type":"string"},"description":"public, max-age=0, s-maxage=60, must-revalidate"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DirectoryHighlightsResponse"},"example":{"apiVersion":"2026-07-25","resource":"directory_highlights","generatedAt":"2026-07-25T18:00:00.000Z","filters":{"state":null},"limits":{"spotlight":2,"featured":12},"counts":{"spotlightedBars":0,"featuredBars":0},"spotlightedBars":[],"featuredBars":[]}}}},"400":{"description":"Invalid state filter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DirectoryHighlightsErrorResponse"},"example":{"apiVersion":"2026-07-25","resource":"directory_highlights","generatedAt":"2026-07-25T18:00:00.000Z","error":{"code":"invalid_state","message":"State must be a valid US postal code or /kava-bars state slug."}}}}},"503":{"description":"The kill switch is disabled or authoritative eligibility data is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DirectoryHighlightsErrorResponse"},"example":{"apiVersion":"2026-07-25","resource":"directory_highlights","generatedAt":"2026-07-25T18:00:00.000Z","error":{"code":"directory_highlights_unavailable","message":"Directory highlights are temporarily unavailable."}}}}}}}},"/search-placements":{"get":{"tags":["Discovery"],"summary":"Resolve authoritative BestKavaBar search placement tiers","description":"Returns one sanitized placement classification for each eligible requested public bar. Active Spotlight campaign enrollment supersedes effective plan tier. Omitted IDs are treated by clients as free/non-featured.","operationId":"getBarSearchPlacements","parameters":[{"$ref":"#/components/parameters/BarIds"}],"responses":{"200":{"description":"Eligible placement classifications in normalized request order.","headers":{"Cache-Control":{"schema":{"type":"string"},"description":"public, max-age=0, s-maxage=60, must-revalidate"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchPlacementsResponse"},"example":{"apiVersion":"2026-07-26","resource":"bar_search_placements","generatedAt":"2026-07-26T00:00:00.000Z","count":2,"placements":[{"barId":"00000000-0000-0000-0000-000000000000","tier":"spotlight","priority":0,"featured":true},{"barId":"11111111-1111-1111-1111-111111111111","tier":"free","priority":4,"featured":false}]}}}},"400":{"description":"Missing, empty, malformed, or oversized bar_ids.","headers":{"Cache-Control":{"schema":{"type":"string","const":"no-store"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchPlacementsErrorResponse"},"example":{"apiVersion":"2026-07-26","resource":"bar_search_placements","generatedAt":"2026-07-26T00:00:00.000Z","error":{"code":"invalid_bar_ids","message":"bar_ids must contain 1 to 50 unique UUIDs."}}}}},"500":{"description":"The authoritative placement source is temporarily unavailable.","headers":{"Cache-Control":{"schema":{"type":"string","const":"no-store"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchPlacementsErrorResponse"},"example":{"apiVersion":"2026-07-26","resource":"bar_search_placements","generatedAt":"2026-07-26T00:00:00.000Z","error":{"code":"search_placements_unavailable","message":"Unable to load bar search placements."}}}}}}}},"/cities":{"get":{"tags":["Discovery"],"summary":"Search public city aggregates","operationId":"listPublicCities","parameters":[{"$ref":"#/components/parameters/State"},{"$ref":"#/components/parameters/City"},{"$ref":"#/components/parameters/Query"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Offset"}],"responses":{"200":{"description":"Paginated city/state aggregate rows.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CitiesResponse"}}}},"400":{"description":"Invalid or missing query parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"The requested public dataset resource is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}}}}},"/cities.csv":{"get":{"tags":["Dataset"],"summary":"Export public city aggregates as CSV","operationId":"exportPublicCitiesCsv","parameters":[{"$ref":"#/components/parameters/State"},{"$ref":"#/components/parameters/City"},{"$ref":"#/components/parameters/Query"}],"responses":{"200":{"description":"City/state aggregate CSV export.","content":{"text/csv":{"schema":{"type":"string","description":"City/state aggregate CSV export."}}}},"400":{"description":"Invalid or missing query parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"The requested public dataset resource is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}}}}},"/events":{"get":{"tags":["Discovery"],"summary":"Search current or recent public events","operationId":"listPublicEvents","parameters":[{"$ref":"#/components/parameters/State"},{"$ref":"#/components/parameters/City"},{"$ref":"#/components/parameters/Query"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Offset"}],"responses":{"200":{"description":"Paginated current or recent public event rows.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventsResponse"}}}},"400":{"description":"Invalid or missing query parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"The requested public dataset resource is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}}}}},"/deals":{"get":{"tags":["Discovery"],"summary":"Search current or scheduled public deals","operationId":"listPublicDeals","parameters":[{"$ref":"#/components/parameters/State"},{"$ref":"#/components/parameters/City"},{"$ref":"#/components/parameters/Query"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Offset"}],"responses":{"200":{"description":"Paginated public deal rows.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DealsResponse"}}}},"400":{"description":"Invalid or missing query parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"The requested public dataset resource is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}}}}},"/prices":{"get":{"tags":["Catalog"],"summary":"Search structured public menu price samples","operationId":"listPublicPrices","parameters":[{"$ref":"#/components/parameters/State"},{"$ref":"#/components/parameters/City"},{"$ref":"#/components/parameters/Query"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Offset"},{"$ref":"#/components/parameters/MaxBars"}],"responses":{"200":{"description":"Paginated structured public menu price samples.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PricesResponse"}}}},"400":{"description":"Invalid or missing query parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"The requested public dataset resource is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}}}}},"/prices.csv":{"get":{"tags":["Dataset"],"summary":"Export aggregate menu price summaries as CSV","operationId":"exportPublicPricesCsv","parameters":[{"$ref":"#/components/parameters/State"},{"$ref":"#/components/parameters/City"}],"responses":{"200":{"description":"Aggregate structured menu price CSV export.","content":{"text/csv":{"schema":{"type":"string","description":"Aggregate structured menu price CSV export."}}}},"400":{"description":"Invalid or missing query parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"The requested public dataset resource is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}}}}},"/brands":{"get":{"tags":["Catalog"],"summary":"Search query-based brand and product menu matches","operationId":"listPublicBrandMatches","parameters":[{"$ref":"#/components/parameters/BrandQuery"},{"$ref":"#/components/parameters/State"},{"$ref":"#/components/parameters/City"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Offset"},{"$ref":"#/components/parameters/MaxBars"}],"responses":{"200":{"description":"Query-based structured-menu brand matches.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandsResponse"}}}},"400":{"description":"Invalid or missing query parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"The requested public dataset resource is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}}}}},"/strains":{"get":{"tags":["Catalog"],"summary":"Search public noble kava strain catalog rows","operationId":"listPublicStrains","parameters":[{"$ref":"#/components/parameters/Profile"},{"$ref":"#/components/parameters/Category"},{"$ref":"#/components/parameters/Query"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/Offset"}],"responses":{"200":{"description":"Paginated public noble kava strain catalog rows.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StrainsResponse"}}}},"400":{"description":"Invalid or missing query parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"The requested public dataset resource is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}}}}}},"components":{"parameters":{"BarId":{"name":"barId","in":"path","required":true,"schema":{"type":"string"},"description":"HappyKava bar UUID or public slug."},"BarIdQuery":{"name":"bar_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Limit reviews to one HappyKava bar UUID."},"State":{"name":"state","in":"query","required":false,"schema":{"type":"string"},"description":"US postal code or HappyKava state slug, for example FL or florida."},"City":{"name":"city","in":"query","required":false,"schema":{"type":"string"},"description":"City name or slug."},"Query":{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"Search text."},"BrandQuery":{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2},"description":"Brand or product search text. This is query-based, not a canonical catalog."},"Limit":{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":500,"default":100},"description":"Rows to return."},"Offset":{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0},"description":"Zero-based pagination offset."},"MaxBars":{"name":"max_bars","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":40},"description":"Maximum public bars to scan for structured menu data."},"SpotlightLimit":{"name":"spotlight_limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":2,"default":2},"description":"Maximum Spotlight campaign placements to return."},"FeaturedLimit":{"name":"featured_limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":24,"default":12},"description":"Maximum effective Pro/Premium Featured placements to return."},"BarIds":{"name":"bar_ids","in":"query","required":true,"schema":{"type":"string","minLength":36,"description":"Comma-separated list of 1 to 50 unique canonical HappyKava bar UUIDs.","example":"00000000-0000-0000-0000-000000000000,11111111-1111-1111-1111-111111111111"}},"Profile":{"name":"profile","in":"query","required":false,"schema":{"type":"string","enum":["heady","balanced","heavy"]},"description":"Plain-language strain profile."},"Category":{"name":"category","in":"query","required":false,"schema":{"type":"string","enum":["heady","balanced","heavy"]},"description":"Alias for profile on /strains."}},"schemas":{"ApiMeta":{"type":"object","required":["apiVersion","resource","generatedAt","source","publisher","usageInfo"],"properties":{"apiVersion":{"type":"string","example":"2026-09-01"},"resource":{"type":"string"},"generatedAt":{"type":"string","format":"date-time"},"source":{"type":"string","example":"HappyKava public API"},"publisher":{"type":"object","required":["name","url"],"properties":{"name":{"type":"string","const":"HappyKava"},"url":{"type":"string","format":"uri","const":"https://happykava.app"}}},"usageInfo":{"type":"string","format":"uri","const":"https://happykava.app/kava-data/open-dataset#attribution"}}},"PublicContentProvenance":{"type":"object","additionalProperties":false,"required":["version","source","publisher","resourceType","sourceUrl","sourceId","contentId","usageInfo","preferredCitation"],"properties":{"version":{"type":"string","const":"1"},"source":{"type":"string","const":"HappyKava"},"publisher":{"type":"object","required":["name","url"],"properties":{"name":{"type":"string","const":"HappyKava"},"url":{"type":"string","format":"uri","const":"https://happykava.app"}}},"resourceType":{"type":"string","enum":["profile","menu","event","event_collection"]},"sourceUrl":{"type":"string","format":"uri"},"sourceId":{"type":"string","pattern":"^HKP1-S-(P|M|E|EC)-[A-F0-9]{16}$"},"contentId":{"type":"string","pattern":"^HKP1-C-(P|M|E|EC)-[A-F0-9]{20}$"},"usageInfo":{"type":"string","format":"uri"},"preferredCitation":{"type":"string"}}},"ApiError":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"ApiErrorResponse":{"allOf":[{"$ref":"#/components/schemas/ApiMeta"},{"type":"object","required":["error"],"properties":{"error":{"$ref":"#/components/schemas/ApiError"}}}]},"ApiIndex":{"allOf":[{"$ref":"#/components/schemas/ApiMeta"},{"type":"object","required":["baseUrl","docs","llmsTxt","openapi","resources"],"properties":{"baseUrl":{"type":"string","format":"uri"},"docs":{"type":"string","format":"uri"},"llmsTxt":{"type":"string","format":"uri"},"openapi":{"type":"string","format":"uri"},"mcp":{"type":"object","properties":{"command":{"type":"string"},"docs":{"type":"string","format":"uri"}}},"resources":{"type":"array","items":{"$ref":"#/components/schemas/ApiResource"}},"responsePolicy":{"type":"object","additionalProperties":{"type":"string"}},"crossSurfaceParity":{"type":"string"}}}]},"ApiResource":{"type":"object","required":["name","href","params"],"properties":{"name":{"type":"string"},"href":{"type":"string"},"params":{"type":"array","items":{"type":"string"}},"format":{"type":"string"},"description":{"type":"string"}},"additionalProperties":true},"DatasetManifest":{"allOf":[{"$ref":"#/components/schemas/ApiMeta"},{"type":"object","required":["name","description","docs","openapi","license","resources"],"properties":{"name":{"type":"string"},"description":{"type":"string"},"docs":{"type":"string","format":"uri"},"openapi":{"type":"string","format":"uri"},"license":{"type":"object","additionalProperties":true},"refreshPolicy":{"type":"object","additionalProperties":true},"privacyBoundaries":{"type":"array","items":{"type":"string"}},"resources":{"type":"array","items":{"$ref":"#/components/schemas/ApiResource"}},"preferredCitation":{"type":"string"}}}]},"DirectoryHighlightsErrorResponse":{"type":"object","additionalProperties":false,"required":["apiVersion","resource","generatedAt","error"],"properties":{"apiVersion":{"type":"string","const":"2026-07-25"},"resource":{"type":"string","const":"directory_highlights"},"generatedAt":{"type":"string","format":"date-time"},"error":{"$ref":"#/components/schemas/ApiError"}}},"DirectoryHighlightsSpotlightPlacement":{"type":"object","additionalProperties":false,"required":["kind","label","disclosure","paid","planTier"],"properties":{"kind":{"type":"string","const":"spotlight"},"label":{"type":"string","const":"Spotlighted Kava Bar"},"disclosure":{"type":"string","const":"Sponsored"},"paid":{"type":"boolean","const":true},"planTier":{"type":["string","null"],"enum":["pro","premium",null],"description":"Effective authoritative plan tier. May be null only for a campaign-enrolled Spotlight bar."}}},"DirectoryHighlightsFeaturedPlacement":{"type":"object","additionalProperties":false,"required":["kind","label","disclosure","paid","planTier"],"properties":{"kind":{"type":"string","const":"featured"},"label":{"type":"string","const":"Featured Kava Bar"},"disclosure":{"type":"string","const":"Sponsored"},"paid":{"type":"boolean","const":true},"planTier":{"type":"string","enum":["pro","premium"],"description":"Effective authoritative Pro or Premium plan tier."}}},"DirectoryHighlightsBar":{"type":"object","additionalProperties":false,"required":["id","slug","name","description","city","state","timezone","imageUrl","rating","hours","links"],"properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"city":{"type":["string","null"]},"state":{"type":["string","null"]},"timezone":{"type":["string","null"]},"imageUrl":{"type":["string","null"],"format":"uri"},"rating":{"type":"object","additionalProperties":false,"required":["value","count"],"properties":{"value":{"type":["number","null"]},"count":{"type":["integer","null"],"minimum":0}}},"hours":{"type":"object","additionalProperties":false,"required":["today","isOpenNow","closesAt"],"properties":{"today":{"type":["string","null"]},"isOpenNow":{"type":["boolean","null"]},"closesAt":{"type":["string","null"],"format":"date-time"}}},"links":{"type":"object","additionalProperties":false,"required":["profile","share","app","favorite","notifications"],"properties":{"profile":{"type":"string"},"share":{"type":"string","format":"uri"},"app":{"type":"string"},"favorite":{"type":"string"},"notifications":{"type":"string"}}}}},"DirectoryHighlightsActivity":{"type":"object","additionalProperties":false,"required":["type","occurredAt"],"properties":{"type":{"type":["string","null"],"enum":["vibe","event","deal","profile","review",null]},"occurredAt":{"type":["string","null"],"format":"date-time"}}},"DirectoryHighlightsTickerItem":{"type":"object","additionalProperties":false,"required":["id","title","status","startsAt","endsAt","isAllDay","href"],"properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"status":{"type":"string","enum":["active","upcoming"]},"startsAt":{"type":"string","format":"date-time"},"endsAt":{"type":"string","format":"date-time"},"isAllDay":{"type":"boolean"},"href":{"type":"string"}}},"DirectoryHighlightsBaseItem":{"type":"object","additionalProperties":false,"required":["placement","bar","activity"],"properties":{"placement":{"$ref":"#/components/schemas/DirectoryHighlightsFeaturedPlacement"},"bar":{"$ref":"#/components/schemas/DirectoryHighlightsBar"},"activity":{"$ref":"#/components/schemas/DirectoryHighlightsActivity"}}},"DirectoryHighlightsSpotlightItem":{"type":"object","additionalProperties":false,"required":["placement","bar","activity","ticker"],"properties":{"placement":{"$ref":"#/components/schemas/DirectoryHighlightsSpotlightPlacement"},"bar":{"$ref":"#/components/schemas/DirectoryHighlightsBar"},"activity":{"$ref":"#/components/schemas/DirectoryHighlightsActivity"},"ticker":{"type":"object","additionalProperties":false,"required":["vibe","deals","events","closing"],"properties":{"vibe":{"oneOf":[{"type":"object","additionalProperties":false,"required":["labels","updatedAt","expiresAt"],"properties":{"labels":{"type":"array","maxItems":5,"uniqueItems":true,"items":{"type":"string"}},"updatedAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"}}},{"type":"null"}]},"deals":{"type":"array","maxItems":3,"items":{"$ref":"#/components/schemas/DirectoryHighlightsTickerItem"}},"events":{"type":"array","maxItems":3,"items":{"$ref":"#/components/schemas/DirectoryHighlightsTickerItem"}},"closing":{"oneOf":[{"type":"object","additionalProperties":false,"required":["closesAt"],"properties":{"closesAt":{"type":"string","format":"date-time"}}},{"type":"null"}]}}}}},"DirectoryHighlightsResponse":{"type":"object","additionalProperties":false,"required":["apiVersion","resource","generatedAt","filters","limits","counts","spotlightedBars","featuredBars"],"properties":{"apiVersion":{"type":"string","const":"2026-07-25"},"resource":{"type":"string","const":"directory_highlights"},"generatedAt":{"type":"string","format":"date-time"},"filters":{"type":"object","additionalProperties":false,"required":["state"],"properties":{"state":{"type":["string","null"]}}},"limits":{"type":"object","additionalProperties":false,"required":["spotlight","featured"],"properties":{"spotlight":{"type":"integer","minimum":1,"maximum":2},"featured":{"type":"integer","minimum":1,"maximum":24}}},"counts":{"type":"object","additionalProperties":false,"required":["spotlightedBars","featuredBars"],"properties":{"spotlightedBars":{"type":"integer","minimum":0,"maximum":2},"featuredBars":{"type":"integer","minimum":0,"maximum":24}}},"spotlightedBars":{"type":"array","maxItems":2,"items":{"$ref":"#/components/schemas/DirectoryHighlightsSpotlightItem"}},"featuredBars":{"type":"array","maxItems":24,"items":{"$ref":"#/components/schemas/DirectoryHighlightsBaseItem"}}}},"SearchPlacement":{"oneOf":[{"type":"object","additionalProperties":false,"required":["barId","tier","priority","featured"],"properties":{"barId":{"type":"string","format":"uuid"},"tier":{"type":"string","const":"spotlight"},"priority":{"type":"integer","const":0},"featured":{"type":"boolean","const":true}}},{"type":"object","additionalProperties":false,"required":["barId","tier","priority","featured"],"properties":{"barId":{"type":"string","format":"uuid"},"tier":{"type":"string","const":"premium"},"priority":{"type":"integer","const":1},"featured":{"type":"boolean","const":true}}},{"type":"object","additionalProperties":false,"required":["barId","tier","priority","featured"],"properties":{"barId":{"type":"string","format":"uuid"},"tier":{"type":"string","const":"pro"},"priority":{"type":"integer","const":2},"featured":{"type":"boolean","const":true}}},{"type":"object","additionalProperties":false,"required":["barId","tier","priority","featured"],"properties":{"barId":{"type":"string","format":"uuid"},"tier":{"type":"string","const":"standard"},"priority":{"type":"integer","const":3},"featured":{"type":"boolean","const":true}}},{"type":"object","additionalProperties":false,"required":["barId","tier","priority","featured"],"properties":{"barId":{"type":"string","format":"uuid"},"tier":{"type":"string","const":"free"},"priority":{"type":"integer","const":4},"featured":{"type":"boolean","const":false}}}]},"SearchPlacementsResponse":{"type":"object","additionalProperties":false,"required":["apiVersion","resource","generatedAt","count","placements"],"properties":{"apiVersion":{"type":"string","const":"2026-07-26"},"resource":{"type":"string","const":"bar_search_placements"},"generatedAt":{"type":"string","format":"date-time"},"count":{"type":"integer","minimum":0,"maximum":50},"placements":{"type":"array","maxItems":50,"uniqueItems":true,"items":{"$ref":"#/components/schemas/SearchPlacement"}}}},"SearchPlacementsErrorResponse":{"type":"object","additionalProperties":false,"required":["apiVersion","resource","generatedAt","error"],"properties":{"apiVersion":{"type":"string","const":"2026-07-26"},"resource":{"type":"string","const":"bar_search_placements"},"generatedAt":{"type":"string","format":"date-time"},"error":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_bar_ids","search_placements_unavailable"]},"message":{"type":"string"}}}}},"PublicBar":{"type":"object","required":["id","slug","name","address","rating","links"],"properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"city":{"type":["string","null"]},"state":{"type":["string","null"]},"address":{"type":"object","properties":{"full":{"type":["string","null"]},"line1":{"type":["string","null"]},"line2":{"type":["string","null"]},"postalCode":{"type":["string","null"]}}},"imageUrl":{"type":["string","null"],"format":"uri"},"rating":{"$ref":"#/components/schemas/Rating"},"links":{"type":"object","properties":{"profile":{"type":"string"},"website":{"type":["string","null"]},"map":{"type":["string","null"]},"reviews":{"type":["string","null"]}}},"updatedAt":{"type":["string","null"],"format":"date-time"}}},"PublicReview":{"type":"object","required":["id","bar","rating","author","imported","verifiedVisit"],"properties":{"id":{"type":"string","format":"uuid"},"bar":{"type":"object","additionalProperties":true},"rating":{"type":"integer","minimum":1,"maximum":5},"text":{"type":["string","null"]},"author":{"type":"string"},"reviewedAt":{"type":["string","null"],"format":"date-time"},"source":{"type":["string","null"]},"imported":{"type":"boolean"},"verifiedVisit":{"type":"boolean","description":"True only for a native review linked to a HappyKava check-in."}}},"PublicBarDetail":{"allOf":[{"$ref":"#/components/schemas/PublicBar"},{"type":"object","required":["contact","location","hours","media","menu","recentReviews","dataFreshness"],"properties":{"contact":{"type":"object","additionalProperties":true},"location":{"type":"object","additionalProperties":true},"hours":{"type":"object","additionalProperties":true},"media":{"type":"array","items":{"type":"object","additionalProperties":true}},"menu":{"type":"object","additionalProperties":true,"properties":{"availability":{"$ref":"#/components/schemas/MenuAvailability"}}},"recentReviews":{"type":"array","items":{"$ref":"#/components/schemas/PublicReview"}},"dataFreshness":{"type":"object","additionalProperties":true,"properties":{"menuRefreshAfterMs":{"$ref":"#/components/schemas/MenuRefreshBudget"}}},"provenance":{"type":"object","required":["profile","menu"],"properties":{"profile":{"oneOf":[{"$ref":"#/components/schemas/PublicContentProvenance"},{"type":"null"}]},"menu":{"oneOf":[{"$ref":"#/components/schemas/PublicContentProvenance"},{"type":"null"}]}},"description":"Present when public content provenance V1 is enabled. Null section values mean signed provenance was unavailable or that section had no public content."}}}]},"BarDetailResponse":{"allOf":[{"$ref":"#/components/schemas/ApiMeta"},{"type":"object","required":["bar"],"properties":{"bar":{"$ref":"#/components/schemas/PublicBarDetail"}}}]},"ReviewsResponse":{"allOf":[{"$ref":"#/components/schemas/ApiMeta"},{"type":"object","required":["filters","count","total","limit","offset","reviews"],"properties":{"filters":{"type":"object","additionalProperties":true},"count":{"type":"integer","minimum":0,"description":"Number of rows returned in this response."},"total":{"type":"integer","minimum":0,"description":"Total rows matching the filters before pagination."},"limit":{"type":"integer","minimum":1,"maximum":500},"offset":{"type":"integer","minimum":0},"reviews":{"type":"array","items":{"$ref":"#/components/schemas/PublicReview"}}}}]},"Rating":{"type":"object","properties":{"value":{"type":["number","null"]},"count":{"type":["integer","null"]}}},"CityAggregate":{"type":"object","required":["key","city","citySlug","state","links","barCount","sampleBars"],"properties":{"key":{"type":"string"},"city":{"type":"string"},"citySlug":{"type":"string"},"state":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"}}},"links":{"type":"object","properties":{"directory":{"type":"string"},"state":{"type":"string"}}},"barCount":{"type":"integer","minimum":0},"liveItemCount":{"type":"integer","minimum":0},"sampleBars":{"type":"array","items":{"$ref":"#/components/schemas/PublicBar"}}}},"PublicEvent":{"type":"object","required":["id","title","bar","links"],"properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"description":{"type":["string","null"]},"startsAt":{"type":["string","null"],"format":"date-time"},"endsAt":{"type":["string","null"],"format":"date-time"},"isAllDay":{"type":"boolean"},"recurrenceType":{"type":["string","null"]},"daysOfWeek":{"type":"array","items":{"type":"integer"}},"categories":{"type":"array","items":{"type":"string"}},"imageUrl":{"type":["string","null"]},"rsvp":{"type":"object","additionalProperties":true},"rating":{"$ref":"#/components/schemas/Rating"},"bar":{"$ref":"#/components/schemas/PublicBarSummary"},"links":{"type":"object","additionalProperties":true},"relevance":{"type":["number","null"]},"provenance":{"oneOf":[{"$ref":"#/components/schemas/PublicContentProvenance"},{"type":"null"}],"description":"Present when public content provenance V1 is enabled."}}},"PublicDeal":{"type":"object","required":["id","title","schedule","programs","bar","links"],"properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"description":{"type":["string","null"]},"schedule":{"type":"object","additionalProperties":true},"categories":{"type":"array","items":{"type":"string"}},"imageUrl":{"type":["string","null"]},"programs":{"type":"object","additionalProperties":true},"bar":{"$ref":"#/components/schemas/PublicBarSummary"},"links":{"type":"object","additionalProperties":true},"relevance":{"type":["number","null"]}}},"PublicBarSummary":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":["string","null"]},"city":{"type":["string","null"]},"state":{"type":["string","null"]},"timezone":{"type":["string","null"]},"profileUrl":{"type":["string","null"]}}},"MenuRefreshBudget":{"type":"number","minimum":0,"maximum":900000,"description":"Remaining menu validity in milliseconds at response construction. Subtract the full request duration; refresh before using the result after this budget. Menu endpoints use no-store, not stale CDN caching."},"MenuAvailability":{"type":"object","required":["version","asOf","nextChangeAt"],"properties":{"version":{"type":"integer","const":1},"asOf":{"type":"string","format":"date-time"},"nextChangeAt":{"type":["string","null"],"format":"date-time"}},"description":"Database projection time and next scheduled change. A null nextChangeAt is not permission to cache indefinitely."},"MenuSeasonalPeriod":{"type":"object","required":["periodId","availabilityMode","startsAt","endsAt","scheduleTimezone"],"properties":{"periodId":{"type":"string","format":"uuid"},"availabilityMode":{"type":"string","enum":["regular","seasonal_only"]},"startsAt":{"type":"string","format":"date-time"},"endsAt":{"type":["string","null"],"format":"date-time"},"scheduleTimezone":{"type":"string"}},"description":"Current seasonal presentation. Seasonal-only items are hidden outside their period; regular items retain regular availability. End moments are exclusive."},"PublicPrice":{"type":"object","required":["bar","category","item","price","soldOut"],"properties":{"bar":{"$ref":"#/components/schemas/PublicBar"},"category":{"type":"string"},"item":{"type":"string"},"description":{"type":["string","null"]},"size":{"type":["string","null"]},"price":{"type":"object","required":["cents","text"],"properties":{"cents":{"type":"integer","minimum":0},"text":{"type":"string"}}},"soldOut":{"type":"boolean"},"availability":{"$ref":"#/components/schemas/MenuAvailability"},"seasonal":{"oneOf":[{"$ref":"#/components/schemas/MenuSeasonalPeriod"},{"type":"null"}]}}},"PriceSummary":{"type":"object","properties":{"count":{"type":"integer","minimum":0},"minCents":{"type":["integer","null"]},"medianCents":{"type":["integer","null"]},"maxCents":{"type":["integer","null"]},"minText":{"type":["string","null"]},"medianText":{"type":["string","null"]},"maxText":{"type":["string","null"]}}},"PublicBrandMatch":{"type":"object","required":["bar","category","item","soldOut"],"properties":{"bar":{"$ref":"#/components/schemas/PublicBar"},"category":{"type":"string"},"item":{"type":"string"},"description":{"type":["string","null"]},"priceText":{"type":["string","null"]},"soldOut":{"type":"boolean"},"availability":{"$ref":"#/components/schemas/MenuAvailability"},"seasonal":{"oneOf":[{"$ref":"#/components/schemas/MenuSeasonalPeriod"},{"type":"null"}]}}},"PublicBrandSampleItem":{"type":"object","required":["category","item","soldOut"],"properties":{"category":{"type":"string"},"item":{"type":"string"},"description":{"type":["string","null"]},"priceText":{"type":["string","null"]},"soldOut":{"type":"boolean"},"availability":{"$ref":"#/components/schemas/MenuAvailability"},"seasonal":{"oneOf":[{"$ref":"#/components/schemas/MenuSeasonalPeriod"},{"type":"null"}]}}},"PublicStrain":{"type":"object","required":["id","slug","cultivarName","category","status","links"],"properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"cultivarName":{"type":"string"},"region":{"type":["string","null"]},"category":{"type":"object","additionalProperties":true},"status":{"type":"object","additionalProperties":true},"chemotypeCode":{"type":["string","null"]},"tkDisplay":{"type":["string","null"]},"details":{"type":["string","null"]},"tags":{"type":"object","additionalProperties":true},"rating":{"type":"object","additionalProperties":true},"potency":{"type":"object","additionalProperties":true},"links":{"type":"object","properties":{"canonical":{"type":"string"}}}}},"BarsResponse":{"allOf":[{"$ref":"#/components/schemas/ApiMeta"},{"type":"object","required":["filters","count","total","limit","offset","bars"],"properties":{"filters":{"type":"object","properties":{"state":{"type":["string","null"],"description":"Two-letter US state code after normalization."},"city":{"type":["string","null"]},"q":{"type":["string","null"]}}},"count":{"type":"integer","minimum":0,"description":"Number of rows returned in this response."},"total":{"type":"integer","minimum":0,"description":"Total rows matching the filters before pagination."},"limit":{"type":"integer","minimum":1,"maximum":500},"offset":{"type":"integer","minimum":0},"bars":{"type":"array","items":{"$ref":"#/components/schemas/PublicBar"}}}}]},"OpenNowResponse":{"allOf":[{"$ref":"#/components/schemas/ApiMeta"},{"type":"object","required":["evaluatedAt","filters","count","total","limit","offset","barsWithHours","openNowBars","responsePolicy"],"properties":{"evaluatedAt":{"type":"string","format":"date-time"},"filters":{"type":"object","properties":{"state":{"type":["string","null"],"description":"Two-letter US state code after normalization."},"city":{"type":["string","null"]},"q":{"type":["string","null"]}}},"count":{"type":"integer","minimum":0,"description":"Number of rows returned in this response."},"total":{"type":"integer","minimum":0,"description":"Total rows matching the filters before pagination."},"limit":{"type":"integer","minimum":1,"maximum":500},"offset":{"type":"integer","minimum":0},"barsWithHours":{"type":"integer","minimum":0,"description":"Filtered bars with posted hours available for evaluation."},"openNowBars":{"type":"array","items":{"$ref":"#/components/schemas/PublicBar"}},"responsePolicy":{"type":"object","properties":{"source":{"type":"string"},"missingHours":{"type":"string"}}}}}]},"CitiesResponse":{"allOf":[{"$ref":"#/components/schemas/ApiMeta"},{"type":"object","required":["filters","count","total","limit","offset","cities"],"properties":{"filters":{"type":"object","properties":{"state":{"type":["string","null"],"description":"Two-letter US state code after normalization."},"city":{"type":["string","null"]},"q":{"type":["string","null"]}}},"count":{"type":"integer","minimum":0,"description":"Number of rows returned in this response."},"total":{"type":"integer","minimum":0,"description":"Total rows matching the filters before pagination."},"limit":{"type":"integer","minimum":1,"maximum":500},"offset":{"type":"integer","minimum":0},"cities":{"type":"array","items":{"$ref":"#/components/schemas/CityAggregate"}}}}]},"EventsResponse":{"allOf":[{"$ref":"#/components/schemas/ApiMeta"},{"type":"object","required":["filters","count","total","limit","offset","events"],"properties":{"filters":{"type":"object","properties":{"state":{"type":["string","null"],"description":"Two-letter US state code after normalization."},"city":{"type":["string","null"]},"q":{"type":["string","null"]}}},"count":{"type":"integer","minimum":0,"description":"Number of rows returned in this response."},"total":{"type":"integer","minimum":0,"description":"Total rows matching the filters before pagination."},"limit":{"type":"integer","minimum":1,"maximum":500},"offset":{"type":"integer","minimum":0},"events":{"type":"array","items":{"$ref":"#/components/schemas/PublicEvent"}}}}]},"DealsResponse":{"allOf":[{"$ref":"#/components/schemas/ApiMeta"},{"type":"object","required":["filters","count","total","limit","offset","deals"],"properties":{"filters":{"type":"object","properties":{"state":{"type":["string","null"],"description":"Two-letter US state code after normalization."},"city":{"type":["string","null"]},"q":{"type":["string","null"]}}},"count":{"type":"integer","minimum":0,"description":"Number of rows returned in this response."},"total":{"type":"integer","minimum":0,"description":"Total rows matching the filters before pagination."},"limit":{"type":"integer","minimum":1,"maximum":500},"offset":{"type":"integer","minimum":0},"deals":{"type":"array","items":{"$ref":"#/components/schemas/PublicDeal"}}}}]},"PricesResponse":{"allOf":[{"$ref":"#/components/schemas/ApiMeta"},{"type":"object","required":["filters","count","total","limit","offset","scannedBars","structuredMenuBars","summary","prices"],"properties":{"filters":{"type":"object","properties":{"state":{"type":["string","null"],"description":"Two-letter US state code after normalization."},"city":{"type":["string","null"]},"q":{"type":["string","null"]},"maxBars":{"type":"integer","minimum":1,"maximum":100}}},"count":{"type":"integer","minimum":0,"description":"Number of rows returned in this response."},"total":{"type":"integer","minimum":0,"description":"Total rows matching the filters before pagination."},"limit":{"type":"integer","minimum":1,"maximum":500},"offset":{"type":"integer","minimum":0},"scannedBars":{"type":"integer","minimum":0},"menuRefreshAfterMs":{"$ref":"#/components/schemas/MenuRefreshBudget"},"structuredMenuBars":{"type":"integer","minimum":0},"summary":{"$ref":"#/components/schemas/PriceSummary"},"prices":{"type":"array","items":{"$ref":"#/components/schemas/PublicPrice"}}}}]},"BrandsResponse":{"allOf":[{"$ref":"#/components/schemas/ApiMeta"},{"type":"object","required":["filters","brand","count","totalItems","barCount","limit","offset","scannedBars","bars","items"],"properties":{"filters":{"type":"object","properties":{"state":{"type":["string","null"],"description":"Two-letter US state code after normalization."},"city":{"type":["string","null"]},"q":{"type":["string","null"]},"maxBars":{"type":"integer","minimum":1,"maximum":100}}},"brand":{"type":"object","required":["query","canonical","source"],"properties":{"query":{"type":"string"},"canonical":{"type":"boolean"},"source":{"type":"string"}}},"count":{"type":"integer","minimum":0,"description":"Number of rows returned in this response."},"totalItems":{"type":"integer","minimum":0},"barCount":{"type":"integer","minimum":0},"limit":{"type":"integer","minimum":1,"maximum":500},"offset":{"type":"integer","minimum":0},"scannedBars":{"type":"integer","minimum":0},"menuRefreshAfterMs":{"$ref":"#/components/schemas/MenuRefreshBudget"},"bars":{"type":"array","items":{"type":"object","required":["bar","matchCount","sampleItems"],"properties":{"bar":{"$ref":"#/components/schemas/PublicBar"},"matchCount":{"type":"integer","minimum":0},"sampleItems":{"type":"array","items":{"$ref":"#/components/schemas/PublicBrandSampleItem"}}}}},"items":{"type":"array","items":{"$ref":"#/components/schemas/PublicBrandMatch"}}}}]},"StrainsResponse":{"allOf":[{"$ref":"#/components/schemas/ApiMeta"},{"type":"object","required":["filters","count","total","limit","offset","source","sourceRpc","advisory","strains"],"properties":{"filters":{"type":"object","properties":{"profile":{"type":["string","null"],"enum":["heady","balanced","heavy",null]},"q":{"type":["string","null"]}}},"count":{"type":"integer","minimum":0,"description":"Number of rows returned in this response."},"total":{"type":"integer","minimum":0,"description":"Total rows matching the filters before pagination."},"limit":{"type":"integer","minimum":1,"maximum":500},"offset":{"type":"integer","minimum":0},"source":{"type":"string","enum":["happykava"],"description":"Stable public provenance label."},"sourceRpc":{"type":"string","deprecated":true,"description":"Deprecated compatibility field. Use source instead; this field will be removed in the next API version."},"advisory":{"type":"string"},"strains":{"type":"array","items":{"$ref":"#/components/schemas/PublicStrain"}}}}]}}},"x-happykava-boundaries":["Public API v1 is read-only and uses access-controlled public data sources.","Responses do not include private owner settings, user profiles, check-ins, staff records, employment requests, payment data, or unpublished owner data.","Brand responses are query-based structured-menu matches, not a canonical brand catalog.","Strain responses are catalog and discovery data, not medical guidance, diagnosis, treatment, or dosing advice.","Empty filtered reads return 200 with empty collections; unavailable data returns JSON errors and never fabricates counts or availability."]}