Introduction#
What is Discovery API?#
Discovery API V2 is Sensefuel's unified API for building intelligent product discovery experiences across e-commerce channels.It provides a single interface for:Catalog Browse / Faceted Navigation
Why Discovery API V2?#
Discovery API V2 consolidates capabilities that were previously distributed across multiple APIs into a single, consistent integration model.Unified API Design for Search, Browse, and Recommendations
Consistent Response Structure across discovery use cases
Real-Time Hyper-Personalization based on visitor behavior
Advanced Merchandising Features such as Spotlights and Showcases
Flexible Filtering and Navigation
Simplified Integration and Maintenance
Main Use Cases#
Discovery API can be used to power a wide range of e-commerce experiences:Search#
Allow customers to find products using natural search queries, autocomplete suggestions, references, and advanced filtering options.Browse (Listing)#
Build category pages, brand pages, thematic collections, and any catalog navigation experience based on your merchandising structure.Recommend#
Display personalized product recommendations across the customer journey, including home pages, product pages, cart pages, and custom placements.Content Discovery#
Search and surface editorial content such as buying guides, blog articles, FAQs, recipes, or inspiration pages.How Discovery Works#
To generate the most relevant results, Discovery API leverages several types of information:Catalog data (products, variants, offers)
Business rules and merchandising strategies
Collective intelligence learned from the behavior and interactions of all your users across the platform
Individual intelligence, derived from each user's historical and real-time behavior
Before You Start#
Before integrating Discovery API, we recommend becoming familiar with the following concepts:Search and Browse Features
Getting Started#
Authentication#
All Discovery API V2 endpoints are protected using API Key authentication.
To authenticate your requests, include your API key in the X-API-KEY header.Every request to Discovery API V2 also requires a valid siteUUID in the request pathSome endpoints additionally require an X-Session-Id header to enable real-time personalization.To get your siteUUID and X-API-KEY you must connect to Sensefuel's platform.
API Key Authentication#
Include your API key in every request:Requests missing a valid API key will be rejected.Site UUID#
All Discovery API resources are associated with a specific Sensefuel data environment, named site.The siteUUID path parameter identifies the catalog, configuration, and behavioral data used to process the request./api/sites/{siteUUID}/search/products
Session Identification#
Search and Browse experiences rely on a session identifier to support real-time behavioral learning and personalization.For endpoints that require it, provide the session ID using the X-Session-Id header:A session ID should remain stable throughout a user's browsing session and be regenerated when a new session starts.Ranking Token#
The ranking token is returned by Search and Listing responses and can be reused when requesting additional pages.
Using the ranking token helps preserve ranking consistency across paginated requests.Credentials Management#
To ensure a secure integration:Never expose API keys in public repositories.
Avoid embedding credentials directly in client-side applications.
Store credentials in a secure secret management solution.
Rotate API keys according to your organization's security policies.
Grant credentials only to authorized systems and personnel.
Core Concepts#
Product Model#
The Product Model defines how catalog data is represented in Discovery API.Discovery supports multiple catalog structures, from simple product catalogs to complex multi-store or multi-offer environments.Products & Variants#
Products represent the items available in your catalog.A product can contain one or more variants (SKU) that correspond to purchasable options such as size, color, capacity, or any other attribute specific to your catalog structure.Variants belonging to the same product are grouped through the item_group_id attribute. This identifier allows Discovery to understand that multiple variants belong to the same parent product while preserving their individual characteristics.For example, all variants of a t-shirt available in different sizes and colors would share the same item_group_id.Offers#
Offers represent the commercial availability of a product within a specific business context.This concept is primarily used in multi-store, multi-inventory, or multi-price environments where product availability may differ depending on the requested context.store_code#
The store_code identifies the store, location, or business context associated with an offer.When a store_code is provided, Discovery only returns products that have an offer for the requested context.Conversely, a product that does not have an offer associated with the selected store_code is excluded in that context and cannot be returned by Search, Browse, or Recommendation requests.User Model#
Discovery API uses several identifiers to understand what users are currently doing, and how results should be personalized.The user model is built around two main concepts:Together, these signals allow Sensefuel to combine historical knowledge about a user with their real-time behavior.user_id#
The user_id uniquely identifies a browser across visits.It is the primary identifier used by Sensefuel to build and reuse an individual's behavioral profile over time.When the same user_id is provided across multiple sessions, Discovery can leverage past interactions such as:This historical knowledge enables long-term personalization across Search, Browse, and Recommendation experiences.User
├─ Session #1
├─ Session #2
├─ Session #3
└─ Session #N
session_id#
The session_id identifies a user's current visit.Unlike the user_id, which may persist across multiple visits, a session identifier represents a single browsing session.User ID
├─ Session ID #1
├─ Session ID #2
└─ Session ID #3
As events are received, Discovery continuously updates personalization in real time.Session should expires 30 minutes after the browser is closed or inactivity.
X-Session-Id header.Segments#
Segments provide additional business context about a user.
They allow external information known by your platform to trigger Discovery experiences previously configured by business users in Sensefuel's platform.{
"customer_type": "vip",
"loyalty_tier": "gold",
}
B2B / B2C differentiation
Custom business audiences
Key Takeaways#
Discovery personalization relies on both long-term and short-term signals:| Signal | Purpose |
|---|
user_id | Understands the user across visits |
session_id | Understands the user's current intent |
segments | Adds business-specific context |
Recommendation Model#
All recommendation strategies available in Sensefuel are personalized.Each recommendation slot is configured by your business teams to use a specific recommendation algorithm according to the desired customer experience and business objective.Recommendation Algorithms#
| Algorithm | Purpose |
|---|
| Significant Similarity | Recommends products similar to the current product based on catalog attributes. |
| Individualized Cross-Selling | Learns which complementary products are most relevant for each user. |
| Ideal Next Purchase | Recommends products based on recent purchases and cart activity. |
| Personal Interest | Recommends products based on recent browsing and interaction history. |
| Relevant Exploring | Recommends alternative products that match the user's interests while encouraging discovery. |
| Linked Products | Recommends products explicitly associated in your catalog. |
| Selection | Recommends products from a business-defined selection while personalizing their ranking for each user. |
Fallback Behavior#
Some algorithms require recent behavioral signals such as:When insufficient information is available, Sensefuel automatically falls back to the best-performing products for the current context.Automatic Exclusions#
Products already added to the user's cart are automatically excluded from recommendation results, whether recommendations are delivered through the Sensefuel JavaScript Tag or Discovery API.Slots#
A slot represents a recommendation placement within a customer journey.Common examples include home pages, product detail pages, cart pages, and other custom placements throughout the experience.Each slot can contain one or more configurations managed by business teams in the Sensefuel platform. These configurations define how recommendations should behave according to business objectives, user audiences, product contexts, or merchandising strategies.When a recommendation request is performed, Discovery automatically selects the most relevant configuration for the current context.slot_id#
A slot_id uniquely identifies a recommendation placement.The recommendation strategy itself is configured and managed by business teams within the Sensefuel platform. Discovery automatically determines which configuration should be applied for the current context.Tracking & Learning#
Behavioral tracking is a fundamental part of every Discovery integration. Sensefuel needs behavioral data to work properly and to continuously improve search relevance, browsing experiences, recommendations, as well as providing analytics.To provide these behavioral signals, Sensefuel offers two integration approaches:Both approaches feed the same learning engine and can be used depending on your technical architecture.Behavioral data serves two main purposes:AI Learning, enabling Sensefuel to continuously improve personalization, relevance, and recommendation quality
Analytics & Performance Measurement, providing insights into user behavior and the business impact of Search, Browse, and Recommendation experiences
JavaScript Tag (Hybrid integration)#
When using the Sensefuel JavaScript Tag, a user identifier user_idand a session_id is automatically generated and maintained by the tag.It can be retrieved through the tracking interface:These identifiers should be reused whenever Discovery API requests are executed outside of the tag itself.GDPR
When using the Sensefuel JavaScript Tags, GDPR compliance is managed through the deployment of an additional Sensefuel multi-session tag. Click here to know more. Activity Tracking API#
When using the Activity Tracking API the user_id and track_id areGenerated through the Activity Tracking API call
or
Provided by your own identification system
In Activity Tracking API, the session identifier is historically referred to as track_id. Throughout this documentation, the term session_id is used to describe the same concept.
If supplied, the identifier is preserved and returned by Sensefuel. Otherwise, Sensefuel automatically generates an identifier and returns it in the response for future use.
session_id and user_id must not contain personally identifiable information (PII).
GDPR
When integrating Discovery API with Activity Tracking API directly
As a general rule:Without consent,user_id should be stored in non-persistent storage and regenerated when a new session starts.
With consent,user_id may be stored in persistent storage and reused across visits.
Search & Browse Associated Features#
Search#
Browse (listing)#
Recommend#
Recommendation Slots#
Integration Guides#
Build a Search Result Page#
Build an Autocomplete Experience#
Build Real-Time Hyper-Personalized Faceted Navigation#
Migration Guides#
Recommend API → Discovery V2
FAQ#
Dois-je utiliser scope_name ou scope_id ?
Comment obtenir un slot_id ?
Le product_url est-il toujours obligatoire pour la recommandation ?
Ai-je besoin de mettre en place le tracking ?
Qu'est-ce qu'une intégration hybride ?
Qu'est-ce qu'un store_code et quand l'utiliser ?
Glossary#
Capacité permettant de construire des expériences de navigation catalogue comme des pages liste produits (PLP / Page catégorie / Page marque, etc.) à partir d'un contexte de navigation transmis dans les données alimentant Sensefuelscope_name correspond à l'attribut product_type
scope_id correspond Ă l'attribut scope_id
Recherche appliquée aux contenus éditoriaux indexés (guides, recettes, FAQ, articles, blog, etc.).
Dimension de filtrage disponible dans une réponse Discovery.- marque
- couleur
- taille
- prix
- matière
Critère utilisé pour restreindre les résultats d'une recherche (Search) ou d'un listing (Browse).
Version contextualisée d'un produit.Une Offer est définie par :Include
Â
Paramètre permettant de demander des fonctionnalités ou enrichissements supplémentaires dans les réponses Discovery.filters
suggestions
references
spotlights
showcases
scopes
universes
