> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trychannel3.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Color

Find products that match one or more colors.

This is useful for building color-matched shopping experiences — for example, finding brown couches or blue Dodger's gear.

> [!NOTE]
>
> Color filtering is currently in **Beta**. The API surface may change.

[Embedded post](https://www.linkedin.com/embed/feed/update/urn:li:ugcPost:7465145869307322368?compact=1)

Color search demo

## Basic color filter

Add one or more colors to your search. Each color needs a **hex code** (like `#5D3FD3`).

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
import Channel3 from "@channel3/sdk";

const client = new Channel3();

const results = await client.products.search({
  query: "sofa",
  filters: {
    colors: {
      palette: [{ hex: "#5D3FD3" }],
    },
  },
});
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from channel3_sdk import Channel3

client = Channel3()

results = client.products.search(
    query="sofa",
    filters={
        "colors": {"palette": [{"hex": "#5D3FD3"}]},
    },
)
```

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://api.trychannel3.com/v1/search \
  -H "x-api-key: $CHANNEL3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "sofa",
    "filters": { "colors": { "palette": [{ "hex": "#5D3FD3" }] } }
  }'
```

## Multiple colors

Provide a palette of colors to find products that match the combination. Every color in the palette must be present — it's **AND**, not "red OR blue."

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const results = await client.products.search({
  query: "throw pillow",
  filters: {
    colors: {
      palette: [{ hex: "#1A1A2E" }, { hex: "#E2B96F" }],
    },
  },
});
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
results = client.products.search(
    query="throw pillow",
    filters={
        "colors": {
            "palette": [
                {"hex": "#1A1A2E"},
                {"hex": "#E2B96F"},
            ],
        },
    },
)
```

## Color percentages

Use **percentage** for **relative prominence** when a product has multiple colors — which one dominates, and which are accents. It does **not** mean "80% of the image must be blue."

"Mostly blue, with a little brown" would look like:

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const results = await client.products.search({
  query: "area rug",
  filters: {
    colors: {
      palette: [
        { hex: "#1E3A8A", percentage: 0.8 }, // dominant
        { hex: "#8B4513", percentage: 0.2 }, // accent
      ],
    },
  },
});
```

That tells the API a **4:1 ratio** (more blue than brown).

Omit `percentage` when you only care that all colors appear, not how they're weighted (e.g. "red, white, and blue" with no strong dominance preference).

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const results = await client.products.search({
  query: "patriotic t-shirt",
  filters: {
    colors: {
      palette: [{ hex: "#FF0000" }, { hex: "#FFFFFF" }, { hex: "#0000FF" }],
    },
  },
});
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.