Smart Search

The SearchService class (accessed via client.search) provides keyword search, type-ahead suggestions, and semantic search.

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
}

Misspellings

When exact matching finds nothing, the query is retried against a similarity match over product names and brands, so a typo still reaches the product. Those results carry a matchReason of Similar name or Similar brand rather than Text match, which lets you label them — “showing results for snowboard” — instead of presenting an approximate match as an exact one. Exact matches always rank first: the fallback runs only when there were none, so a query that already worked behaves exactly as before.

const result = await client.search.searchProducts({ q: 'snoboard' });
// result.results[0].matchReason === 'Similar name'

Response

{
  "query": "snoboard",
  "results": [
    { "productId": "02525ff5-0916-4f00-857c-c2c6237e671b", "score": 0.583333, "matchReason": "Similar name" }
  ],
  "totalResults": 1
}

`autocompleteSearch`

Suggestions for a partial query, for a search box that completes as the shopper types. Call it on each keystroke from the second character; it returns terms to suggest, not products, so run searchProducts once the shopper picks one. Suggestions come from what the store actually sells — its product names, its brands, and the merchant’s own subcategories — so there is nothing to configure and nothing that drifts from the catalogue. Each carries a kind so you can group or badge them. Prefixes match first, with similarity as a fallback, so a suggestion still appears when the first characters are already mistyped. Fewer than two characters returns an empty list with a 200 — a shopper mid-word has not done anything wrong.

const result = await client.search.autocompleteSearch({
  q: 'sno',   // 'prefix' also accepted
  limit: 5
});

Response

{
  "query": "sno",
  "suggestions": [
    { "suggestion": "Snowboard Vendor", "kind": "brand", "score": 0.9025 },
    { "suggestion": "snowboard", "kind": "subcategory", "score": 0.81 },
    { "suggestion": "The Draft Snowboard", "kind": "product", "score": 0.75 }
  ]
}

Requires a store-scoped key; marketplace operator keys are rejected.

`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 credential identifying the shopper to nudge results toward their 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. Send whichever credential matches how the shopper signed in — the same three this API accepts everywhere a shopper is identified:

Header	Use it when
`x-auth-token`	The shopper signed in through Galactic Core.
`x-external-auth`	You authenticate shoppers with your own identity provider and send a signed assertion.
`x-idp-token`	You pass your identity provider’s own token straight through for Galactic Core to verify.

Personalization is best-effort: an absent, expired, or invalid credential returns unpersonalized results rather than an error, so search never fails because a session lapsed.

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 }
});
// returns same { query, results: [{ productId, score }], totalResults } shape as above,
//   re-ranked to blend query relevance with this shopper's preference signal.

Merchandising

A merchant can place results deliberately for a query or a family of queries, from their own admin. There is nothing to request or configure on the client — the order you receive already reflects it, and a store with no rules behaves exactly as it did before.

Action	Effect
Pin	The product is placed at the top of the results for that query.
Bury	The product drops to the bottom, without being removed.
Boost	The product lifts past its near neighbours, but does not jump the queue.

A rule matches a query either exactly or by substring, can be limited to a date range, and carries a priority that decides the winner where two rules overlap. Each rule can name up to twenty products. Rules reorder; they never conjure. They are applied after ranking and only to products the query already matched, so a rule cannot introduce an unrelated product, and a pinned product that has been deleted, taken offline, or is otherwise not sellable simply does not appear. Nothing a merchant hides becomes visible through a pin. One consequence is worth building for: a pinned product is fetched and merged in even if it ranked below the page you asked for, because “float it to the top” would otherwise do nothing for exactly the products a merchant most wants pinned. The limit you asked for is still honoured. Pinned and boosted results carry a matchReason of Featured by the store. That is the signal to build against if you want to distinguish a deliberate placement from an earned one:

const { results } = await client.search.searchProducts({ q: 'headphones' });

results.forEach((r) => {
  const featured = r.matchReason === 'Featured by the store';
  console.log(`${r.name}${featured ? '  (featured)' : ''}`);
});

Merchandising rules are authored in the merchant’s admin, not through this API — placing your own products in someone’s search results is not something an integration should be able to do. The API reflects the merchant’s decisions; it does not set them.

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`

Misspellings

`autocompleteSearch`

`semanticSearch`

Personalized results

Merchandising

Comparison: Text vs. Semantic

Response Codes

​Methods

​searchProducts

​Misspellings

​autocompleteSearch

​semanticSearch

​Personalized results

​Merchandising

​Comparison: Text vs. Semantic

​Response Codes

Methods

`searchProducts`

Misspellings

`autocompleteSearch`

`semanticSearch`

Personalized results

Merchandising

Comparison: Text vs. Semantic

Response Codes