Search API 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 Responses HTTP Code Description Schema 200 OK 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 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 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 Responses HTTP Code Description Schema 200 OK 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 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 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 > array num_lists required Number of lists that were requested. integer perfect_match optional Exact match for the query, if available. 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 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 Completion Payload returned by the completions endpoints. Name Description Schema completions required List of suggested terms. < Item > array request_id required Identifier of the completion request. integer user_group optional Experiment group the user belongs to. string