> ## 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 API

Returns a list of relevant Items for a user search query.
Personalization can be achieved by providing a `user_id` or `session_id`.
This also allows for model relevance improvements through event feedback.

## Endpoint

```
POST /v1/search
```

## Request Body

| Field        | Type    | Required | Description                                                                                                                                                     |
| :----------- | :------ | :------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `query`      | String  | Yes      | The user's search query text. Example: 'workshop desk'                                                                                                          |
| `user_id`    | String  | No       | Unique identifier for the user performing the search.                                                                                                           |
| `session_id` | String  | No       | Unique identifier for the user's current session.                                                                                                               |
| `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       | Maximum number of search results to return. Defaults to 50.                                                                                                     |

## Example Request

<CodeBlock title="POST /search Request Example">
  ```json Example Body theme={null}
  {
    "query": "workshop desk",
    "limit": 10
  }
  ```
</CodeBlock>

## Response Body

Returns a JSON object containing the search results.

| Field   | Type  | Description                                                    |
| :------ | :---- | :------------------------------------------------------------- |
| `items` | Array | An array of item IDs. Example: `["ST678VG","QW1234","EC5792"]` |

### Hit Object (within `items` array if scores are requested, otherwise just item IDs)

Each object in the `items` array is an ItemScore object. The provided example shows a simple list of ItemScores.

| Field      | Type   | Description                                                                             |
| :--------- | :----- | :-------------------------------------------------------------------------------------- |
| `item_id`  | String | The unique identifier of the result item.                                               |
| `score`    | Float  | The search relevance/ranking score assigned by the model (if scores are returned).      |
| `metadata` | Object | Optional: Additional item metadata (e.g., `title`, `description`, `price`, `imageUrl`). |

<CodeBlock title="POST /search Response Example (ItemResponse)">
  ```json Example Response theme={null}
  {
    "items": [
      {"id": "ST678VG", "score": 0.95},
      {"id": "QW1234", "score": 0.87},
      {"id": "EC5792", "score": 0.78}
    ]
  }
  ```
</CodeBlock>

## Responses

* **`200 OK`**: Successful Response (`ItemResponse`)
* **`422 Validation Error`**: (`HTTPValidationError`)
* **`401 Unauthorized`**: Invalid or missing API key.
* **`429 Too Many Requests`**: Rate limit exceeded.
* **`5xx Server Error`**: An internal error occurred.