Quickstart

1. Create an Account

Visit app.colacloud.us/auth/register and sign up with email or Google.

Verify email

Check your inbox and verify your email address.

Generate an API key

Go to Dashboard > API Keys and click Create API Key. Copy your key — it won’t be shown again.

2. Make Your First Request

Search for bourbon labels:

curl -H "X-API-Key: your_api_key" \
  "https://app.colacloud.us/api/v1/colas?q=bourbon&per_page=5"

from colacloud import ColaCloud

client = ColaCloud(api_key="your_api_key")
results = client.colas.list(q="bourbon", per_page=5)

for cola in results.data:
    print(f"{cola.brand_name} - {cola.product_name}")

import { ColaCloud } from 'colacloud';

const client = new ColaCloud({ apiKey: 'your_api_key' });
const results = await client.colas.list({ q: 'bourbon', perPage: 5 });

for (const cola of results.data) {
  console.log(`${cola.brandName} - ${cola.productName}`);
}

cola search "bourbon" --limit 5

3. Look Up a Product by Barcode

Find COLAs associated with a UPC/EAN barcode:

curl -H "X-API-Key: your_api_key" \
  "https://app.colacloud.us/api/v1/barcode/012345678901"

matches = client.barcode.lookup("012345678901")

const matches = await client.barcodes.lookup('012345678901');

cola barcode 012345678901

Use /api/v1/colas?barcode_value=012345678901 when you want to filter COLA Search results by the record’s main barcode and combine that with other /colas filters. Use /api/v1/barcode/{barcode_value} when you want the dedicated enrichment lookup across extracted barcode rows.

4. Check Your Usage

curl -H "X-API-Key: your_api_key" \
  "https://app.colacloud.us/api/v1/usage"

Default Date Range

When no date filters are provided, the /colas endpoint returns results from the last 365 days. The response includes a defaults_applied field indicating when this default is active:

{
  "defaults_applied": {
    "date_range": true,
    "date_from": "2025-03-01"
  }
}

Pass approval_date_from or approval_date_to to override this default and query the full historical dataset. q is a general text search across brand, product, class, permit number, applicant/company name, and barcode-shaped queries. Use it when you know a word but not which field it belongs to. Common /colas filters include:

Filter	Use
`product_type`	TTB product type: `wine`, `malt beverage`, or `distilled spirits`. Comma-separated values are supported.
`category` / `derived_subcategory`	COLA Cloud’s derived category tree, such as `Beer` and `Beer > Ale`.
`abv_min` / `abv_max`	Alcohol by volume range.
`volume_unit` with `volume_min` / `volume_max`	Package size range. Volume ranges require a unit, such as `fluid ounces` or `milliliters`.
`container_type`	Derived container type, such as `bottle`, `can`, `keg`, or `box`.
`barcode_value` / `permit_number`	Exact filters for a main barcode or TTB permit number.

curl -H "X-API-Key: your_api_key" \
  "https://app.colacloud.us/api/v1/colas?category=Beer&derived_subcategory=Beer%20%3E%20Ale&container_type=can&volume_unit=fluid%20ounces&volume_min=12&volume_max=16"

Next Steps

Authentication

API key usage, rate limits, and pagination

API Reference

Interactive API playground

SDKs & Tools

Python, JavaScript, CLI, and MCP server

Dataset Schema

Full schema with 100+ columns

Getting Started

API Reference

SDKs & Tools

Guides

Data Products

Regulatory Reference (Experimental)

Trust

1. Create an Account

2. Make Your First Request

3. Look Up a Product by Barcode

4. Check Your Usage

Default Date Range

Search Filters

Next Steps

Authentication

API Reference

SDKs & Tools

Dataset Schema

​1. Create an Account

​2. Make Your First Request

​3. Look Up a Product by Barcode

​4. Check Your Usage

​Default Date Range

​Search Filters

​Next Steps

Authentication

API Reference

SDKs & Tools

Dataset Schema

1. Create an Account

2. Make Your First Request

3. Look Up a Product by Barcode

4. Check Your Usage

Default Date Range

Search Filters

Next Steps