Skip to main content
The /v1/search endpoint is the core of Channel3. Make a requests and get back a list of products with prices, availability, images, and retailer offers.

Attribute clicks to a user

Send x-user-id on search, and on other catalog requests, to tie buy-link clicks and commissions to a user in your app. Use a stable id from your system (UUID, Clerk ID, and so on): letters, numbers, and . _ @ -, up to 128 characters. Filter clicks and sales by the same value.

Group a shopper conversation

Strongly recommended for better analytics. Send x-conversation-id on every search in a shopper conversation, and again on browse, image search, similar products, and product detail in that conversation.
The same value groups those calls in your Channel3 analytics. Use 1–64 characters: letters, numbers, underscores, and hyphens. Send x-conversation-id when your app calls /v1/search itself. The Conversational Agent 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.

Filters

Narrow results with filters. Every filter is optional — combine as many as you need.
These are the filters most integrations use. See the API reference for the complete list.

Pagination

Use next_page_token from the response to fetch the next page. You can page up to 500 products total. A request with a next_page_token costs one credit. See pricing.

Collections

Pass config.collection_id to search inside a saved catalog scope (brands, websites, categories, and/or specific products). Request filters still apply and can only narrow the collection. See Collections. Set mode: "keyword" to skip semantic (vector) search and use exact keyword matching instead. This path is optimized for low latency — use it when users type specific product names or SKUs, or when you need the fastest possible search response.