Smart Search

The SearchService class (accessed via client.search) provides both traditional keyword-based search and advanced AI-powered semantic search capabilities.

Methods

`searchProducts`

Fast, keyword-based search optimized for exact matches, SKUs, and product names. It uses case-insensitive partial matching to find relevant results quickly.

const result = await client.search.searchProducts({
  q: 'headphones', // You can use 'q' or 'query'
  limit: 10
});

console.log(`Found ${result.totalResults} results`);
// Each result: { productId, score, matchReason: "Text match" }

Response

{
  "query": "headphones",
  "results": [
    { "productId": "69fbb1fe-6b96-4e7b-b86d-07c3799aa626", "score": 1, "matchReason": "Text match" }
  ],
  "totalResults": 1
}

`semanticSearch`

AI-powered, meaning-based search that understands intent and context. This allows customers to find products using natural language descriptions even if they don’t know the exact product name.

Key Support: Both Secret Keys and Publishable Keys are supported for semantic search, allowing you to implement AI-powered search directly in your frontend.

const result = await client.search.semanticSearch({
  requestBody: {
    query: 'wireless earbuds for the gym',
    limit: 8,
    minScore: 0.5 // Optional: raise the similarity floor to return only strong matches (default 0.3)
  }
});

// Each result: { productId, score } ranked by semantic similarity
result.results.forEach(r => console.log(`${r.productId} — score ${r.score}`));

Response

{
  "query": "wireless earbuds for the gym",
  "results": [
    { "productId": "f4992a40-38a1-4ebd-9390-3ecfb9d10093", "score": 0.89 },
    { "productId": "f6a2629e-f899-4615-b17a-e78e2e4c35a4", "score": 0.88 },
    { "productId": "7d425c0a-50e7-4e39-af79-6f7945f9dfa8", "score": 0.85 },
    { "productId": "69fbb1fe-6b96-4e7b-b86d-07c3799aa626", "score": 0.83 }
  ],
  "totalResults": 50
}

Personalized results

Pass personalize: true together with a signed-in customer’s session token (the x-auth-token header) to nudge results toward that shopper’s preferences. Query relevance stays primary — relevance is blended with the shopper’s preference signal, not replaced — so results remain on-topic. Without a customer session, or for a shopper with no preference signal yet, ranking is by query relevance only.

const personalized = new Tybrite({
  apiKey: 'tybrite_pk_live_...',
  headers: { 'x-auth-token': customerSessionToken },
});

const result = await personalized.search.semanticSearch({
  requestBody: { query: 'gear for the gym', limit: 5, personalize: true }
});
// → same { query, results: [{ productId, score }], totalResults } shape as above,
//   re-ranked to blend query relevance with this shopper's preference signal.

Comparison: Text vs. Semantic

Feature	`searchProducts` (Text)	`semanticSearch` (AI)
Logic	Case-insensitive keyword matching	Meaning-based matching via AI embeddings
Best For	SKUs, Model numbers, Exact names	Natural language, Intent, “Vibes”
Example	”MacBook Pro”, “SKU-990"	"a laptop for professional video editing”
Speed	Ultra-fast	Fast

Zero-Result Fallback: A powerful UX pattern is to first call searchProducts. If totalResults is 0, gracefully fallback to semanticSearch to suggest products that might still interest the user.

Why is semanticSearch a POST? POST /v1/search is intentionally accessible to publishable keys despite using the POST verb. It is a read-only operation — POST is used purely to support complex JSON request bodies (query, minScore, filters). No state is mutated and no 403 is returned for publishable keys.

Response Codes

Both methods accept publishable and secret keys. searchProducts is GET; semanticSearch is POST (read-only).

Code	Meaning
`200`	Search results returned (may be empty — check `totalResults`).
`400`	Missing `query`/`q` parameter, invalid `limit`, or malformed request body.
`401`	Invalid or missing API key.
`429`	Rate limit exceeded.
`500`	Internal server error or upstream embedding-service failure (semantic search only).

Get Started

Core Commerce

Discovery

Checkout & Logistics

Marketplace

B2B (Wholesale)

Account & Support

System & Store

Integrations

Methods

`searchProducts`

`semanticSearch`

Personalized results

Comparison: Text vs. Semantic

Response Codes

​Methods

​searchProducts

​semanticSearch

​Personalized results

​Comparison: Text vs. Semantic

​Response Codes

Methods

`searchProducts`

`semanticSearch`

Personalized results

Comparison: Text vs. Semantic

Response Codes