> ## Documentation Index
> Fetch the complete documentation index at: https://docs.colacloud.us/llms.txt
> Use this file to discover all available pages before exploring further.

# Search operators

> Require a phrase, exclude words, or combine alternatives in COLA Cloud searches.

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.

| Query | Meaning |
| - | - |
| `"cabernet sauvignon"` | Require these words next to one another, in this order. |
| `whiskey -cinnamon` | Require whiskey and exclude cinnamon. |
| `whiskey -"red wine"` | Require whiskey and exclude the phrase red wine. |
| `bourbon OR rye` | Match bourbon, rye, or both. |
| `(bourbon OR rye) -flavored` | Match either spirit and exclude flavored. |

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

```bash theme={null}
curl --get 'https://app.colacloud.us/api/v1/colas' \
  --header "X-API-Key: $COLA_API_KEY" \
  --data-urlencode 'q=(bourbon OR rye) -"cinnamon flavored"' \
  --data-urlencode 'sort=relevance_desc' \
  --data-urlencode 'per_page=10'
```

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.