post
https://{yourinstance}.makaira.io/search/
The search endpoint is the heart of the Makaira Marketing Suite when it comes to searching for products in a classic shop scenario.
It is used for your autosuggest and search results as well as for listing products on category or manufacturer pages.
Executes a search request and returns ranked results across products, categories, manufacturers, and suggestions. Authenticate with HMAC using an API key that includes search permissions, or with a Bearer JWT.
Request
POST /search/
Headers
| Header | Value |
|---|---|
Authorization | Bearer <token> |
Content-Type | application/json |
X-Makaira-Instance | Your Makaira instance identifier |
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
isSearch | boolean | Yes | Set to true for full-text search (e.g. autosuggest), false for listing pages (e.g. category or manufacturer pages). |
searchPhrase | string | Yes | The search term entered by the user. Use an empty string for listing-page requests. |
enableAggregations | boolean | Yes | Set to true to include filter aggregations in the response. |
aggregations | object | Yes | Active filter selections. Pass an empty object or array when no filters are applied. |
sorting | object | Yes | Sorting configuration. Pass an empty object or array to use the default relevance sort. Example: {"price": "asc"}. |
count | integer | Yes | Number of items to return per page. |
offset | integer | Yes | Pagination offset (0-based). |
constraints | object | Yes | Query constraints. See table below. |
fields | array | No | List of document fields to include in the response. An empty array returns all available fields. |
apiVersion | string | No | API version string (e.g. 2018.6). |
enableHook | boolean | No | Set to false to bypass any configured search query hooks. Defaults to true. |
Constraints
| Constraint | Type | Required | Description |
|---|---|---|---|
query.shop_id | string | Yes | Filters results to a specific shop. Only relevant in multi-shop setups. |
query.language | string | Yes | Language identifier for the search index (e.g. de, en). |
query.use_stock | string | No | When set to "true", excludes out-of-stock products. |
query.variant_count | integer | No | Maximum number of variants to return per product. Must be an integer ≥ 1. Values exceeding the server-configured maximum are clamped to that maximum. Omitting this field returns up to the server-configured maximum. Invalid values (non-integer, zero, or negative) return a 400 Bad Request error. |
query.variant_sorting | object | No | Sort variants within each product group by a specific field. Example: {"price": "asc"}. |
query.use_child_attribute_sorting | boolean | No | When true, sorts product groups by the aggregated value of a specific variant attribute. Use together with query.attribute_id, query.attribute_type, query.attribute_sort_order, and query.attribute_aggregation_mode. |
query.attribute_id | string | No | The ID of the attribute to sort by. Required when query.use_child_attribute_sorting is true. |
query.attribute_type | string | No | The attribute type (e.g. attributeInt, attributeStr, attributeFloat). Required when query.use_child_attribute_sorting is true. |
query.attribute_sort_order | string | No | Sort direction: asc or desc. Defaults to desc. Used with query.use_child_attribute_sorting. |
query.attribute_aggregation_mode | string | No | Aggregation mode across variant values: max, min, avg, or sum. Defaults to max. Used with query.use_child_attribute_sorting. |
oi.user.agent | string | No | User agent string. Required for personalization. |
oi.user.ip | string | No | User IP address. Required for personalization. |
Example Request
{
"searchPhrase": "kite",
"constraints": {
"query.shop_id": 1,
"query.language": "de",
"query.use_stock": true
},
"enableAggregations": true,
"isSearch": true,
"aggregations": [],
"sorting": [],
"fields": ["title"],
"count": 50,
"offset": 0,
"apiVersion": "2018.6"
}Example Request — Attribute-based variant sorting
Sorts product groups by the minimum price of their variants:
{
"searchPhrase": "jacket",
"constraints": {
"query.shop_id": 1,
"query.language": "de",
"query.use_child_attribute_sorting": true,
"query.attribute_id": "attribute-price-id",
"query.attribute_type": "attributeFloat",
"query.attribute_sort_order": "asc",
"query.attribute_aggregation_mode": "min"
},
"enableAggregations": true,
"isSearch": true,
"aggregations": [],
"sorting": [],
"count": 50,
"offset": 0
}Response
Returns a JSON object containing result buckets for each document type.
Response Body
| Field | Type | Description |
|---|---|---|
product | object | Product search results. Contains items, count, total, and aggregations. |
category | object | Category results. Contains items, count, and total. |
manufacturer | object | Manufacturer results. Contains items, count, and total. |
suggestion | object | Autosuggest results. Contains items, count, and total. |
Each result bucket item has:
| Field | Type | Description |
|---|---|---|
id | string | Document ID. |
fields | object | Document fields as requested. |