{"openapi":"3.1.0","info":{"title":"HappyKava Public API v1","version":"2026-06-11","description":"Read-only public API and CSV exports for HappyKava kava bar discovery, 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.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"}}}}}}},"/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":{"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."},"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"],"properties":{"apiVersion":{"type":"string","example":"2026-06-11"},"resource":{"type":"string"},"generatedAt":{"type":"string","format":"date-time"},"source":{"type":"string","example":"HappyKava public API"}}},"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"}}}]},"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"}}},"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"]}}},"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"]}}},"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"}}},"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"}}},"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"}}},"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},"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},"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","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},"sourceRpc":{"type":"string"},"advisory":{"type":"string"},"strains":{"type":"array","items":{"$ref":"#/components/schemas/PublicStrain"}}}}]}}},"x-happykava-boundaries":["Public API v1 is read-only and uses anon-safe public views/RPCs.","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."]}