Introduction#
What is Unified Discovery API?#
Unified Discovery API is Sensefuel's API for building intelligent product discovery experiences across e-commerce channels.It provides a single interface for:Catalog Browse / Faceted Navigation
Powered by Sensefuel's AI engine, Unified Discovery API combines real-time behavioral signals, catalog data, and business rules to deliver highly relevant and hyper-personalized experiences throughout the customer journey.Whether a user is searching for a product, browsing a category page, or looking for recommendations on a product detail page, Unified Discovery API adapts results to maximize relevance, engagement, and conversion.Why Unified Discovery API?#
Unified Discovery API 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
This unified approach allows front-end applications to build rich discovery experiences while reducing implementation complexity.Main Use Cases#
Unified 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
By combining these signals, Sensefuel continuously learns and adapts the experience delivered to each user.Before You Start#
Before integrating Unified Discovery API, we recommend becoming familiar with the following concepts:Search and Browse Features
These concepts are covered in the next sections of this documentation and form the foundation of every Unified Discovery API integration.Getting Started#
Authentication#
All Unified Discovery API endpoints are protected using API Key authentication.
To authenticate your requests, include your API key in the X-API-KEY header.Every request to Unified Discovery API 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 Unified 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 Unified Discovery API.Sensefuel 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 Sensefuel 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#
Unified 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, Sensefuel 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
Sensefuel uses the session to understand the user's immediate intent and react to actions performed during the current visit.
As events are received, Unified Discovery API continuously updates personalization in real time.Session should expires 30 minutes after the browser is closed or inactivity.
When using Unified Discovery API, the session identifier is transmitted through the X-Session-Id header.Segments#
Segments provide additional business context that can be used to tailor Discovery experiences.Unlike behavioral signals such as user_id or session_id, segments are business-defined context configured by your Sensefuel Customer Success Manager (CSM) in the platform to match your specific predefined use cases.Common use cases include:B2B / B2C differentiation
Custom business audiences
Business teams can use these segments within the Sensefuel platform to target specific configurations. When a Unified Discovery API request contains the matching segment, it returns the elements associated with those targeted configurations, such as recommendation, showcases, etc.Key Takeaways#
Unified Discovery API 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, Unified Discovery API 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. Unified Discovery API automatically determines which configuration should be applied for the current context.Tracking & Learning#
Behavioral tracking is a fundamental part of every Unified Discovery API 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 Unified 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 Unified 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#
Filters & Sorting#
Filters serve two complementary purposes in the Unified Discovery API:1.
Retrieving the filters configured by business users in the Sensefuel platform.
2.
Restricting a result set by applying filter conditions to catalog attributes.
By including filters in the include parameter, the API returns the filters configured by your business teams. These filters are typically used to build faceted navigation in search and browse experiences, allowing users to refine results through filter selections.The returned filters reflect the merchandising and navigation strategy defined in the platform and may vary depending on the query, listing context, and current result set.Filtering, however, is not limited to the attributes returned in the filters section. Any indexed catalog attribute can be used as a filter when querying the API.This makes filters useful not only for user-driven interactions, but also for business-driven use cases such as:Pre-filtered search experiences
Campaign-specific experiences
Custom product selections
In other words, thefiltersinclusion provides the list of filters that should typically be exposed to users, while the filtering mechanism itself can be applied to any indexed attribute available in the catalog.
Filtering Logic#
Values within the same filter are evaluated using OR logic, while different filters are combined using AND logic.
Example:brand = Nike OR Adidas
AND
color = Black
AND
price ⤠150Supported Filter Types#
Depending on the attribute type, filters can be applied as:Refer to the endpoint reference for the supported syntax and examples for each filter type.Sorting#
By default, the Unified Discovery API orders results according to Sensefuel's relevance model.Results are first ranked using the relevance indicator (pr) and then by their relevance score (score) so that the most relevant products for the current user and context are displayed first.This default ranking can be overridden using the sort and order query parameters.The list of available sorting attributes depends on the catalog configuration and the data available in the index.Typical examples include:Custom business attributes
Relevance#
Sensefuel continuously evaluates the relevance of products and discovery elements in order to deliver the most meaningful experience for each user.Throughout the Unified Discovery API, several objects may expose relevance-related metrics such as score and pr. These metrics are used to rank and prioritize products, filters, scopes, universes, autocomplete suggestions, and merchandising assets according to the current context.Hyper-Personalized RelevanceSensefuel leverages multiple signals to determine relevance.
Depending on the available data and project configuration, relevance may take into account:The user's navigation context
The current scope or category
Product performance signals
Business merchandising rules
Real time individual user affinity signals
As a result, two users may receive different rankings for the same query depending on their context and interactions.Relevance Indicators (pr & score)Several objects returned by the Discovery API may include a pr (relevance) indicator.
This field provides a relevance hint that can be leveraged by client applications to optimize the user experience and decide how prominently an item should be displayed.| Value | Meaning |
|---|
0 | Relevant |
1 | Less relevant |
The pr indicator represents the first level of relevance evaluation.Items marked with pr = 0 should be considered relevant to the current user and context, while items marked with pr = 1 are considered significantly less relevant.
The relevance evaluation is dynamic and highly personalized. An item considered relevant for one user, context, or moment may be considered less relevant for another user or context.When multiple items share the same pr value, the score attribute provides a second level of ranking. Higher scores indicate a stronger relevance signal.By default, the Unified Discovery API orders results according to this relevance model:This ordering is automatically applied unless explicitly overridden using the sort query parameter.Client applications may leverage the pr indicator to:Prioritize highly relevant items
Display low-relevance items behind a "Show more" interaction
Apply different visual treatments
Reduce visual noise in search and browse experiences
The pr field should be considered as a UX/UI guidance signal rather than a filtering criterion. Front-end applications are free to interpret and leverage it according to their own user experience strategy.Autocomplete & Suggestions#
The Discovery API exposes two complementary mechanisms to assist users during their search journey:The dedicated suggestions endpoint, designed to retrieve suggestions independently from a search request.
The include=autocomplete parameter, designed to enrich a search response with query completion proposals.
Suggestions Endpoint#
The suggestions endpoint can be called with or without a query.Without a query, it can be used to power discovery experiences such as:Dedicated discovery modules
When a query is provided, the endpoint returns related suggestions that can help users adapt their search intent for discovery experience such as: When used with the dedicated suggestions endpoint, the product_url parameter allows the API to generate suggestions based on a specific product context.This is particularly useful on Product Detail Pages (PDPs), where suggestions can be tailored to the viewed product and help users discover related search intents, products, scopes, or merchandising content.By combining the current product context with Sensefuel's relevance and personalization signals, the API returns suggestions that are more meaningful than generic query-based suggestions.
Depending on the requested includes, the endpoint can also return:Autocomplete via Search products Endpoint#
To retrieve autocomplete proposals alongside search results, include autocomplete in the search request.When requested, the API returns autocomplete suggestions within the same response as the search results.This mechanism is primarily intended for instant search experiences, allowing users to receive both matching products and query completion proposals while typing without requiring an additional API call.Because autocomplete and suggestions depend on the current query, catalog configuration, and platform optimization, returned values may evolve over time as the catalog evolves.References#
References allow users to search products using unique identifiers rather than natural language queries.Typical examples include:The Discovery API can identify and return products matching these references, providing a fast and precise way to access a specific item.To retrieve reference matches alongside search results, include references in the request.Reference search is fully configurable. Any attribute sent to Sensefuel can be designated as a reference field and used for reference-based matching. This makes the feature suitable for many business-specific use cases.
Because reference fields are configured at the catalog level, the set of attributes considered as references may vary from one implementation to another.Spotlights#
Spotlights are e-merchandising assets that help guide users toward specific product selections or business objectives.Spotlights are configured by business users in the Sensefuel platform using criteria based on catalog attributes or static selection (Select). A Spotlight is dynamically returned when the current result set contains products associated to it.For example, a Spotlight could be configured in the platform with the condition:When a user searches for sneakers, if Nike products are present in the result set, the corresponding Spotlight may be returned by the API.To retrieve Spotlights alongside search results, include spotlights in the request.Unlike filters, Spotlights are designed to provide a richer and more engaging experience. They can include:Background Images or hexadecimal color
Other meta data for display purposes
A Spotlight can therefore be viewed as a visual representation of a merchandising rule.
When a user selects a Spotlight, its technical identifier can be passed back to the API to apply the selection associated with that Spotlight.The API then applies the criteria associated with the selected Spotlight and returns the corresponding products.This approach allows front-end applications to leverage merchandising rules defined in the platform without needing to know or reproduce the underlying filtering conditions.Because Spotlights are dynamically evaluated against the current result set, the content returned by the API may vary depending on the search query, active filters, listing context, and merchandising rules configured by business teams.Showcases#
Showcases allow business users to promote a curated selection of products at the top of search results or product listing pages, similarly to an "end cap" or "end aisle" in a physical store.To retrieve showcases alongside search or listing results, include showcases in the include parameter of the request.When requested, the API returns the showcase configured for the current search or navigation context.Showcases are configured by business users in the Sensefuel platform and can be triggered by:One or multiple search queries
One or multiple product listing pages (PLPs) through the product_type or scope_id
Specific segments, stores, or contextual conditions
The products displayed in a showcase can be selected through:Manual product id selection
Product selections managed through Sensefuel merchandising tools (Select)
Only products that are present in the current result set can be displayed in a showcase.Typical use cases include:Strategic product selections
Display Styles#
A showcase can be configured with different presentation styles:Neutral: seamlessly integrated into the product grid without any visual distinction.
templatetype : MANUAL_RANKING
Sponsored: displayed with dedicated styling, including custom text and background color.
templatetype : FULL_PRODUCT
Visual: displayed with a visual asset, replacing the first product tile of the showcase.
templatetype : BANNER
Search and Navigation Contexts#
Showcases can be activated in different contexts:Search context, based on one or more keywords.
Navigation context, based on a product_type or category/PLP id scope_id.
This allows merchandising teams to tailor product visibility according to the user's intent and navigation journey.Because showcases are managed directly in the Sensefuel platform, displayed content may vary over time depending on merchandising strategies, campaigns, and business rules.Scopes & Universes#
Scopes & Universes are navigation dimensions that allow users to focus on a specific subset of the catalog.They can be used both to filter results and to build navigation experiences such as Product Listing Pages (PLPs), Brand pages, Landing pages, Promotion pages, etc.Filtering with Scopes#
A scope can be applied to a search or listing request using the scope_name and/or scope_id parameters.The scope_name parameter identifies the catalog attribute used as the navigation dimension. This corresponds to the product_type attribute.Depending on the implementation, a scope may represent the complete hierarchy or only a specific level of that hierarchy.In the previous example, it is possible to request a product listing for:
Women or Women > Shoesor Women > Shoes > Sneakersallowing users to navigate progressively through the catalog hierarchy while keeping a consistent search and browse experience.Scope IDs#
A scope_id is a technical identifier associated with a navigation context.It is typically provided in the catalog feed and is primarily used to retrieve products belonging to a specific Product Listing Page (PLP).A product can belong to multiple categories and therefore be associated with multiple scope_id.For this reason, scope_id should be considered as a category identifier rather than a product classification attribute.Retrieving Available Scopes#
To retrieve the scopes available for the current search or listing context, include scopes in the request.The API returns the scope values associated with the products contained in the current result set.These scopes are typically displayed to users as contextual navigation visual filters, allowing them to quickly focus on a more specific subset of products.Universes#
Universes represent the first level of the hierarchy associated with the attribute product_type.For example, given the following product types:
Garden > Construction Wood
Garden > Garden Furniture
Garden > GreenhousesSensefuel automatically derives the following universe:
GardenUniverses are therefore generated by Sensefuel from the scope hierarchy and do not require a dedicated attribute in the catalog feed.To retrieve available universes for the current search or listing context, include universes in the request.{
"id": "Garden",
"count": 548,
"score": 80.69,
"pr": 0
}
Universes can be used to help users navigate across major catalog domains before refining their navigation with more specific scopes.Because universes are derived from the products present in the current result set, the values returned by the API may vary depending on the query, active filters, and listing context.Shortcuts#
Shortcuts provide quick access to predefined destinations associated with a search intent.They are configured by business users in the Sensefuel platform and are exposed through the dedicated shortcuts endpoint.When a query matches one of the configured shortcut keywords, the API returns a shortcut along with one or more associated destinations.Destinations#
A shortcut can contain one or more destinations.Each destination typically references a page or navigation entry point within the website or application.{
"id": "5600",
"url": "https://www.example.com/faq.html",
"basicDisplay": {
"label": "FAQ"
}
}
Typical destination types include:FAQ or Special Pages within the website
Product Listing Pages (PLPs)
Highlighted Shortcut#
A shortcut can optionally expose a highlighted object that provides dedicated display instructions for the client application.{
"highlighted": {
"use": true,
"title": "FAQ",
"description": "Consult our help page",
"iconUrl": "https://example.com/themes/img/logos/logo_red.svg",
"color": "#000000",
"backgroundColor": "#F1F1F1",
"size": "L",
"horizontal": {
"hideIcon": false,
"hideDescription": true
}
}
}
When use is set to true, the shortcut can be displayed using a dedicated visual presentation defined by business users in the Sensefuel platform.The highlighted configuration may include:Text and background colors
This metadata allows clients to render shortcuts as visually prominent navigation elements within autocomplete, search entry points, or discovery experiences.The interpretation of these properties is left to the client implementation.Recommendations#
Recommendations help users discover relevant products beyond their current search or navigation context.Unlike search, which responds to an explicit user intent, recommendations are proactively generated by the Discovery Engine based on product affinity, catalog relationships, business rules, and user behavior.The recommend endpoint can be used throughout the customer journey to surface products that are likely to be of interest to the user.Typical use cases include:Product detail pages ("You may also like")
Home page recommendations
Personalized product discovery
Recommendations are dynamically generated according to the current context and may leverage information such as:Business merchandising rules
Depending on the recommendation strategy configured in the Sensefuel platform, the API may return products related to a specific product, a user, or another business context.Because recommendations are personalized and context-aware, the returned products may vary from one user to another and evolve over time.