post
https://{yourinstance}.makaira.io/search/public
This endpoint acts basically the same as the /search/ endpoint. The only difference is that the public endpoint does not require HMAC with an API key.
That means, they are publicly available. Because of that, we limit the fields returned in the responses. To achieve this, customers can define a whitelist of fields that should be returned.
Executes a search request without HMAC or an API key. Suitable for use directly from storefronts. Response fields are limited to those whitelisted in the Makaira admin under Public Fields.
Request
POST /search/public
Headers
| Header | Value |
|---|---|
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. 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 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. |
apiVersion | string | No | API version string (e.g. 2018.6). |
enableHook | boolean | No | Set to false to bypass 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": [],
"count": 50,
"offset": 0,
"apiVersion": "2018.6"
}Example Request — Variant sorting by price
Returns products with their variants sorted by price ascending:
{
"searchPhrase": "kite",
"constraints": {
"query.shop_id": 1,
"query.language": "de",
"query.variant_sorting": {
"price": "asc"
}
},
"enableAggregations": true,
"isSearch": true,
"aggregations": [],
"sorting": [],
"count": 50,
"offset": 0
}Example Request — Attribute-based product group sorting
Sorts product groups by the minimum price of their variants using attribute-based sorting:
{
"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 with result buckets for each document type. Only fields whitelisted in the Makaira admin under Public Fields are included.
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 allowed by the Public Fields whitelist. |