> ## Documentation Index
> Fetch the complete documentation index at: https://client-integrations-api-dev.sequen.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Search Rerank API

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`)

| 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

<CodeBlock title="POST /search/rerank Request Example (SearchRerankRequest)">
  ```json Example Body theme={null}
  {
    "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
  }
  ```
</CodeBlock>