---
title: "Create a saved search"
method: POST
path: "/saved-searches"
tags: ["Saved Searches"]
---

# Create a saved search

`POST /saved-searches`

## Request

- Base URL: `https://app.colacloud.us/api/v1`
- URL: `https://app.colacloud.us/api/v1/saved-searches`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

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.

## Request body

- SavedSearchCreateRequest
  - `name` string: Human-readable saved search name
  - `filters` SavedSearchFilters, required: 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).
    - `query` string, nullable
    - `brand_name` string, nullable
    - `barcode_value` string, nullable: Exact filter against the COLA record's main barcode value.
    - `application_status` 'approved' | 'expired' | 'surrendered' | 'revoked', nullable: Current TTB application status.
    - `type_malt_beverage` boolean
    - `type_wine` boolean
    - `type_distilled_spirit` boolean
    - `derived_beer` boolean
    - `derived_wine` boolean
    - `derived_liquor` boolean
    - `derived_category` string, nullable
    - `origin_domestic` boolean
    - `origin_imported` boolean
    - `country` string, nullable
    - `us_state` string, nullable
    - `permit_number_text` string, nullable
    - `applicant_us_state` string, nullable
    - `abv_min` number, float, nullable: Meaningful for active recurring schedules only when greater than 0.
    - `abv_max` number, float, nullable: Meaningful for active recurring schedules only when less than 100.
    - `volume_unit` 'beer barrels' | 'fluid ounces' | 'gallons' | 'liters' | 'milliliters' | 'pints' | 'quarts', nullable: Required when volume_min or volume_max is set.
    - `volume_min` number, float, nullable
    - `volume_max` number, float, nullable
    - `container_bottle` boolean
    - `container_can` boolean
    - `container_keg` boolean
    - `container_box` boolean
    - `container_cask` boolean
    - `container_pouch` boolean
    - `container_pod` boolean
    - `container_carton` boolean
    - `container_bag` boolean
    - `container_jug` boolean
  - `schedule` SavedSearchSchedule
    - `active` boolean
    - `cadence` 'daily' | 'weekly' | 'monthly', nullable
    - `day` integer, nullable: Weekly uses 0-6 where 0 is Monday; monthly uses 1-28.

## Response `201`

Saved search created

- object
  - `data` SavedSearch
    - `uuid` string, uuid
    - `name` string
    - `filters` SavedSearchFilters: 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).
      - `query` string, nullable
      - `brand_name` string, nullable
      - `barcode_value` string, nullable: Exact filter against the COLA record's main barcode value.
      - `application_status` 'approved' | 'expired' | 'surrendered' | 'revoked', nullable: Current TTB application status.
      - `type_malt_beverage` boolean
      - `type_wine` boolean
      - `type_distilled_spirit` boolean
      - `derived_beer` boolean
      - `derived_wine` boolean
      - `derived_liquor` boolean
      - `derived_category` string, nullable
      - `origin_domestic` boolean
      - `origin_imported` boolean
      - `country` string, nullable
      - `us_state` string, nullable
      - `permit_number_text` string, nullable
      - `applicant_us_state` string, nullable
      - `abv_min` number, float, nullable: Meaningful for active recurring schedules only when greater than 0.
      - `abv_max` number, float, nullable: Meaningful for active recurring schedules only when less than 100.
      - `volume_unit` 'beer barrels' | 'fluid ounces' | 'gallons' | 'liters' | 'milliliters' | 'pints' | 'quarts', nullable: Required when volume_min or volume_max is set.
      - `volume_min` number, float, nullable
      - `volume_max` number, float, nullable
      - `container_bottle` boolean
      - `container_can` boolean
      - `container_keg` boolean
      - `container_box` boolean
      - `container_cask` boolean
      - `container_pouch` boolean
      - `container_pod` boolean
      - `container_carton` boolean
      - `container_bag` boolean
      - `container_jug` boolean
    - `schedule` SavedSearchSchedule
      - `active` boolean
      - `cadence` 'daily' | 'weekly' | 'monthly', nullable
      - `day` integer, nullable: Weekly uses 0-6 where 0 is Monday; monthly uses 1-28.
    - `created_at` string, date-time, nullable
    - `manage_url` string, uri
    - `dashboard_url` string, uri

## Other responses

- `400`: Invalid schedule or filters
- `401`: Missing or invalid API key or Bearer token
- `403`: Missing scope, feature disabled, or scheduled watchlist limit reached
- `429`: Quota or burst limit exceeded

---

[API](https://skmtc.dev/colacloud/apis/cola-cloud-api.md) · [All operations](https://skmtc.dev/colacloud/apis/cola-cloud-api/llms.txt) · [OpenAPI document](https://skmtc.dev/colacloud/apis/cola-cloud-api/revisions/1cb00a02112c?raw)