---
title: "Search"
method: POST
path: "/v0/search"
tags: ["channel3-api"]
---

# Search

`POST /v0/search`

Search for products.

## Request body

- LegacyInternalSearchRequest — v0 search request (frozen, no pagination).
  - `query` string, nullable — Search query
  - `image_url` string, nullable — Image URL
  - `base64_image` string, nullable — Base64 encoded image
  - `limit` integer, nullable — Optional limit on the number of results. Default is 20, max is 30.
  - `filters` LegacyInternalSearchFilters — v0 search filters with deprecated fields.
    - `brand_ids` string[], nullable — If provided, only products from these brands will be returned
    - `gender` 'male' | 'female', nullable
    - `condition` 'new' | 'refurbished' | 'used', nullable — Filter by offer condition. Requires at least one offer matching the requested condition, locale, and any price filter. Offers without condition data are indexed as new.
    - `age` string[], nullable — Filter by age group. Age-agnostic products are treated as adult products.
    - `price` SearchFilterPrice — Price filter for search. Values are inclusive.
      - `min_price` number, nullable — Minimum price, in dollars and cents
      - `max_price` number, nullable — Maximum price, in dollars and cents
    - `availability` AvailabilityStatus[], nullable — If provided, only products with these availability statuses will be returned
    - `sale` 'on_sale', nullable — If 'on_sale', only products with at least one on-sale offer (priced below its compare-at price) for the requested locale are returned. If omitted, no filter.
    - `website_ids` string[], nullable — If provided, only products from these websites will be returned. Accepts website IDs or domains (e.g. "nike.com").
    - `category_ids` string[], nullable — If provided, only products from these categories will be returned. Accepts category slugs.
    - `exclude_brand_ids` string[], nullable — If provided, products from these brands will be excluded from the results
    - `exclude_website_ids` string[], nullable — If provided, products from these websites will be excluded from the results. Accepts website IDs or domains (e.g. "nike.com").
    - `exclude_category_ids` string[], nullable — If provided, products in these categories (or their descendants) will be excluded from the results. Accepts category slugs.
    - `colors` SearchColorsFilter — [Beta] Color filter wrapper. Holds required colors and optional match mode.
      - `palette` SearchFilterColor[], required — Colors required in matching products. Treated as an AND condition.
        - `hex` string, required — sRGB hex string, e.g. '#a1b2c3'
        - `percentage` number, nullable — Percentage of color, where 1.0 is 100%
      - `match` 'strict' | 'standard' | 'loose' — How tightly a product's colors must match the requested palette.
    - `attributes` object, nullable — If provided, only products whose extracted attributes match these key/value constraints will be returned. Keys are attribute handles (e.g. 'color', 'material') and values are lists of allowed values (OR within a key, AND across keys). When a category filter is also supplied, all keys must be valid attributes of at least one of the requested categories. See `Category.attributes` for the valid keys/values per category.
    - `dimensions` SearchFilterDimensions — Physical-dimension range filters, matched against the same offer. Matching products have at least one offer satisfying every provided range (alongside any locale/price/availability filters). Values are compared with a small relative tolerance. An offer with no dimension data for a filtered field does not match; note that when a single merchant on a product reports a dimension it is shared across that product's offers, so a matching offer may not itself surface that dimension in the response.
      - `length` SearchFilterLengthDimension
        - `min` number, nullable — Minimum value, in `unit`. Inclusive.
        - `max` number, nullable — Maximum value, in `unit`. Inclusive.
        - `unit` 'mm' | 'cm' | 'm' | 'in' | 'ft', required
      - `width` SearchFilterLengthDimension
        - `min` number, nullable — Minimum value, in `unit`. Inclusive.
        - `max` number, nullable — Maximum value, in `unit`. Inclusive.
        - `unit` 'mm' | 'cm' | 'm' | 'in' | 'ft', required
      - `height` SearchFilterLengthDimension
        - `min` number, nullable — Minimum value, in `unit`. Inclusive.
        - `max` number, nullable — Maximum value, in `unit`. Inclusive.
        - `unit` 'mm' | 'cm' | 'm' | 'in' | 'ft', required
      - `weight` SearchFilterWeightDimension
        - `min` number, nullable — Minimum value, in `unit`. Inclusive.
        - `max` number, nullable — Maximum value, in `unit`. Inclusive.
        - `unit` 'mg' | 'g' | 'kg' | 'oz' | 'lb', required
    - `exclude_product_ids` string[], nullable — Deprecated: this field is accepted but ignored. It has no effect on search results.
  - `config` LegacyInternalSearchConfig — v0 search configuration with deprecated fields.
    - `redirect_mode` 'brand' | 'price' | 'commission' — "price" redirects to the product page with the lowest price "commission" redirects to the product page with the highest commission rate "brand" redirects to the brand's product page
  - `context` string, nullable — Optional customer information to personalize search results

## Response `200`

Successful Response

- LegacyInternalProduct[]
  - `id` string, required
  - `title` string, required
  - `description` string, nullable
  - `brands` ProductBrand[] — Ordered list of brands.
    - `id` string, required
    - `name` string, required
  - `images` LegacyInternalProductImage[]
    - `url` string, required
    - `cleaned_url` string, nullable — Background-removed square image on Channel3 CDN when available. Use for product grids; ``url`` is the regular hosted shot.
    - `is_main_image` boolean
    - `is_cleaned_image` boolean — Deprecated: always ``false``. Use ``cleaned_url`` for product grids when set; otherwise ``url``.
    - `shot_type` 'hero' | 'lifestyle' | 'on_model' | 'detail' | 'scale_reference' | 'angle_view' | 'flat_lay' | 'in_use' | 'packaging' | 'size_chart' | 'product_information' | 'merchant_information' — Product image type classification for API responses.
    - `alt_text` string, nullable
    - `photo_quality` 'professional' | 'ugc' | 'poor' — Photo quality classification for API responses.
  - `categories` string[]
  - `category` CategorySummary — Lean category representation used in search hits and list rows.
    - `slug` string, required — URL-friendly slug (e.g. 'sofas')
    - `title` string, required — Human-readable category title
    - `path` CategoryRef[] — Hierarchical path as a structured list, root first; the last entry is this category itself
      - `slug` string, required — URL-friendly slug (e.g. 'sofas')
      - `title` string, required — Human-readable category title
    - `has_children` boolean, required — Whether this category has subcategories
  - `gender` 'male' | 'female' | 'unisex', nullable
  - `age` 'newborn' | 'infant' | 'toddler' | 'kids' | 'adult', nullable — Target age group. Age-agnostic products are typically returned as 'adult'.
  - `materials` string[], nullable
  - `key_features` string[], nullable
  - `offers` ProductOffer[] — All merchant offers for this product in the requested locale.
    - `url` string, required
    - `domain` string, required
    - `price` Price, required
      - `price` number, required — The current price of the product, including any discounts.
      - `compare_at_price` number, nullable — The original price of the product before any discounts.
      - `currency` string, required — The currency code of the product, like USD, EUR, GBP, etc.
    - `availability` 'InStock' | 'OutOfStock', required
    - `condition` 'new' | 'refurbished' | 'used', nullable — Condition of this merchant offer (new, used, or refurbished). Null when condition is unknown.
    - `max_commission_rate` number — The maximum commission rate for the merchant, as a decimal fraction: 0 is no commission, 0.5 is 50% commission. 'Max' because the actual commission rate may be lower due to vendor-specific affiliate rules.
    - `dimensions` Dimensions — Physical dimensions of a product offer. Members are null when unknown. Values are standardized to the supported unit set; a merchant-stated value whose unit is not one of those units is omitted rather than shown.
      - `length` LengthDimension — A length measurement, in one of the supported length units.
        - `number` number, required
        - `unit` 'mm' | 'cm' | 'm' | 'in' | 'ft', required
      - `width` LengthDimension — A length measurement, in one of the supported length units.
        - `number` number, required
        - `unit` 'mm' | 'cm' | 'm' | 'in' | 'ft', required
      - `height` LengthDimension — A length measurement, in one of the supported length units.
        - `number` number, required
        - `unit` 'mm' | 'cm' | 'm' | 'in' | 'ft', required
      - `weight` WeightDimension — A weight measurement, in one of the supported weight units.
        - `number` number, required
        - `unit` 'mg' | 'g' | 'kg' | 'oz' | 'lb', required
  - `variants` Variants — Wrapper for variant-interaction state on a Product. Holds `options` and `selected`. `options` represent all of the configuration options for the product. `selected` represents the currently selected option values.
    - `options` VariantOption[], required
      - `name` string, required — The name of the option (e.g. 'Color', 'Size')
      - `values` OptionValue[], required — The values of the option (e.g. ['Blue', 'Red', 'Green'])
        - `label` string, required — The display value of the option value (e.g. 'Blue')
        - `exists` boolean, required — Whether the option value exists on the product, or is a configuration only present on another variant of the same product. For example, a shirt that comes in multiple colors, but only one color is available in Size XL.
        - `available` 'InStock' | 'LimitedAvailability' | 'PreOrder' | 'BackOrder' | 'SoldOut' | 'OutOfStock' | 'Discontinued' | 'Unknown'
        - `thumbnail_url` string, nullable — For options that reference different products, this is the URL of the thumbnail image for the option value. E.g., a shoe that comes in multiple colors will have an OptionValue for each color with a thumbnail_url set.
        - `product_id` string, nullable — The product id that represents this value. Variants that point to different products will have this field set, as well as thumbnail_url for displaying selector icons.
    - `selected` SelectedOption[], required
      - `name` string, required — The name of the selected option (e.g. 'Color', 'Size')
      - `label` string, required — The display value of the selected option (e.g. 'Blue', 'XL')
  - `structured_attributes` object — Structured attributes extracted for this product, keyed by attribute handle (e.g. 'color', 'material'). Values are the canonical allowed values for that handle.
  - `url` string, required — Deprecated, use offers field
  - `brand_id` string, nullable
  - `brand_name` string, nullable
  - `image_urls` string[] — List of image URLs (deprecated, use images field)
  - `price` Price, required
    - `price` number, required — The current price of the product, including any discounts.
    - `compare_at_price` number, nullable — The original price of the product before any discounts.
    - `currency` string, required — The currency code of the product, like USD, EUR, GBP, etc.
  - `availability` 'InStock' | 'OutOfStock', required — Deprecated, use offers field
  - `score` integer, required
  - `image_url` string, required — Main product image (deprecated, use images field)
  - `family_id_v3` string, nullable

## Other responses

- `400` — Bad request
- `401` — Unauthorized - Invalid or missing authentication
- `402` — Payment required
- `422` — Validation Error
- `500` — Internal Server Error

---

[API](https://skmtc.net/channel3-ai/apis/fastapi.md) · [All operations](https://skmtc.net/channel3-ai/apis/fastapi/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/channel3-ai/fastapi/revisions/981d371bd83e/schema)