# Search API
> Current Froomle documentation ยท [View canonical page](https://docs.froomle.com/froomle-doc-main/v2/api_reference/search/index.html)
Getting search results and completions from the Froomle platform is done through the search API. The search results and completions in the API will only contain items which are stored in the specified environment. In addition to requesting search results and completions, the search API also supports fetching previously computed search results.
## Specifications
### POST /{environment}/searches/requests
#### Description
Request search results scoped to a specific environment.
#### Parameters
| Type | Name | Description | Schema |
| --- | --- | --- | --- |
| **Path** | **environment**
_required_ | The environment for which the request is made. | string |
| **Body** | **body**
_required_ | Search payload. | [SearchRequest](https://docs.froomle.com/froomle-doc-main/v2/api_reference/search/index.html#_searchrequest) |
#### Responses
| HTTP Code | Description | Schema |
| --- | --- | --- |
| **200** | OK | [SearchResults](https://docs.froomle.com/froomle-doc-main/v2/api_reference/search/index.html#_searchresults) |
#### Consumes
- `application/json`
#### Produces
- `application/json`
* * *
### GET /{environment}/searches/lists
#### Description
Query cached search results from a previously computed list.
#### Parameters
| Type | Name | Description | Schema |
| --- | --- | --- | --- |
| **Path** | **environment**
_required_ | The environment for which the list request is made. | string |
| **Query** | **list\_key**
_required_ | Identifier of the cached list returned by an earlier search. | string |
| **Query** | **offset**
_required_ | Rank of the first item to include (1-based). | integer |
| **Query** | **limit**
_required_ | Number of items to return. | integer |
#### Responses
| HTTP Code | Description | Schema |
| --- | --- | --- |
| **200** | OK | [SearchResults](https://docs.froomle.com/froomle-doc-main/v2/api_reference/search/index.html#_searchresults) |
| **404** | List key not found or expired. | No Content |
#### Produces
- `application/json`
* * *
### GET /{environment}/searches/completions
#### Description
Request completions for a partially entered query.
#### Parameters
| Type | Name | Description | Schema |
| --- | --- | --- | --- |
| **Path** | **environment**
_required_ | The environment for which the request is made. | string |
| **Query** | **q**
_required_ | The query term to complete. | string |
| **Query** | **user\_id**
_optional_ | Identifier of the logged-in user. | string |
| **Query** | **device\_id**
_optional_ | Identifier for an anonymous user or device. | string |
| **Query** | **request\_id**
_optional_ | Client-supplied identifier for correlating requests. | string |
| **Query** | **page\_type**
_optional_ | Contextual page type for the query. | string |
#### Responses
| HTTP Code | Description | Schema |
| --- | --- | --- |
| **200** | OK | [Completion](https://docs.froomle.com/froomle-doc-main/v2/api_reference/search/index.html#_completion) |
#### Produces
- `application/json`
* * *
### POST /{environment}/searches/completions
#### Description
Request completions with the advanced payload that supports multi-environment setups.
#### Parameters
| Type | Name | Description | Schema |
| --- | --- | --- | --- |
| **Path** | **environment**
_required_ | The environment for which the request is made. | string |
| **Body** | **body**
_required_ | Completion payload. | [CompletionRequest](https://docs.froomle.com/froomle-doc-main/v2/api_reference/search/index.html#_completionrequest) |
#### Responses
| HTTP Code | Description | Schema |
| --- | --- | --- |
| **200** | OK | [Completion](https://docs.froomle.com/froomle-doc-main/v2/api_reference/search/index.html#_completion) |
#### Consumes
- `application/json`
#### Produces
- `application/json`
* * *
## Definitions
### Item
One content item returned by the Search API.
| Name | Description | Schema |
| --- | --- | --- |
| **information\_field**
_required_ | Optional metadata field configured per customer. | string |
| **item\_id**
_required_ | Identifier of the item in your catalog. | string |
| **type**
_required_ | Document type of the returned object. | string |
* * *
### SearchRequest
Specification of a search request body.
| Name | Description | Schema |
| --- | --- | --- |
| **autocorrect**
_optional_ | Whether the query should be autocorrected (default: `true`). | boolean |
| **filter\_by**
_optional_ | Filters that limit which items can appear. | [Filter](https://docs.froomle.com/froomle-doc-main/v2/api_reference/search/index.html#_search_filter) |
| **group\_by**
_optional_ | Fields used to split results into multiple lists (default: `[]`). | < string > array |
| **limit**
_optional_ | Number of items returned per list (default: `4`). | integer |
| **list\_size**
_optional_ | Number of items cached per list for later retrieval (default: `100`). | integer |
| **num\_lists**
_optional_ | Number of lists requested (default: `4`). | integer |
| **q**
_required_ | The search query typed by the user. | string |
| **page\_type**
_required_ | Page or surface for which the request is made. | string |
| **channel**
_optional_ | Channel identifier (e.g., web, iOS, Android). | string |
| **user\_id**
_optional_ | Logged-in user identifier. | string |
| **device\_id**
_required_ | Identifier for anonymous users or devices. | string |
| **histories**
_optional_ | Behavioral histories that improve personalization. | [Histories](https://docs.froomle.com/froomle-doc-main/v2/api_reference/search/index.html#_search_histories) |
* * *
### SearchResults
Response returned by the search endpoints.
| Name | Description | Schema |
| --- | --- | --- |
| **auto\_suggest**
_optional_ | Alternative query if autocorrect was triggered. | string |
| **lists**
_required_ | Grouped search results. | < [List](https://docs.froomle.com/froomle-doc-main/v2/api_reference/search/index.html#_search_list) > array |
| **num\_lists**
_required_ | Number of lists that were requested. | integer |
| **perfect\_match**
_optional_ | Exact match for the query, if available. | [Item](https://docs.froomle.com/froomle-doc-main/v2/api_reference/search/index.html#_search_item) |
| **request\_id**
_required_ | Identifier of the request to log alongside events. | string |
| **user\_group**
_optional_ | Experiment group the user belongs to. | string |
* * *
### CompletionRequest
Body accepted by the advanced completions endpoint.
| Name | Description | Schema |
| --- | --- | --- |
| **fuzziness**
_optional_ | Maximum edit distance when matching queries (default: `0`). | integer |
| **filter\_by**
_optional_ | Filters applied before generating completions. | [Filter](https://docs.froomle.com/froomle-doc-main/v2/api_reference/search/index.html#_search_filter) |
| **q**
_optional_ | Partial query string. | string |
| **user\_id**
_optional_ | User identifier. | string |
| **device\_id**
_optional_ | Device identifier. | string |
| **histories**
_optional_ | Interaction histories used to personalize results. | [Histories](https://docs.froomle.com/froomle-doc-main/v2/api_reference/search/index.html#_search_histories) |
* * *
### Completion
Payload returned by the completions endpoints.
| Name | Description | Schema |
| --- | --- | --- |
| **completions**
_required_ | List of suggested terms. | < [Item](https://docs.froomle.com/froomle-doc-main/v2/api_reference/search/index.html#_search_item) > array |
| **request\_id**
_required_ | Identifier of the completion request. | integer |
| **user\_group**
_optional_ | Experiment group the user belongs to. | string |