Search COLAs

Search and filter Certificates of Label Approval with full-text search and various filters. Results are ordered by approval date (descending).

When no explicit date filters (approval_date_from, approval_date_to) are provided, results default to the last 365 days. This applies to all queries, including text search. To search the full historical database, pass approval_date_from explicitly (e.g., 2005-01-01). The defaults_applied field in the response indicates when this default is active.

GET /colas

Search COLAs

cURL

curl --request GET \
  --url https://app.colacloud.us/api/v1/colas \
  --header 'X-API-Key: <api-key>'

200

Example

{
  "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

ApiKeyHeaderBearerApiKey

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

200

application/json

Successful response

data · object[]

Show child attributes

pagination · object

Show child attributes