> For the complete documentation index, see [llms.txt](https://docs.abtasty.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.abtasty.com/commerce/search/api/search-api-v0.4.md). # /search API (v0.4) This document outlines the usage of the Search API route, which allows for powerful querying and filtering of datasets. ## Endpoint | Method | URL | | ------ | ----------------------------------------------- | | GET | https\://{identifier}.search.abtasty.com/search | ## Query parameters All request data is sent as URL query parameters. Nested data uses bracket notation. Serialization rule (canonical): * Objects: filters\[field]\[key]=value * Arrays of scalars: repeat the param: filters\[field]\[]=v1\&filters\[field]\[]=v2 * Arrays of objects: index the array:\ filters\[field]\[0]\[operator]=>\&filters\[field]\[0]\[value]=10 | Parameter | Type | Description | Required | Example | | --------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------- | --------------------------------- | | text | string | The search query string. | Yes | "toy" | | filters | object | An object containing key-value pairs for filtering search results. Each key represents a field to filter on. Values can be strings, arrays of strings, or objects for range queries. | No | {"brand": \["lego", "playmobil"]} | | page | integer | The page number of results to retrieve (0-indexed). | No | 0 | | hitsPerPage | integer | The number of results to return per page. | No | 20 | | sort | Array of string | Sorting values sent to Meilisearch to sort the search results. | No | \["price:asc", "name:desc"] | | rankingScoreThreshold | float | A ranking score from 1.0 (perfect match) to 0.0 (no match) indicates relevancy, with higher scores signifying better matches. | No | 0.1 | | semanticRatio | float | semanticRatio balances semantic search results. Higher values bring documents from further in the semantic space into final results. |


No

| 0.3 | ### filters Object Structure The filters object supports different types of filters: * List Filters: For fields where you want to match one or more exact values. * Format: `{"field_name": ["value1", "value2"]}` * Example: `"color": ["red", "blue"]` * Range Filters: For numerical fields where you want to specify a range using operators. * Format: `{"field_name": [{"operator": "operator_type", "value": number}, {"operator": "operator_type", "value": number}]}` * Supported Operators: `">"`, `"<"`, `">="`, `"<="`, `"="` * Example: `"price": [{ "operator": ">", "value": 10 }, { "operator": "<", "value": 20 }]` * Example: `"rating": [{ "operator": ">=", "value": 4 }]` ## Response Body The response body is a JSON object with the following properties: | Property | Type | Description | | ----------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------- | | hits | array of objects | An array of search results, where each object represents a matching item. The structure of each item depends on the dataset. | | facets | object | An object containing aggregated facet information for different fields, useful for building dynamic filtering interfaces. | | totalPages | integer | The total number of available pages based on the hitsPerPage. | | totalHits | integer | The total number of search results matching the query and filters. | | hitsPerPage | integer | The number of results returned per page, as specified in the request or defaulted by the API. | | page | integer | The current page number of the results. | ### facets Object Structure The facets object provides information about different fields that can be used for filtering: * type: Indicates the type of facet ("list" or "range"). * values: * For "list" type: An array of arrays, where each inner array contains the facet value and its count. * For "range" type: An object with min and max properties indicating the available range. ## Example Request and Response ### Request ```http GET https://search-api.abtasty.com/search ?index={identifier}_Catalog &text=toy &filters[brand][]=lego &filters[brand][]=playmobil &filters[price][0][operator]=%3E &filters[price][0][value]=10 &filters[price][1][operator]=%3C &filters[price][1][value]=20 &filters[color][]=red &filters[color][]=blue &filters[rating][0][operator]=%3E%3D &filters[rating][0][value]=4 &page=0 &hitsPerPage=20 &rankingScoreThreshold=0.1 &semanticRatio=0.1 &sort=price:desc ``` ### Response ```json { "hits": [ { "id": "126455", "img_link": "/103446.jpg", "link": "/starWarsLego", "name": "Star wars lego", "price": 120 }, { "id": "126456", "img_link": "/103447.jpg", "link": "/playmobilCastle", "name": "Playmobil Castle", "price": 45.0 }, { "id": "126457", "img_link": "/103448.jpg", "link": "/barbieDreamhouse", "name": "Barbie Dreamhouse", "price": 5.9 } ], "facets": { "brand": { "type": "list", "values": [["lego", 10], ["playmobil", 5]] }, "category": { "type": "list", "values": [["toys", 15], ["games", 8]] }, "price": { "type": "range", "values": { "min": 5, "max": 100 } } }, "totalPages": 20, "totalHits": 1000, "hitsPerPage": 50, "page": 1 } ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.abtasty.com/commerce/search/api/search-api-v0.4.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.