> ## 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.

# Quickstart

> Create an account, generate an API key, and make your first request in under 5 minutes.

## 1. Create an Account

<Steps>
  <Step title="Sign up">
    Visit [app.colacloud.us/auth/register](https://app.colacloud.us/auth/register) and sign up with email or Google.
  </Step>

  <Step title="Verify email">
    Check your inbox and verify your email address.
  </Step>

  <Step title="Generate an API key">
    Go to **Dashboard > API Keys** and click **Create API Key**. Copy your key — it won't be shown again.
  </Step>
</Steps>

## 2. Make Your First Request

Search for bourbon labels:

<CodeGroup>
  ```bash cURL theme={null}
  curl -H "X-API-Key: your_api_key" \
    "https://app.colacloud.us/api/v1/colas?q=bourbon&per_page=5"
  ```

  ```python Python SDK theme={null}
  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}")
  ```

  ```typescript JavaScript SDK theme={null}
  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}`);
  }
  ```

  ```bash CLI theme={null}
  cola search "bourbon" --limit 5
  ```
</CodeGroup>

## 3. Look Up a Product by Barcode

Find COLAs associated with a UPC/EAN barcode:

<CodeGroup>
  ```bash cURL theme={null}
  curl -H "X-API-Key: your_api_key" \
    "https://app.colacloud.us/api/v1/barcode/012345678901"
  ```

  ```python Python SDK theme={null}
  matches = client.barcode.lookup("012345678901")
  ```

  ```typescript JavaScript SDK theme={null}
  const matches = await client.barcodes.lookup('012345678901');
  ```

  ```bash CLI theme={null}
  cola barcode 012345678901
  ```
</CodeGroup>

<Tip>
  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.
</Tip>

## 4. Check Your Usage

```bash theme={null}
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:

```json theme={null}
{
  "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.

## Search Filters

`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.                                                   |

```bash theme={null}
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

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/authentication">
    API key usage, rate limits, and pagination
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/colas/search-colas">
    Interactive API playground
  </Card>

  <Card title="SDKs & Tools" icon="wrench" href="/sdks/python">
    Python, JavaScript, CLI, and MCP server
  </Card>

  <Card title="Dataset Schema" icon="database" href="/data-products/snowflake">
    Full schema with 100+ columns
  </Card>
</CardGroup>