> ## 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.
</Note>

<Frame caption="Color search demo">
  <iframe src="https://www.linkedin.com/embed/feed/update/urn:li:ugcPost:7465145869307322368?compact=1" frameborder="0" allowfullscreen="" title="Embedded post" />
</Frame>

## Basic color filter

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

<CodeGroup>
  ```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" }] } }
    }'
  ```
</CodeGroup>

## 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."

<CodeGroup>
  ```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"},
              ],
          },
      },
  )
  ```
</CodeGroup>

## 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.