> ## 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. # 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. ## OpenAPI ````yaml /openapi.yaml get /colas openapi: 3.0.3 info: title: COLA Cloud 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 all 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 ## 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: support@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 - name: Permittees description: Permit holder operations - name: Barcodes description: Barcode lookup operations - name: Usage description: API usage and rate limit information - name: Saved Searches description: Durable saved-search and scheduled alert operations - name: Reference Data description: > Free reference datasets from the TTB. These endpoints require an API key but do not count against your monthly quota. 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. 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. operationId: listColas parameters: - name: q in: query description: >- Text search query. Searches brand, product, class, permit number, and applicant/company name. 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 derived top-level categories. Comma-separated values are accepted. These overlap with TTB product types but use COLA Cloud's real-world product categorization. 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 derived category path prefix, such as "Beer > Ale" or "Wine > Red Wine". 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 application status. schema: type: string 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 example: '012345678905' - name: approval_date_from in: query description: Filter by minimum approval date (YYYY-MM-DD) schema: type: string format: date example: '2024-01-01' - name: approval_date_to in: query description: Filter by maximum approval date (YYYY-MM-DD) schema: type: string format: date example: '2024-12-31' - name: abv_min in: query description: Filter by minimum alcohol by volume (ABV) percentage schema: type: number format: float example: 12 - name: abv_max in: query description: Filter by maximum alcohol by volume (ABV) percentage schema: type: number format: float example: 15 - name: volume_unit in: query description: >- Filter by package volume unit. Required when volume_min or volume_max is provided. schema: type: string enum: - beer barrels - fluid ounces - gallons - liters - milliliters - pints - quarts example: milliliters - name: volume_min in: query description: Filter by minimum package volume in the selected volume_unit. schema: type: number format: float minimum: 0 example: 375 - name: volume_max in: query description: Filter by maximum package volume in the selected volume_unit. schema: type: number format: float minimum: 0 example: 750 - name: container_type in: query description: >- Filter by one or more derived container types. Comma-separated values are accepted. style: form explode: false schema: type: array items: type: string enum: - bag - bottle - box - can - carton - cask - jug - keg - pod - pouch example: - bottle - can - name: page in: query description: Page number (max 100) schema: type: integer default: 1 minimum: 1 maximum: 100 - name: per_page in: query description: Results per page (max 100) schema: type: integer default: 20 minimum: 1 maximum: 100 - name: sort in: query description: >- Sort order. Defaults to approval date descending. Use relevance_desc with q when strongest text matches should rank first. schema: type: string enum: - approval_date_desc - relevance_desc default: approval_date_desc responses: '200': description: Successful response headers: X-Detail-Views-Limit: $ref: '#/components/headers/X-Detail-Views-Limit' X-Detail-Views-Remaining: $ref: '#/components/headers/X-Detail-Views-Remaining' X-List-Records-Limit: $ref: '#/components/headers/X-List-Records-Limit' X-List-Records-Remaining: $ref: '#/components/headers/X-List-Records-Remaining' X-Quota-Reset: $ref: '#/components/headers/X-Quota-Reset' content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/ColaSummary' pagination: $ref: '#/components/schemas/Pagination' 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 '401': $ref: '#/components/responses/Unauthorized' '429': $ref: '#/components/responses/RateLimitExceeded' components: headers: X-Detail-Views-Limit: description: Your monthly detail view limit schema: type: integer example: 200 X-Detail-Views-Remaining: description: Detail views remaining this month schema: type: integer example: 158 X-List-Records-Limit: description: Your monthly list record limit schema: type: integer example: 500 X-List-Records-Remaining: description: List records remaining this month schema: type: integer example: 350 X-Quota-Reset: description: Unix timestamp when quotas reset (first of next month) schema: type: integer example: 1706745600 schemas: ColaSummary: type: object description: Summary view of a COLA (used in list responses) properties: ttb_id: type: string description: Unique TTB identifier brand_name: type: string description: Brand name on the label product_name: type: string description: Product name product_type: type: string enum: - wine - malt beverage - distilled spirits description: Type of alcohol product class_name: type: string description: TTB classification (e.g., "table red wine") origin_name: type: string description: Country/region of origin permit_number: type: string description: Permit number of the producer/importer approval_date: type: string format: date nullable: true image_count: type: integer description: Number of label images has_barcode: type: boolean description: Whether any barcode was extracted from label images Pagination: type: object properties: mode: type: string enum: - offset - cursor description: Pagination mode page: type: integer description: Current page number (offset mode only) per_page: type: integer description: Results per page total: type: integer nullable: true description: Total number of results (null in offset mode) pages: type: integer nullable: true description: Total number of pages (null in offset mode) has_more: type: boolean description: Whether more results are available next_cursor: type: string nullable: true description: Cursor for next page (cursor mode only) Error: type: object properties: error: type: object properties: code: type: string description: Machine-readable error code message: type: string description: Human-readable error message details: type: object additionalProperties: true description: Additional error metadata required: - code - message - details required: - error responses: Unauthorized: description: Missing or invalid API key or Bearer token content: application/json: schema: $ref: '#/components/schemas/Error' examples: missing_key: summary: Missing API key or Bearer token value: error: code: unauthorized message: >- API key required. Provide via X-API-Key header or Authorization: Bearer. details: {} invalid_key: summary: Invalid API key value: error: code: unauthorized message: Invalid API key. details: {} revoked_key: summary: Revoked API key value: error: code: unauthorized message: This API key has been revoked. details: {} oauth_connection_required: summary: OAuth connection is not linked value: error: code: oauth_connection_required message: No COLA Cloud account is linked to this OAuth connection. details: {} RateLimitExceeded: description: Quota or burst limit exceeded headers: X-Detail-Views-Limit: $ref: '#/components/headers/X-Detail-Views-Limit' X-Detail-Views-Remaining: $ref: '#/components/headers/X-Detail-Views-Remaining' X-List-Records-Limit: $ref: '#/components/headers/X-List-Records-Limit' X-List-Records-Remaining: $ref: '#/components/headers/X-List-Records-Remaining' X-Quota-Reset: $ref: '#/components/headers/X-Quota-Reset' Retry-After: description: Seconds to wait before retrying (for per-minute burst limits) schema: type: integer example: 60 content: application/json: schema: $ref: '#/components/schemas/Error' examples: detail_view_quota: summary: Detail view quota exceeded value: error: code: quota_exceeded message: >- Detail view quota exceeded. Upgrade your plan for more detail views. details: limit: 200 used: 200 upgrade_url: https://app.colacloud.us/dashboard/subscriptions list_record_quota: summary: List record quota exceeded value: error: code: quota_exceeded message: >- List record quota exceeded. Upgrade your plan for more list records. details: limit: 500 used: 500 upgrade_url: https://app.colacloud.us/dashboard/subscriptions minute_limit: summary: Per-minute burst limit exceeded value: error: code: rate_limit_exceeded message: Too many requests. Please wait before making more requests. details: limit_per_minute: 10 retry_after: 60 securitySchemes: ApiKeyHeader: type: apiKey in: header name: X-API-Key description: API key passed in the X-API-Key header BearerApiKey: type: http scheme: bearer description: | API key passed as `Authorization: Bearer `, or a linked WorkOS OAuth access token passed as `Authorization: Bearer `. API keys are equivalent to the X-API-Key scheme. OAuth tokens must include the scope required by the endpoint. ````