> ## 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. # Get COLA details > Retrieve detailed information for a single COLA by its TTB ID. Includes all label images with stable CloudFront URLs and barcode data. Counts as one detail view against your quota. ## OpenAPI ````yaml /openapi.yaml get /colas/{ttb_id} 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: 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 - 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/{ttb_id}: get: tags: - COLAs summary: Get COLA details description: | Retrieve detailed information for a single COLA by its TTB ID. Includes all label images with stable CloudFront URLs and barcode data. Counts as one detail view against your quota. operationId: getCola parameters: - name: ttb_id in: path required: true description: The unique TTB identifier for the COLA schema: type: string example: '24001234567' 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: $ref: '#/components/schemas/ColaDetail' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '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: ColaDetail: type: object description: Detailed view of a COLA (includes all fields, images, and barcodes) allOf: - $ref: '#/components/schemas/ColaSummary' - type: object properties: class_id: type: string description: TTB class ID code origin_id: type: string description: TTB origin ID code latest_update_date: type: string format: date nullable: true is_distinctive_container: type: boolean for_distinctive_capacity: type: string nullable: true description: Volume of the distinctive container as free text is_resubmission: type: boolean for_resubmission_ttb_id: type: string nullable: true for_exemption_state: type: string nullable: true address_recipient: type: string nullable: true description: Label recipient name address_zip_code: type: string nullable: true address_state: type: string nullable: true grape_varietals: type: array items: type: string nullable: true description: Grape varieties (wine only) wine_vintage_year: type: integer nullable: true description: Vintage year (wine only) wine_appellation: type: string nullable: true description: Wine appellation (wine only) llm_container_type: type: string nullable: true description: LLM-identified container type (bottle, can, etc.) llm_product_description: type: string nullable: true description: LLM-generated product description llm_brand_established_year: type: integer nullable: true llm_tasting_note_flavors: type: array items: type: string nullable: true description: LLM-extracted tasting notes llm_artwork_credit: type: string nullable: true llm_wine_designation: type: string nullable: true llm_beer_ibu: type: string nullable: true description: IBU rating (beer only) llm_beer_hops_varieties: type: array items: type: string nullable: true llm_liquor_aged_years: type: integer nullable: true llm_liquor_finishing_process: type: string nullable: true llm_liquor_grains: type: array items: type: string nullable: true barcode_type: type: string nullable: true description: Primary barcode type (upca, ean13, etc.) barcode_value: type: string nullable: true description: Primary barcode value qrcode_url: type: string nullable: true description: URL encoded in QR code (if present) has_front_image: type: boolean has_back_image: type: boolean has_neck_image: type: boolean has_strip_image: type: boolean images: type: array items: $ref: '#/components/schemas/ColaImage' barcodes: type: array items: $ref: '#/components/schemas/Barcode' 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 ColaImage: type: object properties: ttb_image_id: type: string description: Unique image identifier image_index: type: integer description: Image index within the COLA container_position: type: string enum: - front - back - neck - strip - other description: Position on the container extension_type: type: string description: File extension (jpg, png, etc.) width_pixels: type: integer height_pixels: type: integer width_inches: type: number format: float nullable: true height_inches: type: number format: float nullable: true file_size_mb: type: number format: float barcode_count: type: integer qrcode_count: type: integer image_url: type: string format: uri description: Stable CloudFront URL for the image Barcode: type: object properties: barcode_type: type: string description: Barcode format (upca, ean13, qr, etc.) barcode_value: type: string description: Decoded barcode value ttb_image_id: type: string description: Image this barcode was found in width_pixels: type: integer height_pixels: type: integer orientation: type: string enum: - horizontal - vertical - square relative_image_position: type: string description: Position in the image (e.g., "bottom center") 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: {} NotFound: description: Resource not found content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: not_found message: COLA 12345678901 not found 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. ````