Skip to main content
The POST /v1/search endpoint is the core of Channel3. Pass a free-text query and get back a ranked list of products with prices, availability, images, and merchant offers. 
import Channel3 from "@channel3/sdk";

const client = new Channel3(); // reads CHANNEL3_API_KEY from env

const results = await client.products.search({
  query: "merino wool sweater",
});

console.log(results.products[0].title);
console.log(results.products[0].offers[0].price);

from channel3_sdk import Channel3

client = Channel3()  # reads CHANNEL3_API_KEY from env

results = client.products.search(query="merino wool sweater")

print(results.products[0].title)
print(results.products[0].offers[0].price)

curl -X POST https://api.trychannel3.com/v1/search \
  -H "x-api-key: $CHANNEL3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "merino wool sweater"}'

​
Filters

Narrow results with filters. Every filter is optional — combine as many as you need. 
const results = await client.products.search({
  query: "running shoes",
  filters: {
    price:        { min_price: 50, max_price: 150 },
    availability: ["InStock", "LimitedAvailability"],
    gender:       "male",
    category:     "running-shoes",        // category slug
    brand_ids:    ["brand_id_1"],         // from /v1/brands/search
  },
  limit: 20,
});

results = client.products.search(
    query="running shoes",
    filters={
        "price":        {"min_price": 50, "max_price": 150},
        "availability": ["InStock", "LimitedAvailability"],
        "gender":       "male",
        "category":     "running-shoes",
        "brand_ids":    ["brand_id_1"],
    },
    limit=20,
)
These are the filters most integrations use. See the API reference for the complete list.
FilterTypeDescription
price{ min_price?, max_price? }Price range in the request’s currency.
availabilitystring[]One or more of InStock, LimitedAvailability, PreOrder, BackOrder, SoldOut, OutOfStock.
genderstringmale, female, or unisex.
categorystringA category slug (e.g. running-shoes). See Categories.
brand_idsstring[]Limit to specific brands. Resolve brand IDs via /v1/brands/search.
attributesRecord<string, string[]>Filter by structured attribute key/value pairs — e.g. { "connectivity": ["USB"] }. Attribute keys come from category detail. See Advanced Search.
colors{ hex: string, percentage?: number }[]Filter by color palette using hex values (Beta).
agestringnewborn, infant, toddler, kids, or adult.
dimensions{ length?, width?, height?, weight? }Filter by physical size and weight, each { min?, max?, unit }. See Dimension Filters.

​
Pagination

Use next_page_token from the response to fetch the next page. You can page up to 500 products total. 
const page1 = await client.products.search({ query: "running shoes" });
console.log("Page 1:", page1.products.length, "products");

if (page1.next_page_token) {
  const page2 = await client.products.search({
    query: "running shoes",
    page_token: page1.next_page_token,
  });
  console.log("Page 2:", page2.products.length, "products");
}

page1 = client.products.search(query="running shoes")
print(f"Page 1: {len(page1.products)} products")

if page1.next_page_token:
    page2 = client.products.search(
        query="running shoes",
        page_token=page1.next_page_token,
    )
    print(f"Page 2: {len(page2.products)} products")

​
Search modes

config.mode selects the search strategy. default combines keyword (lexical) and semantic (vector) search and is the right choice for most use cases — the other two modes trade that balance for speed or depth.
ModeWhat it doesUse it for
defaultLexical + semantic search.Most product search. This is the default.
keywordLexical only — skips semantic search.Real-time, low-latency needs like ad targeting, SKU or exact-name lookups.
agenticAn LLM plans multiple structured sub-searches.Complex, multi-constraint queries where quality matters more than latency.
Set mode: "keyword" to skip semantic (vector) search and use exact keyword matching instead. This path is optimized for super low latency — use it when users type specific product names or SKUs, or when you need the fastest possible search response. 
const results = await client.products.search({
  query: "Nike Air Max 90",
  config: { mode: "keyword" },
});

results = client.products.search(
    query="Nike Air Max 90",
    config={"mode": "keyword"},
)
mode: "keyword" replaces the deprecated keyword_search_only: true, which still works and behaves identically.
Set mode: "agentic" when queries read like a person describing what they want rather than a keyword phrase — an LLM decomposes the query into structured sub-searches so every constraint becomes a real filter. See Agentic Search for how it works and when to use it.