Skip to main content
GET
/
colas
Search COLAs
curl --request GET \
  --url https://app.colacloud.us/api/v1/colas \
  --header 'X-API-Key: <api-key>'
{
  "data": [
    {
      "ttb_id": "24001234567",
      "brand_name": "Sample Winery",
      "product_name": "Reserve Cabernet Sauvignon",
      "product_type": "wine",
      "class_name": "table red wine",
      "origin_name": "american",
      "permit_number": "CA-I-12345",
      "approval_date": "2024-01-20",
      "image_count": 2,
      "has_barcode": true
    }
  ],
  "pagination": {
    "mode": "offset",
    "page": 1,
    "per_page": 20,
    "total": null,
    "pages": null,
    "has_more": true
  }
}

Authorizations

​
X-API-Key
string
header
required

API key passed in the X-API-Key header

Query Parameters

​
q
string

Text search query. Searches brand, product, class, permit number, and applicant/company name. 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 derived top-level categories. Comma-separated values are accepted. These overlap with TTB product types but use COLA Cloud's real-world product categorization.

Available options:
Beer,
Wine,
Liquor
​
derived_subcategory
string

Filter by a derived category path prefix, such as "Beer > Ale" or "Wine > Red Wine".

​
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
string

Filter by application status.

​
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
​
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
​
sort
enum<string>
default:approval_date_desc

Sort order. Defaults to approval date descending. Use relevance_desc with q when strongest text matches should rank first.

Available options:
approval_date_desc,
relevance_desc

Response

Successful response

​
data
object[]
​
pagination
object