Skip to main content
Re-rank a list of items given a query. This can be used to refine results from an initial search or another source.

​
Endpoint

POST /v1/search/rerank

​
Request Body (SearchRerankRequest)

FieldTypeRequiredDescription
queryStringYesThe search query. Example: ‘I need a gift for my dad’s birthday’.
item_idsArrayYesA list of item IDs to re-rank. Example: ["ST678VG","QW1234","EC5792","FC7890"]
model_idStringNoThe name of the model to use. Example: furniture_v2. Default is default.
user_idStringNoUnique identifier for the user.
session_idStringNoUnique identifier for the user’s current session.
search_contextObjectNoA 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_metadataArray (Object)NoA 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.
eventsArrayNoA list of events associated with the request. Example: [{"timestamp":"2024-06-14T10:00:00Z","type":"search","description":"User searched for workshop desk"}]
limitIntegerNoThe 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
}