Semantic search
Semantic (meaning-based) product search powered by AI embeddings. Understands natural-language
queries like “wireless headphones with noise cancellation” — matching shopper intent against
product meaning rather than literal keyword overlap. Results carry a similarity score and a
matchReason.
Auth: works with both publishable (tybrite_pk_*) and secret (tybrite_sk_*) API keys.
Despite using POST (to carry the structured request body), this is a read-only operation,
so publishable keys are allowed for client-side storefront search.
When to use: prefer this over the text GET /v1/search (searchProducts) when the query
is conversational or descriptive. Two tuning options:
minScore(default0.3, range0.0–1.0) raises the similarity floor — increase it (e.g.0.5) to return only strong matches and suppress loosely-related products.personalize(defaultfalse) nudges ranking toward a signed-in shopper’s preferences when you also pass that shopper’s session token asx-auth-token; relevance stays primary (it is blended, not replaced). Without a customer session it has no effect.
Marketplace: when called with a marketplace operator key, searches products across all merchants in the marketplace.
Authorizations
API Key Authentication
Use your API key in the Authorization header:
Key Types:
Secret Keys (Server-Side Only):
- Format:
tybrite_sk_live_*(production) ortybrite_sk_test_*(sandbox) - Full read/write access to all endpoints
- ⚠️ NEVER expose in client-side code or public repositories
- Required for: write operations, authentication, payment verification, AI recommendations
Publishable Keys (Client-Safe):
- Format:
tybrite_pk_live_*(production) ortybrite_pk_test_*(sandbox) - Read-only access (GET requests only, plus POST semantic search)
- ✅ Safe for client-side JavaScript, mobile apps, and public code
- Allowed for: browsing products, search, CMS content, pricing queries
Endpoint-Specific Requirements:
- Authentication endpoints (
/v1/auth/*): Secret key required - Payment verification (
POST /v1/payments/verify): Secret key required - AI Recommendations (
POST /v1/recommendations): Secret key required - Semantic Search (
POST /v1/search): Both key types allowed (read-only operation) - All write operations: Secret key required
- All read operations: Both key types allowed
Using a publishable key for restricted operations returns 403 Forbidden.
Body
Natural language search query
Maximum number of results to return
1 <= x <= 100Minimum similarity score threshold (0.0 to 1.0)
0 <= x <= 1When true and the request is made on behalf of a signed-in customer (pass the
customer's session token as x-auth-token), results are nudged toward the
shopper's preferences while keeping query relevance primary (relevance is
blended with preference, not replaced). Without a customer session, or for a
shopper with no preference signal yet, ranking is by query relevance only.

