> ## 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. # Create a saved search > Create a durable saved search using the non-date filter field names from the web app's SearchForm. Include a schedule object to enable a recurring saved-search alert. OAuth callers must have the `saved_searches:write` scope. Approval-date filters are not saved-search configuration; scheduled runs use the saved search's previous run and current run as the approval-date window. Broad recurring searches without a meaningful filter are rejected. Each user can have up to 10 active scheduled watchlists. ## OpenAPI ````yaml /openapi.yaml post /saved-searches 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: /saved-searches: post: tags: - Saved Searches summary: Create a saved search description: > Create a durable saved search using the non-date filter field names from the web app's SearchForm. Include a schedule object to enable a recurring saved-search alert. OAuth callers must have the `saved_searches:write` scope. Approval-date filters are not saved-search configuration; scheduled runs use the saved search's previous run and current run as the approval-date window. Broad recurring searches without a meaningful filter are rejected. Each user can have up to 10 active scheduled watchlists. operationId: createSavedSearch requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SavedSearchCreateRequest' example: name: Weekly California cabernet approvals filters: query: cabernet type_wine: true schedule: cadence: weekly day: 0 active: true responses: '201': description: Saved search created content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/SavedSearch' '400': description: Invalid schedule or filters content: application/json: schema: $ref: '#/components/schemas/Error' '401': $ref: '#/components/responses/Unauthorized' '403': description: >- Missing scope, feature disabled, or scheduled watchlist limit reached content: application/json: schema: $ref: '#/components/schemas/Error' '429': $ref: '#/components/responses/RateLimitExceeded' security: - ApiKeyHeader: [] - BearerApiKey: [] components: schemas: SavedSearchCreateRequest: type: object required: - filters properties: name: type: string description: Human-readable saved search name example: Weekly California cabernet approvals filters: $ref: '#/components/schemas/SavedSearchFilters' schedule: $ref: '#/components/schemas/SavedSearchSchedule' SavedSearch: type: object properties: uuid: type: string format: uuid name: type: string filters: $ref: '#/components/schemas/SavedSearchFilters' schedule: $ref: '#/components/schemas/SavedSearchSchedule' created_at: type: string format: date-time nullable: true manage_url: type: string format: uri dashboard_url: type: string format: uri 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 SavedSearchFilters: type: object description: > Filters using non-date web SearchForm field names. Approval-date filters are intentionally not part of saved-search configuration; active recurring schedules apply the date window for each run. ABV bounds only count as meaningful when they narrow the range (`abv_min` greater than 0 or `abv_max` less than 100). additionalProperties: false properties: query: type: string nullable: true brand_name: type: string nullable: true barcode_value: type: string nullable: true description: Exact filter against the COLA record's main barcode value. type_malt_beverage: type: boolean type_wine: type: boolean type_distilled_spirit: type: boolean derived_beer: type: boolean derived_wine: type: boolean derived_liquor: type: boolean derived_category: type: string nullable: true origin_domestic: type: boolean origin_imported: type: boolean country: type: string nullable: true us_state: type: string nullable: true permit_number_text: type: string nullable: true applicant_us_state: type: string nullable: true abv_min: type: number format: float nullable: true description: Meaningful for active recurring schedules only when greater than 0. abv_max: type: number format: float nullable: true description: Meaningful for active recurring schedules only when less than 100. volume_unit: type: string nullable: true enum: - beer barrels - fluid ounces - gallons - liters - milliliters - pints - quarts description: Required when volume_min or volume_max is set. volume_min: type: number format: float nullable: true volume_max: type: number format: float nullable: true container_bottle: type: boolean container_can: type: boolean container_keg: type: boolean container_box: type: boolean container_cask: type: boolean container_pouch: type: boolean container_pod: type: boolean container_carton: type: boolean container_bag: type: boolean container_jug: type: boolean SavedSearchSchedule: type: object properties: active: type: boolean default: true cadence: type: string nullable: true enum: - daily - weekly - monthly day: type: integer nullable: true description: Weekly uses 0-6 where 0 is Monday; monthly uses 1-28. 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 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 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. ````