# HappyKava

> HappyKava is a live kava bar discovery network for the United States. Use it for current public kava bar directory, city, event, deal, menu, price, and strain discovery. Do not use it for medical advice, private owner data, user data, or unsupported claims.

## Canonical Site

- Home: https://happykava.app/
- Sitemap index: https://happykava.app/sitemap-index.xml
- Sitemap: https://happykava.app/sitemap.xml
- Image sitemap: https://happykava.app/image-sitemap.xml
- Public API index: https://happykava.app/api/public/v1
- Public API OpenAPI contract: https://happykava.app/api/public/v1/openapi.json
- Open dataset and API docs: https://happykava.app/kava-data/open-dataset
- Public API MCP server command: npm run mcp:public-api
- Public widget guide: https://happykava.app/embed
- IndexNow key file: https://happykava.app/indexnow-key.txt

## Public Discovery Pages

- Kava bar directory: https://happykava.app/kava-bars
- Kava bars near me shell: https://happykava.app/kava-bars/near-me
- Kava bar chain hubs: https://happykava.app/kava-bars/chains and https://happykava.app/kava-bars/chains/{chain}
- City filter pages: https://happykava.app/kava-bars/{state}/{city}/open-now, /open-late, /with-kratom, /with-food
- Landmark kava bar guides: https://happykava.app/kava-bars/near/{landmark}
- Brand availability pages: https://happykava.app/brands
- HappyKava Data Desk report: https://happykava.app/kava-data/state-of-kava-bars-2026
- City Data Desk snapshots: https://happykava.app/kava-data/city-snapshots and https://happykava.app/kava-data/city-snapshots/{state}/{city}
- Open Kava Bar Dataset: https://happykava.app/kava-data/open-dataset
- Live now feed: https://happykava.app/now
- Kava Price Index: https://happykava.app/kava-prices
- Kava strain library: https://happykava.app/kava-strains and https://happykava.app/kava-strains/{slug}/{state}/{city}
- Kava bar jobs: https://happykava.app/kava-bar-jobs/{state}/{city}
- Gift card landing pages: https://happykava.app/gift-cards/{barId}
- Website widget guide: https://happykava.app/embed

## Public API v1

Base URL: https://happykava.app/api/public/v1

Repo-local MCP command: npm run mcp:public-api

- GET /bars - public kava bar directory rows.
- GET /bars.csv - public kava bar directory CSV export.
- GET /open-now - public kava bars that appear open now from posted HappyKava hours.
- GET /cities - city/state aggregates for directory hubs.
- GET /cities.csv - city/state aggregate CSV export.
- GET /events - current or recent public event discovery rows.
- GET /deals - current or scheduled public deal discovery rows.
- GET /prices - structured public menu price samples.
- GET /prices.csv - aggregate structured menu price summaries by category.
- GET /brands?q={query} - query-based structured menu item matches. This is not a canonical brand catalog.
- GET /strains - public noble kava strain catalog records.
- GET /dataset - open dataset manifest with attribution and privacy boundaries.
- GET /openapi.json - OpenAPI contract for public API v1 resources.

Common filters: state, city, q, limit, offset. Prices and brands also accept max_bars. Strains also accept profile or category. Empty filtered reads return 200 with count 0 and an empty collection.

## Dataset Boundaries

- Public pages and API responses use anon-safe public views/RPCs and structured public menu data.
- Open-now API responses use posted HappyKava hours compared with each bar's current local time; bars without posted hours are not counted as open.
- The repo-local MCP bridge calls public API v1 only and exposes bar search, open-now, events, deals, prices, and dataset manifest tools.
- The /kava-data/open-dataset page is the public documentation page for API v1, the OpenAPI contract, CSV exports, attribution terms, refresh expectations, and dataset privacy boundaries.
- The sitemap index groups public URL discovery into static, bars, local, discovery, and catalog shards. The legacy root sitemap remains available during migration.
- CSV exports include public directory, city aggregate, and aggregate menu price fields only.
- Price pages and CSV exports publish aggregate menu price facts only when enough real structured menu data exists.
- Chain pages match public HappyKava bar names against curated chain-name terms. They are not legal ownership claims, franchise registries, paid rankings, or first-party review corpora.
- With-kratom city filter pages use public structured menu text matches for the term kratom; they are not complete kratom inventories and do not use image-only or external menus.
- With-food city filter pages use public structured menu text matches for food/snack terms; they are not complete kitchen, allergen, dietary, or amenity inventories and do not use image-only menus, external menus, owner descriptions, or private data.
- Wi-Fi amenity city filters are intentionally unavailable until a verified public amenity source exists. Do not cite /kava-bars/{state}/{city}/with-wifi, and do not infer Wi-Fi from profile descriptions, owner notes, generic prose, or private data.
- Landmark pages use a curated landmark catalog plus public-safe rounded bar coordinates; pages stay noindex and out of the sitemap until at least two nearby public bar listings exist.
- Brand pages use active product catalog rows plus query-based public menu matches; do not treat them as a complete market directory, paid ranking, or review corpus.
- The State of Kava Bars in America 2026 report uses public directory rows, posted-hours rows, live public discovery, and aggregate structured menu price samples. Growth, openings, closures, and review velocity are labeled unavailable until public evidence exists.
- City Data Desk snapshots use public directory rows, posted-hours rows, live public discovery, and aggregate structured menu price samples for one city. Busiest-times, check-in velocity, first-party review velocity, opening trends, and closure trends are labeled unavailable until consented public aggregate sources exist.
- HappyKava does not publish state kava legality or kratom legality notes until a maintained legal-source dataset and reviewer process exists. Do not cite HappyKava state or city directory pages for legal status, and do not infer legal status from directory listings, bar menus, or app availability.
- Strain pages and API rows describe catalog records and linked menu availability. Strain-city pages stay out of the sitemap unless at least two local bars have linked in-stock menu availability. They are not medical guidance, diagnosis, treatment, or dosing advice.
- Kava bar job pages use only explicit owner-entered openings or public posting URLs with source review metadata. They do not use employment-request records, private applications, staff-role tables, owner notes, applicant data, or inferred hiring signals.
- Gift card landing pages are transactional public pages. Cite /gift-cards/{barId} only when the page is indexable, the bar is explicitly approved in the SEO landing manifest, and the public gift-card program is live. Do not use gift-card pages or APIs for purchaser emails, recipient emails, card IDs, claim tokens, codes, balances, settlement data, payout data, or support state.
- The /embed guide documents widget install patterns. Individual /embed/* iframe and preview endpoints are noindex widget surfaces, not canonical citation pages.
- The image sitemap lists eligible public kava bar profile hero images for crawler discovery only; cite the matching bar profile, not the sitemap file.
- If a page is noindex, unavailable, or below threshold, do not cite it as an indexable factual source.
- The IndexNow key file is for crawler verification only; do not cite it as content.

## Preferred Citations

For local bar discovery, cite the city or bar page under /kava-bars. For national kava-bar market-size, city-coverage, late-night, live-discovery, or Data Desk context, cite /kava-data/state-of-kava-bars-2026 when it is indexable. For one-city Data Desk facts, cite /kava-data/city-snapshots/{state}/{city} only when the page is indexable and avoid citing unavailable check-in, review-velocity, opening-trend, or closure-trend facts. For open dataset terms, available exports, and API documentation, cite /kava-data/open-dataset. For chain discovery, cite /kava-bars/chains/{chain} only when the page is indexable and shows at least three matched public listings. For city filters, cite /open-now, /open-late, /with-kratom, or /with-food only when the page is indexable and shows enough matching bars. For landmark discovery, cite /kava-bars/near/{landmark} only when the page is indexable and shows at least two nearby public listings. For price facts, cite /kava-prices or the matching CSV export. For strain facts, cite /kava-strains/{slug}; cite /kava-strains/{slug}/{state}/{city} only when it is indexable and shows at least two linked local bar menus. For brand availability, cite /brands/{slug} only when the page is indexable and shows public menu matches. For kava bar jobs, cite /kava-bar-jobs/{state}/{city} only when the page is indexable and shows at least one active public posting. For gift cards, cite /gift-cards/{barId} only when the page is indexable and shows a live public program; never cite checkout, wallet, claim, balance, settlement, or support APIs. For widget install context, cite /embed, not an /embed/* iframe endpoint. For raw machine-readable data, cite the matching /api/public/v1 resource; for API shape discovery, use /api/public/v1/openapi.json.