Semantic search

Semantic search using embeddings and cosine similarity. Understands natural language queries like “wireless headphones with noise cancellation”.

✅ BOTH KEY TYPES SUPPORTED

This endpoint works with both secret keys (tybrite_sk_) and publishable keys (tybrite_pk_).

Note: Despite using POST method (to support complex request bodies with parameters), this is a read-only operation. Publishable keys are allowed for client-side search functionality.

POST /v1/search

Semantic search

cURL

curl --request POST \
  --url https://api.tybritelabs.com/v1/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "wireless headphones with noise cancellation",
  "limit": 10,
  "minScore": 0.5
}
'

200

{
  "query": "<string>",
  "results": [
    {
      "productId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "score": 0.93,
      "matchReason": "Semantic match"
    }
  ],
  "totalResults": 123,
  "searchTimeMs": 123,
  "message": "<string>"
}

Authorizations

Authorization · string · header · required

API Key Authentication

Use your API key in the Authorization header:

Authorization: Bearer tybrite_sk_live_YOUR_KEY

Key Types:

Secret Keys (Server-Side Only):

• Format: tybrite_sk_live_* (production) or tybrite_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) or tybrite_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

application/json

query · string · required

Natural language search query

limit · integer · default: 20

Maximum number of results to return

Required range: 1 <= x <= 100

minScore · number<float> · default: 0.3

Minimum similarity score threshold (0.0 to 1.0)

Required range: 0 <= x <= 1

Response

200

application/json

Success

query · string

results · object[]

Show child attributes

totalResults · integer

searchTimeMs · integer

message · string