Skip to main content
GET
Search COLAs

Authorizations

X-API-Key
string
header
required

API key passed in the X-API-Key header

Query Parameters

q
string

Text search query. Searches TTB ID, brand, product, class, permit number, and applicant/company name and applicant trade name. Exact 14-digit TTB IDs take precedence; other barcode-shaped queries are treated as barcode lookups first.

product_type
enum<string>[]

Filter by one or more TTB product types. Comma-separated values are accepted.

Available options:
wine,
malt beverage,
distilled spirits
category
enum<string>[]

Filter by one or more consumer-facing taxonomy roots. Comma-separated values are accepted. This trade-oriented classification is independent of the TTB product_type field.

Available options:
Beer,
Wine,
Liquor
derived_subcategory
string

Filter by a canonical taxonomy path prefix, such as "Beer > Ale" or "Wine > Red Wine". Paths with a published transition alias are accepted and resolved to their current canonical path.

origin
string

Filter by origin/country (e.g., "american", "french", "italian")

domestic_or_imported
enum<string>

Filter by domestic or imported origin.

Available options:
domestic,
imported
status
enum<string>

Filter by current TTB application status. Non-approved statuses search all available history when no explicit approval-date filter is supplied.

Available options:
approved,
expired,
surrendered,
revoked
brand_name
string

Filter by brand name (partial match, case-insensitive)

permit_number
string

Filter by permit number (exact match, e.g. "CA-I-12345")

barcode_value
string

Filter by the COLA record's main barcode value (exact match). Numeric values may include spaces or hyphens.

approval_date_from
string<date>

Filter by minimum approval date (YYYY-MM-DD)

approval_date_to
string<date>

Filter by maximum approval date (YYYY-MM-DD)

abv_min
number<float>

Filter by minimum alcohol by volume (ABV) percentage

abv_max
number<float>

Filter by maximum alcohol by volume (ABV) percentage

volume_unit
enum<string>

Filter by package volume unit. Required when volume_min or volume_max is provided.

Available options:
beer barrels,
fluid ounces,
gallons,
liters,
milliliters,
pints,
quarts
volume_min
number<float>

Filter by minimum package volume in the selected volume_unit.

Required range: x >= 0
volume_max
number<float>

Filter by maximum package volume in the selected volume_unit.

Required range: x >= 0
container_type
enum<string>[]

Filter by one or more derived container types. Comma-separated values are accepted.

Available options:
bag,
bottle,
box,
can,
carton,
cask,
jug,
keg,
pod,
pouch
product_style
string[]

Filter by asserted finished-beverage style in upstream product facts (for example spirit_cocktail or ipa). Comma-separated values are accepted. Only records evaluated for this field can match; historical coverage is expanding.

Maximum array length: 25
Pattern: ^[a-z][a-z0-9_]{0,63}$
product_base
string[]

Filter by asserted fermentable base in upstream product facts (for example agave or grape). Comma-separated values are accepted. This is independent of the finished-beverage style; records without an asserted base do not match.

Maximum array length: 25
Pattern: ^[a-z][a-z0-9_]{0,63}$
sort
enum<string>
default:approval_date_desc

Sort order. Omit for newest approvals first. Ascending approval-date and brand-name sorts require page pagination without cursor. Unsupported values return 400 invalid_request with error.details.valid_values.

Available options:
approval_date_desc,
approval_date_asc,
brand_name_asc,
brand_name_desc,
relevance_desc
page
integer
default:1

Page number (max 100)

Required range: 1 <= x <= 100
per_page
integer
default:20

Results per page (max 100)

Required range: 1 <= x <= 100

Response

Successful response

data
object[]
pagination
object