---
title: API Overview and Integration Guide to Search Personalization
description: This guide explains how to configure, activate, and maintain search personalization models using the Raptor API. It covers model versioning, embedding management, API endpoints, and authentication.
---
[Skip to content](https://content.raptorservices.com/help-center/search-personalization-api-overview-and-integration-guide#main-content)
![raptor-qntm-logo\_horizontal\_gradient.png\]](https://content.raptorservices.com/hs-fs/hubfs/raptor-qntm-logo_horizontal_gradient.png?height=40&name=raptor-qntm-logo_horizontal_gradient.png)
Open main navigation
Close main navigation
- [Go to raptorservices.com](https://raptorservices.com/)
[Go to raptorservices.com](https://raptorservices.com/)
Hello. How can we help you?
- There are no suggestions because the search field is empty.
1. [Help Center](https://content.raptorservices.com/help-center?hsLang=en)
2. [Site Search](https://content.raptorservices.com/help-center/site-search?hsLang=en)
3. [Search Ranking & Recommendations](https://content.raptorservices.com/help-center/site-search?hsLang=en#search-ranking-recommendations)
# API Overview and Integration Guide to Search Personalization
#### **Introduction**
This guide explains how to configure, activate, and maintain search personalization models using the Raptor API. It covers model versioning, embedding management, API endpoints, and authentication.
The **Search Personalization API** (`search-personalization-api.raptorsmartadvisor.com`) enables personalized search experiences by leveraging machine learning models trained on customer-specific data. These models continuously learn and adapt to ensure relevant and dynamic search results.
#### **How It Works**
Models are configured per customer account and continuously retrained on the latest data
1. A file containing **item embeddings**, and
2. An API that generates **user embeddings** based on each user’s most recent history.
At query time, the search engine compares the **user embedding** to personalize results by performing vector-similarity comparison between the **user embedding** and the **item embeddings** loaded into the search index.
### **Key Principles**
- Raptor continuously collects data and produces new model versions. It is essential that **item embeddings** and **user embeddings** always come from the same model version. Each new version includes a new item-embedding file, which must be downloaded and loaded into the search index. After loading these embeddings, you must instruct the Search Personalization API to use the same version for generating user embeddings.
**⚠️ Important:** Item embeddings and user embeddings must always come from the **same model version**.
- Its recommended always **upgrading to the latest version,** as new versions include newly added products and are trained on the most recent data. (Check the `latestVersion` endpoint regularly (eg. daily) to ensure you’re using the newest model.)
**🔍 Note:** Only one version of each model can be active at a time.
- The Search Personalization API will always return embeddings for the currently **active version**. To upgrade, load the item embeddings for the new version into your search index and then switch the active version in the Search Personalization API. (From that point on, the API will generate embeddings from the new model version.)
- The recommended flow is to pre-fetch **user embeddings** before users perform searches, ensuring embeddings are available instantly at query time without adding latency.
---
#### **API Endpoints**
Explore all endpoints in the [swagger](https://search-personalization-api.raptorsmartadvisor.com/swagger/index.html)
### **Model Management**
- `/{CustomerId}/models`Lists all configured models.
- `/{CustomerId}/model/{ModelId}/versions`
Lists all available versions and shows the active one.
- `/{CustomerId}/model/{ModelId}/latestVersion`
Returns the newest version.
### **Item Embeddings**
- `/{CustomerId}/model/{ModelId}/itemEmbeddings/{ModelVersion}`
Downloads item embeddings for a specific model/version.
Once the item embeddings have been loaded into your search index, switch the active version in the Search Personalization API using:
### **Activation**
- `/{CustomerId}/model/{ModelId}/activate/{ModelVersion}`
Activates a new model version (takes ~30 sec). Deactivates the old version automatically.
- `/{CustomerId}/model/{ModelId}/deactivate`
Deactivates the currently active version.
After activation, retrieve user embeddings via the **Raptor Recommendation Engine** module `GetUserEmbeddings` (documented in the Control Panel).
---
#### **Restrictions**
- Maximum **2 models** can be active in parallel.
- Only **one version per model** can be active at a time.
---
#### **Authentication**
All API calls require **Bearer Token** authentication in the header
The flow involves calling \*login.raptorsmartadvisor.com\* for a bearer token then using it in subsequent calls. Tokens expire after 300 seconds so re-authentication is required for longer running flows.
### **Token Flow**
1. Request token from `login.raptorsmartadvisor.com`.
2. Use **token** in subsequent API calls.
3. Tokens expire after **300 seconds**; re-authentication is required for long-running processes.
**💡 Example:** Use the following request to obtain a bearer token for API calls. Tokens expire after 300 seconds.
```
curl --location 'https://login.raptorsmartadvisor.com/auth/realms/raptor/protocol/openid-connect/token' \--request POST \--header 'Content-Type: application/x-www-form-urlencoded' \--data-urlencode 'client_id=search-personalization-external-api-[CUSTOMERID]' \--data-urlencode 'client_secret=...' \--data-urlencode 'grant_type=client_credentials'
```
Use the token:
```
curl --location 'https://search-personalization-api.raptorsmartadvisor.com/[CUSTOMERID]/models' \--request GET \--header 'Authorization: bearer [token here]'
```
**🔍 Note:** Guidelines for removing outdated model versions will be provided soon.
- [Welcome to Raptor](https://content.raptorservices.com/help-center/welcome-to-raptor?hsLang=en#main-content)
- [Introduction](https://content.raptorservices.com/help-center/welcome-to-raptor?hsLang=en#introduction)
- [Analytics & Insights](https://content.raptorservices.com/help-center/analytics-insights?hsLang=en)
- [Data Management](https://content.raptorservices.com/help-center/data-management?hsLang=en#main-content)
- [Implementing Tracking](https://content.raptorservices.com/help-center/data-management?hsLang=en#implementing-tracking)
- [Implementing Raptor Recommendation](https://content.raptorservices.com/help-center/data-management?hsLang=en#implementing-raptor-recommendation)
- [Email Marketing Integration](https://content.raptorservices.com/help-center/data-management?hsLang=en#email-marketing-integration)
- [The Data Manager](https://content.raptorservices.com/help-center/data-management?hsLang=en#the-data-manager)
- [Streaming API](https://content.raptorservices.com/help-center/data-management?hsLang=en#streaming-api)
- [Destinations](https://content.raptorservices.com/help-center/data-management?hsLang=en#destinations)
- [Customer Data Platform](https://content.raptorservices.com/help-center/customer-data-platform?hsLang=en#main-content)
- [Introduction](https://content.raptorservices.com/help-center/customer-data-platform?hsLang=en#introduction)
- [Profile Unification](https://content.raptorservices.com/help-center/customer-data-platform?hsLang=en#profile-unification)
- [Audience Builder](https://content.raptorservices.com/help-center/customer-data-platform?hsLang=en#audience-builder)
- [Audience Insights](https://content.raptorservices.com/help-center/customer-data-platform?hsLang=en#audience-insights)
- [Calculated Attributes](https://content.raptorservices.com/help-center/customer-data-platform?hsLang=en#calculated-attributes)
- [Activations](https://content.raptorservices.com/help-center/customer-data-platform?hsLang=en#activations)
- [Single Customer View](https://content.raptorservices.com/help-center/customer-data-platform?hsLang=en#single-customer-view)
- [CDP Export API](https://content.raptorservices.com/help-center/customer-data-platform?hsLang=en#cdp-export-api)
- [Website Recommendations](https://content.raptorservices.com/help-center/website-recommendations?hsLang=en#main-content)
- [Introduction](https://content.raptorservices.com/help-center/website-recommendations?hsLang=en#introduction)
- [Recommendation Strategies](https://content.raptorservices.com/help-center/website-recommendations?hsLang=en#recommendation-strategies)
- [Feeds](https://content.raptorservices.com/help-center/website-recommendations?hsLang=en#feeds)
- [Tuning Parameters](https://content.raptorservices.com/help-center/website-recommendations?hsLang=en#tuning-parameters)
- [Working with the Raptor API](https://content.raptorservices.com/help-center/website-recommendations?hsLang=en#working-with-the-raptor-api)
- [Mail Recommendations](https://content.raptorservices.com/help-center/mail-recommendations?hsLang=en)
- [E-mail Triggers](https://content.raptorservices.com/help-center/e-mail-triggers?hsLang=en#main-content)
- [Get started](https://content.raptorservices.com/help-center/e-mail-triggers?hsLang=en#get-started)
- [E-mail Trigger Documentation](https://content.raptorservices.com/help-center/e-mail-triggers?hsLang=en#e-mail-trigger-documentation)
- [E-mail trigger integrations](https://content.raptorservices.com/help-center/e-mail-triggers?hsLang=en#e-mail-trigger-integrations)
- [Site Search](https://content.raptorservices.com/help-center/site-search?hsLang=en#main-content)
- [Search Tracking](https://content.raptorservices.com/help-center/site-search?hsLang=en#search-tracking)
- [Introduction](https://content.raptorservices.com/help-center/site-search?hsLang=en#introduction)
- [Implementing Site Search](https://content.raptorservices.com/help-center/site-search?hsLang=en#implementing-site-search)
- [Search Ranking & Recommendations](https://content.raptorservices.com/help-center/site-search?hsLang=en#search-ranking-recommendations)
- [Reporting](https://content.raptorservices.com/help-center/site-search?hsLang=en#reporting)
- [Merchandising](https://content.raptorservices.com/help-center/merchandising?hsLang=en#main-content)
- [Introduction to Merchandising](https://content.raptorservices.com/help-center/merchandising?hsLang=en#introduction-to-merchandising)
- [Boosted Campaigns](https://content.raptorservices.com/help-center/merchandising?hsLang=en#boosted-campaigns)
- [Customized Feeds](https://content.raptorservices.com/help-center/merchandising?hsLang=en#customized-feeds)
- [AI Models](https://content.raptorservices.com/help-center/ai-models?hsLang=en#main-content)
- [Customer Lifetime Value](https://content.raptorservices.com/help-center/ai-models?hsLang=en#customer-lifetime-value)
- [Administration](https://content.raptorservices.com/help-center/administration?hsLang=en#main-content)
- [Trust Center](https://content.raptorservices.com/help-center/administration?hsLang=en#trust-center)
- [User Management](https://content.raptorservices.com/help-center/administration?hsLang=en#user-management)
- [Operational Insights](https://content.raptorservices.com/help-center/administration?hsLang=en#operational-insights)
- [Data Retention](https://content.raptorservices.com/help-center/administration?hsLang=en#data-retention)
[](https://www.raptorservices.com/)
raptorsmartadvisor.com Help Center
Copyright © 2026, Raptor Services A/S