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

# Make a Search

AI apps and agents use `/search` to find products across the web.

## The request shape

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "query": "merino wool sweater",
  "filters": {
    "price": { "min_price": 50, "max_price": 200 },
    "availability": ["InStock"],
    "brand_ids": ["..."],
    "website_ids": ["..."],
    "category": "sweaters"
    // and many more
  },
  "limit": 20
}
```

## Get an API key

Search requires an API key. [Create a free account](https://channel3.ai/sign-up/developer), then copy your key.

> [!NOTE]
>
> You get **1,000 free credits each month** — that's good for 1,000 searches.
> Extra usage is billed per call; see [pricing](/docs/pricing.md) for the breakdown.

## Choose a search method

> [card] [Search](/docs/guides/search.md)
>
> Search with text and images.

> [card] [Agentic search](/docs/guides/agentic-search.md)
>
> Interpret longer shopping requests for an agent workflow.

> [card] [Image search](/docs/guides/image-search.md)
>
> Find visually similar products from an image URL or upload.

For a photo with several products in one scene, see [Find products in an image](/docs/guides/image-search.md#find-products-in-an-image).

## Filters

Add optional filters to narrow your search.

> [card] [Price](/docs/guides/price-filters.md)
>
> Constrain results to an offer price range.

> [card] [Color](/docs/guides/color-filters.md)
>
> Find products that match a hex color palette.

> [card] [Dimensions](/docs/guides/dimension-filters.md)
>
> Constrain length, width, height, or weight.

> [card] [Brand](/docs/guides/brand-filters.md)
>
> Filter by the company behind a product.

> [card] [Website](/docs/guides/website-filters.md)
>
> Restrict results to retailer offers from selected websites.

> [card] [Attributes](/docs/guides/attribute-filters.md)
>
> Filter on category-specific structured attributes.

> [card] [Collections](/docs/guides/collections.md)
>
> Save a catalog scope and reuse it on search, browse, and conversations.

## Start from an existing product

> [card] [Look up a product URL](/docs/guides/url-lookup.md)
>
> Get structured data from a URL, and offers at other retailers.

> [card] [Find similar products](/docs/guides/similar-products.md)
>
> Get recommendations from a known Channel3 product ID.

## Attribute clicks to your users

Send the `x-user-id` header on search (and other catalog) requests to tie buy-link clicks and commissions back to a user in your app.

```bash 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 "x-user-id: user_abc123" \
  -H "Content-Type: application/json" \
  -d '{"query": "merino wool sweater", "limit": 20}'
```

Use a stable ID from your system (UUID, Clerk ID, etc.). Letters, numbers, and `.` `_` `@` `-`, up to 128 characters. Filter reporting by the same value — see [By user](/docs/guides/reporting/by-user.md).

```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
await client.products.search({
  query: "merino wool sweater",
  "x-user-id": "user_abc123",
});
```

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
client.products.search(
    query="merino wool sweater",
    user_id="user_abc123",
)
```

## Group a shopper conversation

> [!NOTE]
>
> **Strongly recommended.** Send `x-conversation-id` on every search in a shopper conversation. Channel3 uses it to group that session in your analytics, and a session is much easier to understand when every call shares the id.

Send the `x-conversation-id` header on each search in one shopper conversation. Channel3 stores that id with the search and groups every call that sends the same value.

```bash 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 "x-user-id: user_abc123" \
  -H "x-conversation-id: chat_abc123" \
  -H "Content-Type: application/json" \
  -d '{"query": "merino wool sweater", "limit": 20}'
```

Use a stable id from your app for that conversation. 1–64 characters: letters, numbers, underscores, and hyphens. Send the same header on later catalog requests in that conversation — browse, image search, similar products, and product detail — so they stay in the group.

```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}}
await client.products.search({
  query: "merino wool sweater",
  "x-user-id": "user_abc123",
  "x-conversation-id": "chat_abc123",
});
```

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
client.products.search(
    query="merino wool sweater",
    user_id="user_abc123",
    conversation_id="chat_abc123",
)
```

Send `x-conversation-id` when your app calls `/v1/search` itself. The [Conversational Agent](/docs/conversations.md) is a separate path: pass `conversation_id` in the body of `POST /v1/conversations` to continue a thread, and Channel3 groups the searches that turn runs. See [By conversation](/docs/guides/reporting/by-conversation.md).

## Next

Next: [What you get](/docs/guides/response-overview.md). It explains how products, offers, prices, and buy links appear in a response.


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