COLA Cloud COLAs API

openapi: 3.2.0
info:
  title: COLA Cloud COLAs API
  description: 'Access the United States TTB COLA Registry through COLA Cloud''s self-service API.


    ## Overview


    COLA Cloud provides programmatic access to the 2005-forward application database for

    Certificate of Label Approval (COLA) data from the Alcohol and Tobacco Tax and Trade Bureau

    (TTB). Bulk warehouse delivery remains available separately through a data license. The

    self-service API includes:


    - 2005-forward approved alcohol labels

    - Product details, brand information, and approval dates

    - Label images with barcodes and QR codes

    - Permittee (permit holder) information

    - LLM-enriched data including tasting notes and category classification


    ## Authentication


    Self-serve REST, SDK, and CLI requests use a COLA Cloud API key. Include your

    key in the `X-API-Key` header:


    ```

    curl -H "X-API-Key: your_api_key_here" https://app.colacloud.us/api/v1/colas

    ```


    MCP clients may pass the same API key as `Authorization: Bearer `.

    Linked assistant OAuth connections may also call the API with a WorkOS-issued

    Bearer token. OAuth access is scoped per connected app and is in private

    rollout until account linking is self-serve.


    ## Quotas


    Usage is metered by **detail views** (single-record lookups) and **list records** (items returned by list/search endpoints), not raw request count. Quotas are per-user across all channels (web, API, SDKs, CLI, MCP).


    | Tier | Detail Views/mo | List Records/mo | Burst/min |

    |------|----------------|-----------------|-----------|

    | Free | 200 | 10,000 | 10 |

    | Starter | 2,000 | 100,000 | 60 |

    | Pro | 10,000 | 1,000,000 | 120 |


    Quota headers are included in metered route responses:


    - `X-Detail-Views-Limit`: Your monthly detail view limit

    - `X-Detail-Views-Remaining`: Detail views remaining this month

    - `X-List-Records-Limit`: Your monthly list record limit

    - `X-List-Records-Remaining`: List records remaining this month

    - `X-Quota-Reset`: Unix timestamp when quotas reset


    A `429 quota_exceeded` requires pausing the affected monthly meter until reset

    or a confirmed entitlement change. A `429 rate_limit_exceeded` requires waiting

    for `Retry-After` seconds before another call, including `/usage`. A

    `503 limiter_unavailable` means the rate-limiting service is unavailable;

    respect `Retry-After` with a bounded retry budget. Limits remain enforced.


    ## Pagination


    List endpoints support pagination via `page` and `per_page` parameters:


    - `page`: Page number (default: 1)

    - `per_page`: Results per page (default: 20, max: 100)


    Responses include pagination metadata:


    ```json

    {

    "data": [...],

    "pagination": {

    "mode": "offset",

    "page": 1,

    "per_page": 20,

    "total": null,

    "pages": null,

    "has_more": true

    }

    }

    ```


    For deep result sets, use **cursor-based pagination** with the `cursor` parameter

    (returned as `next_cursor` in the response). Cursor pagination performs consistently

    regardless of depth.'
  version: 1.0.0
  contact:
    name: COLA Cloud Support
    email: help@colacloud.us
    url: https://colacloud.us
  license:
    name: Proprietary
    url: https://colacloud.us/terms
servers:
- url: https://app.colacloud.us/api/v1
  description: Production server
security:
- ApiKeyHeader: []
- BearerApiKey: []
tags:
- name: COLAs
  description: Certificate of Label Approval operations
paths:
  /colas:
    get:
      tags:
      - COLAs
      summary: Search COLAs
      description: '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, except for exact 14-digit TTB-ID searches and non-approved

        status filters (`expired`, `surrendered`, or `revoked`), which search all available history.

        Explicit date filters always take precedence. The `defaults_applied` field in the response

        indicates when the recent-date default is active.'
      operationId: listColas
      parameters:
      - name: q
        in: query
        description: 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.
        schema:
          type: string
        example: cabernet sauvignon napa
      - name: product_type
        in: query
        description: Filter by one or more TTB product types. Comma-separated values are accepted.
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
            enum:
            - wine
            - malt beverage
            - distilled spirits
        example:
        - wine
        - malt beverage
      - name: category
        in: query
        description: 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.
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
            enum:
            - Beer
            - Wine
            - Liquor
        example:
        - Beer
        - Wine
      - name: derived_subcategory
        in: query
        description: 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.
        schema:
          type: string
        example: Beer > Ale
      - name: origin
        in: query
        description: Filter by origin/country (e.g., "american", "french", "italian")
        schema:
          type: string
        example: american
      - name: domestic_or_imported
        in: query
        description: Filter by domestic or imported origin.
        schema:
          type: string
          enum:
          - domestic
          - imported
        example: domestic
      - name: status
        in: query
        description: Filter by current TTB application status. Non-approved statuses search all available history when no explicit approval-date filter is supplied.
        schema:
          type: string
          enum:
          - approved
          - expired
          - surrendered
          - revoked
        example: approved
      - name: brand_name
        in: query
        description: Filter by brand name (partial match, case-insensitive)
        schema:
          type: string
        example: Opus One
      - name: permit_number
        in: query
        description: Filter by permit number (exact match, e.g., "CA-I-12345")
        schema:
          type: string
        example: CA-I-12345
      - name: barcode_value
        in: query
        description: Filter by the COLA record's main barcode value (exact match). Numeric values may include spaces or hyphens.
        schema:
          type: string