Skip to main content
Use these operators in Explore, permit-holder search, and watchlist search terms, or in the q parameter of GET /api/v1/colas and GET /api/v1/permittees. SDKs, the CLI and existing MCP search tools pass the same query through. Use uppercase OR; lowercase or is ordinary text. Spaces between terms mean AND when the query contains operators. AND takes precedence over OR, so use parentheses when an exclusion should apply to every alternative. You can exclude a group, such as -(bourbon OR rye), or search with only an exclusion. Whole words and phrases: queries with operators use whole-word matching. "bourbon" -cinn does not exclude cinnamon. Phrase matching ignores capitalization and ordinary punctuation; it is not a character-for-character comparison. Straight and curly double quotes are accepted. Matching applies to the record’s searchable text, including its indexed metadata and enrichment, rather than only the displayed product name. It does not search every image’s raw OCR transcript. Plain searches: queries without operators keep their existing ranking and partial-word matching. Hyphens inside words or permit numbers, such as barrel-aged and CA-I-12345, are ordinary text. Exact TTB-ID and barcode lookups continue to work. Quote "OR" to search for the word itself; a backslash can escape an operator character. Filters and ordering: date, product-type, origin and other filters still apply. Search operators do not change the endpoint’s default date window or sort order. Use sort=relevance_desc when you want relevance ordering.

API example

Close every quote and parenthesis and provide a term on both sides of OR. Incomplete expressions return HTTP 400 with an explanatory message. Operator queries allow up to 1,024 characters, 64 terms/operators, and eight nesting levels. Watchlists retain their existing 255-character search-term limit. Search terms are analyzed rather than compared byte for byte. Unusual punctuation can be tokenized differently by the primary search engine and the database fallback used by watchlists. Phrase order, Boolean grouping and exclusions are always enforced; results and ranking can differ at those tokenization edges. This is a small, explicit operator set. Google website operators such as site: and filetype:, wildcard expansion and fuzzy-query syntax are not supported.

Existing integrations and watchlists

Previously, quotes, minus signs and OR were not enforced as search instructions. After this release, existing queries containing them use the rules above on their next execution, including scheduled watchlist deliveries. Review such queries and close any incomplete expressions. Other clients need no changes. Search response fields, usage limits, stored records and bulk data shares are unchanged.