Recommendations

Get product recommendations

AI-powered product recommendations. Supported types:

similar: Products similar to a given product
also-bought: Frequently purchased together. Each item indicates whether it is a complement (commonly bought alongside) or an alternative.
next: The products a shopper is most likely to view or add next, given what they have viewed/added in the current session. Pass sessionId (the worker anchors on the shopper’s most recent product this session) and/or an explicit productId anchor. Falls back to also-bought, then trending, when there is no session signal.
trending: Currently trending products
new: Recently added products
personalized: Based on a customer’s preferences
bundle: Bundle suggestions. Items that complement the product are surfaced ahead of alternatives.

Minimum results. Every response is topped up to at least 8 products (capped at limit, and at the number of active products in the store), so a storefront shelf never renders with only one or two items. When the requested algorithm returns fewer than eight, the response is backfilled — in order — from trending, engagement signals (views/adds-to-cart), featured products, and newest arrivals, de-duplicated and excluding the anchor product; fallbackUsed then includes backfill.

⚠️ SECRET KEY REQUIRED

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

Why Secret Key? 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.

Marketplace operator keys. With a marketplace operator key, recommendations are computed across all merchants in the marketplace; supported types: trending, new, also-bought, similar, personalized, bundle, next. Each item is stamped with its source merchant (merchant_store_id).

POST

recommendations

curl --request POST \
  --url https://api.tybritelabs.com/v1/recommendations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "similar",
  "productId": "7d425c0a-50e7-4e39-af79-6f7945f9dfa8",
  "limit": 5
}
'

{
  "type": "similar",
  "recommendations": [
    {
      "productId": "7d425c0a-50e7-4e39-af79-6f7945f9dfa8",
      "score": 0.99,
      "reason": "Similar product based on description and attributes"
    },
    {
      "productId": "0186665f-f0a1-4c79-976a-919b5b1c2daa",
      "score": 0.85,
      "reason": "Similar product based on description and attributes"
    }
  ],
  "fromCache": true,
  "computedAt": "2026-06-20T10:30:00Z"
}

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request parameters",
    "details": "The 'email' field is required"
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid Authorization header"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "This operation requires a secret key. Publishable keys have read-only access."
  }
}

{
  "error": {
    "code": "not_found",
    "message": "Resource not found"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests for this API key. Please slow down and try again shortly.",
    "remaining": 0,
    "reset": 1706198400
  }
}

{
  "error": {
    "code": "server_error",
    "message": "An unexpected error occurred"
  }
}

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,

next,

trending,

new,

personalized,

bundle

productId

string<uuid>

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

sessionId

string

Used with type next. The shopper's current session identifier; the most recent product viewed/added in that session is used as the anchor when productId is not supplied.

customerId

string<uuid>

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

limit

integer

default:10

Required range: 1 <= x <= 50

Response

Success

type

string

recommendations

object[]

Show child attributes

fromCache

boolean

computedAt

string<date-time>

fallbackUsed

string

Get one curated section with its members

Most-viewed products (windowed)

curl --request POST \
  --url https://api.tybritelabs.com/v1/recommendations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "similar",
  "productId": "7d425c0a-50e7-4e39-af79-6f7945f9dfa8",
  "limit": 5
}
'

{
  "type": "similar",
  "recommendations": [
    {
      "productId": "7d425c0a-50e7-4e39-af79-6f7945f9dfa8",
      "score": 0.99,
      "reason": "Similar product based on description and attributes"
    },
    {
      "productId": "0186665f-f0a1-4c79-976a-919b5b1c2daa",
      "score": 0.85,
      "reason": "Similar product based on description and attributes"
    }
  ],
  "fromCache": true,
  "computedAt": "2026-06-20T10:30:00Z"
}

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request parameters",
    "details": "The 'email' field is required"
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid Authorization header"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "This operation requires a secret key. Publishable keys have read-only access."
  }
}

{
  "error": {
    "code": "not_found",
    "message": "Resource not found"
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests for this API key. Please slow down and try again shortly.",
    "remaining": 0,
    "reset": 1706198400
  }
}

{
  "error": {
    "code": "server_error",
    "message": "An unexpected error occurred"
  }
}

Reference

System

Products

Taxonomy

Orders

Payments

Cart & Wishlist

Marketplace

Recommendations

Discovery

Events

Tax

Analytics

Search

Authentication

Customers

Gift Cards

Promotions

CMS

Pricing

Messaging

Shipping

GC Connect

Reviews

Returns

Disputes

B2B

Webhooks

Ingestion

Sandbox

Get product recommendations

Authorizations

Body

Response