# POST /{environment}/searches/requests

> Current Froomle documentation · [View canonical page](https://docs.froomle.com/froomle-doc-main/v2/api_reference/search/operations/search_with_env.html)

<a id="_description"></a>

## Description

Request search results scoped to a specific environment.

<a id="_parameters"></a>

## Parameters

| Type | Name | Description | Schema |
| --- | --- | --- | --- |
| **Path** | **environment**<br>_required_ | The environment for which the request is made. | string |
| **Body** | **body**<br>_required_ | Search payload. | [SearchRequest](https://docs.froomle.com/froomle-doc-main/v2/api_reference/search/operations/search_with_env.html#_searchrequest) |

<a id="_responses"></a>

## Responses

| HTTP Code | Description | Schema |
| --- | --- | --- |
| **200** | OK | [SearchResults](https://docs.froomle.com/froomle-doc-main/v2/api_reference/search/operations/search_with_env.html#_searchresults) |

<a id="_consumes"></a>

## Consumes

-   `application/json`
    

<a id="_produces"></a>

## Produces

-   `application/json`
    

* * *

<a id="_search_item"></a>

### Item

One content item returned by the Search API.

| Name | Description | Schema |
| --- | --- | --- |
| **information\_field**<br>_required_ | Optional metadata field configured per customer. | string |
| **item\_id**<br>_required_ | Identifier of the item in your catalog. | string |
| **type**<br>_required_ | Document type of the returned object. | string |

<a id="_search_list"></a>

### List

Represents a grouped subset of search results.

| Name | Description | Schema |
| --- | --- | --- |
| **grouped\_by**<br>_optional_ | Values of the `group_by` keys shared by every item in the list. | < string > array |
| **items**<br>_optional_ | Items contained in this list. | < [Item](https://docs.froomle.com/froomle-doc-main/v2/api_reference/search/operations/search_with_env.html#_search_item) > array |
| **limit**<br>_optional_ | Number of items returned in this list. | integer |
| **list\_key**<br>_optional_ | Identifier that lets you re-fetch remaining items. | string |
| **list\_name**<br>_optional_ | Server-generated name of the list. | string |
| **list\_size**<br>_optional_ | Total number of cached items for this list. | integer |

<a id="_search_filter"></a>

### Filter

Key-value filters applied to search requests.

| Name | Description | Schema |
| --- | --- | --- |
| **<field>**<br>_optional_ | Field name/value pairs that determine which items are allowed. Configured per customer. | string |

<a id="_search_histories"></a>

### Histories

Map of custom histories that describe past user interactions.

| Name | Description | Schema |
| --- | --- | --- |
| **<history\_name>**<br>_optional_ | Array of recent events used for personalization. | < [HistoryItem](https://docs.froomle.com/froomle-doc-main/v2/api_reference/search/operations/search_with_env.html#_search_historyitem) > array |

<a id="_search_historyitem"></a>

### HistoryItem

Single interaction tuple used inside histories.

| Name | Description | Schema |
| --- | --- | --- |
| **id**<br>_required_ | Identifier of the entity referenced by the event. | string |
| **timestamp**<br>_optional_ | Unix timestamp (seconds). | integer |
| **item\_type**<br>_optional_ | Type of the entity (e.g., item, article, category). | string |
| **reconsumable**<br>_optional_ | Whether the entity can be recommended again. | boolean |

<a id="_searchrequest"></a>

### SearchRequest

Specification of a search request body.

| Name | Description | Schema |
| --- | --- | --- |
| **autocorrect**<br>_optional_ | Whether the query should be autocorrected (default: `true`). | boolean |
| **filter\_by**<br>_optional_ | Filters that limit which items can appear. | [Filter](https://docs.froomle.com/froomle-doc-main/v2/api_reference/search/operations/search_with_env.html#_search_filter) |
| **group\_by**<br>_optional_ | Fields used to split results into multiple lists (default: `[]`). | < string > array |
| **limit**<br>_optional_ | Number of items returned per list (default: `4`). | integer |
| **list\_size**<br>_optional_ | Number of items cached per list for later retrieval (default: `100`). | integer |
| **num\_lists**<br>_optional_ | Number of lists requested (default: `4`). | integer |
| **q**<br>_required_ | The search query typed by the user. | string |
| **page\_type**<br>_required_ | Page or surface for which the request is made. | string |
| **channel**<br>_optional_ | Channel identifier (e.g., web, iOS, Android). | string |
| **user\_id**<br>_optional_ | Logged-in user identifier. | string |
| **device\_id**<br>_required_ | Identifier for anonymous users or devices. | string |
| **histories**<br>_optional_ | Behavioral histories that improve personalization. | [Histories](https://docs.froomle.com/froomle-doc-main/v2/api_reference/search/operations/search_with_env.html#_search_histories) |

<a id="_searchresults"></a>

### SearchResults

Response returned by the search endpoints.

| Name | Description | Schema |
| --- | --- | --- |
| **auto\_suggest**<br>_optional_ | Alternative query if autocorrect was triggered. | string |
| **lists**<br>_required_ | Grouped search results. | < [List](https://docs.froomle.com/froomle-doc-main/v2/api_reference/search/operations/search_with_env.html#_search_list) > array |
| **num\_lists**<br>_required_ | Number of lists that were requested. | integer |
| **perfect\_match**<br>_optional_ | Exact match for the query, if available. | [Item](https://docs.froomle.com/froomle-doc-main/v2/api_reference/search/operations/search_with_env.html#_search_item) |
| **request\_id**<br>_required_ | Identifier of the request to log alongside events. | string |
| **user\_group**<br>_optional_ | Experiment group the user belongs to. | string |