Endpoint
POST /v1/search/rerank
Request Body (SearchRerankRequest)
| Field | Type | Required | Description |
|---|---|---|---|
query | String | Yes | The search query. Example: ‘I need a gift for my dad’s birthday’. |
item_ids | Array | Yes | A list of item IDs to re-rank. Example: ["ST678VG","QW1234","EC5792","FC7890"] |
model_id | String | No | The name of the model to use. Example: furniture_v2. Default is default. |
user_id | String | No | Unique identifier for the user. |
session_id | String | No | Unique identifier for the user’s current session. |
search_context | Object | No | A flexible object for additional search context not captured by user_id. Allows for a custom schema (e.g., locale, device, geo, search filters applied, site section). |
item_retrieval_metadata | Array (Object) | No | A flexible array of objects for additional metadata on candidate items, adaptable per customer. Each object must contain an item_id; other fields (e.g., retrieval_score, rank) are optional and customizable. |
events | Array | No | A list of events associated with the request. Example: [{"timestamp":"2024-06-14T10:00:00Z","type":"search","description":"User searched for workshop desk"}] |
limit | Integer | No | The number of items to return. Default is 50. |
Example Request
Example Body
{
"query": "filing cabinet with lock",
"item_ids": ["FC7890", "SC1234", "LS5678"],
"model_id": "furniture_v2",
"session_id": "2f396d29-fb98-44cf-996c-e8c66fc02fbe",
"search_context": {
"locale": "en-US",
"device": "desktop",
"search_filters": ["color:black", "material:metal"]
},
"item_retrieval_metadata": [
{ "item_id": "FC7890", "retrieval_score": 0.85, "rank": 1 },
{ "item_id": "SC1234", "retrieval_score": 0.72, "rank": 5 },
{ "item_id": "LS5678", "retrieval_score": 0.68, "rank": 12 }
],
"events": [
{
"timestamp": "2024-06-14T10:00:00Z",
"type": "search",
"description": "User searched for secure storage"
}
],
"limit": 2
}