Get product recommendations

AI-powered product recommendations with 5 types:

• similar: Products similar to given product (embedding-based)
• also-bought: Frequently purchased together (co-purchase matrix)
• trending: Currently trending products (velocity-based)
• personalized: Based on customer preferences
• bundle: Bundle suggestions (semantic + co-purchase)

⚠️ SECRET KEY REQUIRED

This endpoint requires a secret key (tybrite_sk_*). Publishable keys will return 403 Forbidden.

Why Secret Key? AI recommendation generation uses computational resources and accesses machine learning models that should be protected from unauthorized use. This prevents abuse and ensures fair resource allocation.

POST /v1/recommendations

cURL

similar

curl --request POST \
  --url https://api.tybritelabs.com/v1/recommendations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "similar",
  "productId": "9b2bb0c5-666d-4729-a59d-2526ec38add9",
  "limit": 5
}
'

200

{
  "type": "similar",
  "recommendations": [
    {
      "productId": "d8cea277-9bb6-4942-b9e9-2f2ac351509f",
      "score": 0.99,
      "reason": "Similar product based on description and attributes"
    },
    {
      "productId": "9cd6e472-de84-435c-be43-957b56682f43",
      "score": 0.85,
      "reason": "Similar product based on description and attributes"
    }
  ],
  "fromCache": true,
  "computedAt": "2026-02-03T10:30:00Z"
}

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

type · enum<string> · required

Available options: similar, also-bought, trending, personalized, bundle

productId · string<uuid>

Required when type is similar, also-bought, or bundle. Must reference an existing product in the store; otherwise 404 is returned.

customerId · string<uuid>

Optional for personalized. When omitted, the worker falls back to trending recommendations.

limit · integer · default: 10

Required range: 1 <= x <= 50

Response

200

application/json

Success

type · string

recommendations · object[]

Show child attributes

fromCache · boolean

computedAt · string<date-time>

fallbackUsed · string