How to Search Products by Color with the Channel3 API (Color Filters, Now in Beta)

Last updated: June 8, 2026

The Channel3 API now supports color filtering on product search: add one or more colors — as hex values — to your search request and you get back products that contain them. It is live in beta today.

Color is one of the most common ways people describe what they want to buy — and now your shopping agent can filter for it in a single call.

Why color matters for shopping agents

Color is rarely a nice-to-have in product discovery — it is often the whole intent. Shoppers think in terms of "burgundy," "sage," "off-white," and a result set that ignores color feels like it ignored the request. For agents building on the Channel3 API, filtering by color turns a vague visual intent into a precise, structured query, so the products that come back actually look like what the shopper pictured.

Inspired by Cosmos

We added color filters after seeing the color search built by Cosmos — a visual discovery app for creatives that lets you search and filter inspiration by color, keyword, or image. Their color search is genuinely one of the best implementations we have seen, and it is what made us want to bring the same precision to product search in the Channel3 API.

How to use color filters

Color filtering lives in the filters object on POST /v1/search. Add a colors.palette array, where each entry is a color given as an sRGB hex value:

POST /v1/search
{
  "query": "leather jacket",
  "filters": {
    "colors": {
      "palette": [
        { "hex": "#000000" }
      ]
    }
  }
}

Pass more than one color to match a multi-color product. The colors are combined with AND, so the API returns only products that contain every color you list — not products that contain just one of them. A palette of red and blue, for example, returns products that are red and blue (think a red-and-blue varsity jacket), not products that are only red or only blue:

POST /v1/search
{
  "query": "leather jacket",
  "filters": {
    "colors": {
      "palette": [
        { "hex": "#000000" },
        { "hex": "#8B4513", "percentage": 0.2 }
      ]
    }
  }
}

That second call finds leather jackets containing both black and brown, with brown expected at roughly 20% of the product. The optional percentage lets you say how much of each color you expect; leave it off and Channel3 applies a sensible default based on how many colors you have listed.

Two things worth knowing:

• Hex in, perceptual match out. You pass a hex code, and matching is done by perceptual color distance — so you get products that are visually close to your color, not only exact hex matches.
• It composes with everything else. The color filter is just another entry in filters, so it stacks with query, brand, price, category, and the rest in a single call.

See it in action

What you can build

• Color-aware shopping agents that honor "find me this, but in forest green."
• Shop-the-look and palette matching — require a multi-color palette so results fit a moodboard or a room's color scheme.
• Better visual-to-product flows — extract a hex (or a palette) from an image upstream, then pass it straight into a color-filtered product search.

Try it

Color filters are live in beta now. Add a colors filter to your next POST /v1/search call and see what comes back.

Start building →

FAQ