--- updatedAt: 2026-09-07T08:15:07.000Z agentTools: projectIndex: https://docs.makaira.io/llms.txt --- # 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 ` | | `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 ```json { "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: ```json { "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. | # OpenAPI definition ```json { "openapi": "3.0.0", "info": { "title": "Makaira API", "version": "1.0", "contact": { "name": "Makaira GmbH", "url": "https://www.makaira.io/", "email": "support@makaira.io" }, "description": "API of the powerful Makaira Search/Recommendation and Marketing Suite" }, "servers": [ { "url": "https://{yourinstance}.makaira.io" } ], "paths": { "/search/": { "post": { "tags": [ "Search" ], "summary": "", "operationId": "post-search", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "suggestion": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "fields": { "type": "object" } } } }, "count": { "type": "string" }, "total": { "type": "string" } } }, "product": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "fields": { "type": "object" } } } }, "count": { "type": "string" }, "total": { "type": "string" }, "aggregations": { "type": "string" } } }, "manufacturer": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "fields": { "type": "object" } } } }, "count": { "type": "string" }, "total": { "type": "string" } } }, "category": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "fields": { "type": "object" } } } }, "count": { "type": "string" }, "total": { "type": "string" } } } } }, "examples": { "Kite search response": { "value": { "suggestion": { "items": null, "count": null, "total": null, "offset": null, "aggregations": null, "additionalData": [] }, "product": { "items": [ { "id": "b5666b6d4bcb67c61dee4887bfba8351", "fields": { "id": "b5666b6d4bcb67c61dee4887bfba8351", "title": "Kite CORE RIOT XR", "makaira-product": { "id": "6ef1a1ea3b12a39f187bf7e21d84e7cc", "title": "Kite CORE RIOT XR" } } }, { "id": "fadc492a5807c56eb80b0507accd756b", "fields": { "id": "fadc492a5807c56eb80b0507accd756b", "title": "Kite SPLEENE SP-X 2010", "makaira-product": { "id": "f930dfead26215afd74d87ffbeccf03b", "title": "Kite SPLEENE SP-X 2010" } } }, { "id": "f4f0cb3606e231c3fdb34fcaee2d6d04", "fields": { "id": "f4f0cb3606e231c3fdb34fcaee2d6d04", "title": "Kite LIQUID FORCE ENVY", "makaira-product": { "id": "b9908dbdf8b65d308ae34fc5c46dacec", "title": "Kite LIQUID FORCE ENVY" } } }, { "id": "b56369b1fc9d7b97f9c5fc343b349ece", "fields": { "id": "b56369b1fc9d7b97f9c5fc343b349ece", "title": "Kite CORE GTS", "makaira-product": { "id": "1ece7025b78c1cf3a7b0343e8799bed2", "title": "Kite CORE GTS" } } }, { "id": "b56764137ca959da9541bb28c1987d6c", "fields": { "id": "b56764137ca959da9541bb28c1987d6c", "title": "Kite NBK REBEL 2010", "makaira-product": { "id": "d7758412ad714f41194bb846b8c30e90", "title": "Kite NBK REBEL 2010" } } }, { "id": "fad21eb148918c8f4d9f0077fedff1ba", "fields": { "id": "fad21eb148918c8f4d9f0077fedff1ba", "title": "Kite LIQUID FORCE HAVOC", "makaira-product": { "id": "31f01c9dd47990376966259558008494", "title": "Kite LIQUID FORCE HAVOC" } } }, { "id": "dc57391739360d306c8dfcb3a4295e19", "fields": { "id": "dc57391739360d306c8dfcb3a4295e19", "title": "Kite RRD PASSION 2010", "makaira-product": { "id": "7238637b3badad2cb8ac3e56f14903da", "title": "Kite RRD PASSION 2010" } } }, { "id": "b56c560872da93602ff88c7267eb4774", "fields": { "id": "b56c560872da93602ff88c7267eb4774", "title": "Kite NAISH PARK 2011", "makaira-product": { "id": "2f5e1a75016e71f5264bad6d8b8bc879", "title": "Kite NAISH PARK 2011" } } }, { "id": "f4fe052346b4ec271011e25c052682c5", "fields": { "id": "f4fe052346b4ec271011e25c052682c5", "title": "Kite CORE GT", "makaira-product": { "id": "de413df92f2ce7183f0b113e1d5c7e7f", "title": "Kite CORE GT" } } }, { "id": "dc5b9cfeb5bd96fdbd9b4e43974661a1", "fields": { "id": "dc5b9cfeb5bd96fdbd9b4e43974661a1", "title": "Kite FLYSURFER SPEED3", "makaira-product": { "id": "9eed3ef4ddb63b4d32572362b0021118", "title": "Kite FLYSURFER SPEED3" } } }, { "id": "dc5480c47d8cd5a9eab9da5db9159cc6", "fields": { "id": "dc5480c47d8cd5a9eab9da5db9159cc6", "title": "Kite RRD PASSION 2009", "makaira-product": { "id": "724d89012c2f7018fe6bed7cafefebc9", "title": "Kite RRD PASSION 2009" } } }, { "id": "b56597806428de2f58b1c6c7d3e0e093", "fields": { "id": "b56597806428de2f58b1c6c7d3e0e093", "title": "Kite NBK EVO 2010", "makaira-product": { "id": "0ab13a94358b5aa96dc9fc73a781a01d", "title": "Kite NBK EVO 2010" } } }, { "id": "d86f775338da3228bec9e968f02e7551", "fields": { "id": "d86f775338da3228bec9e968f02e7551", "title": "Kite Leinen VECTOR QUAD PRO", "makaira-product": { "id": "e80f918712e13c1369ff2b55735313b5", "title": "Kite Leinen VECTOR QUAD PRO" } } }, { "id": "f4f2d8eee51b0fd5eb60a46dff1166d8", "fields": { "id": "f4f2d8eee51b0fd5eb60a46dff1166d8", "title": "Trapez ION SOL KITE 2011", "makaira-product": { "id": "78b536b91ea8bab0336e0a0b1c787c4b", "title": "Trapez ION SOL KITE 2011" } } }, { "id": "0584e8b766a4de2177f9ed11d1587f55", "fields": { "id": "0584e8b766a4de2177f9ed11d1587f55", "title": "Klebeband DACRON KITEFIX", "makaira-product": { "id": "05833e961f65616e55a2208c2ed7c6b8", "title": "Klebeband DACRON KITEFIX" } } }, { "id": "f33d5bcc7135908fd36fc736c643aa1c", "fields": { "id": "f33d5bcc7135908fd36fc736c643aa1c", "title": "KiteFix Kleber GLUFIX (30g)", "makaira-product": { "id": "8a7fcf6342e9f8cdc5412720cfeb0e10", "title": "KiteFix Kleber GLUFIX (30g)" } } }, { "id": "adc920f4cbfa739803058c663a4a00b9", "fields": { "id": "adc920f4cbfa739803058c663a4a00b9", "title": "Kiteboard FLYBOARDS FLYWAVE 2010", "makaira-product": { "id": "0bcd6a8f9a9f13464bab7c56c2b4b416", "title": "Kiteboard FLYBOARDS FLYWAVE 2010" } } }, { "id": "058de8224773a1d5fd54d523f0c823e0", "fields": { "id": "058de8224773a1d5fd54d523f0c823e0", "title": "Kiteboard CABRINHA CALIBER 2011", "makaira-product": { "id": "f4b019980cef07d381f44f435fa07f95", "title": "Kiteboard CABRINHA CALIBER 2011" } } }, { "id": "adcb9deae73557006a8ac748f45288b4", "fields": { "id": "adcb9deae73557006a8ac748f45288b4", "title": "Helm AHM 5000", "makaira-product": { "id": "913f71f3ecc4e2d1d2615985df8a47e4", "title": "Helm AHM 5000" } } }, { "id": "d862c91305fe0d5e86f82122ae9e367c", "fields": { "id": "d862c91305fe0d5e86f82122ae9e367c", "title": "Set O'BRIEN DECADE 2010", "makaira-product": { "id": "152f4c008aa1bda022d09158d4d5eb62", "title": "Set O'BRIEN DECADE 2010" } } }, { "id": "d866060a82d29bc94db20bdfd0e73713", "fields": { "id": "d866060a82d29bc94db20bdfd0e73713", "title": "Set O'BRIEN VICE 2010", "makaira-product": { "id": "2bed7b6b3d1c6108ae4d89570737e173", "title": "Set O'BRIEN VICE 2010" } } }, { "id": "d861ad687c60820255dbf8f88516f24d", "fields": { "id": "d861ad687c60820255dbf8f88516f24d", "title": "Pumpe CABRINHA INFLATION 2011", "makaira-product": { "id": "c03635f31997bac953f0d74c9bb5d2aa", "title": "Pumpe CABRINHA INFLATION 2011" } } }, { "id": "d8631f92ababb452139f222afb81cd36", "fields": { "id": "d8631f92ababb452139f222afb81cd36", "title": "Kiteboard NAISH MOMENTUM", "makaira-product": { "id": "a875a97e1aad4f48bd216ad87f4050cf", "title": "Kiteboard NAISH MOMENTUM" } } }, { "id": "f4fe754e1692b9f79f2a7b1a01bb8dee", "fields": { "id": "f4fe754e1692b9f79f2a7b1a01bb8dee", "title": "Kiteboard RRD TOXIC WAVE2", "makaira-product": { "id": "4011cf1f750d0564d6b0db248da32c9d", "title": "Kiteboard RRD TOXIC WAVE2" } } }, { "id": "ed6a2b0b90cab3f60a2dfd1c91fceb77", "fields": { "id": "ed6a2b0b90cab3f60a2dfd1c91fceb77", "title": "Neoprenschuh ION BALLISTIC SLIPPER 1.5", "makaira-product": { "id": "9014f4be3567b42a6e3d6799bb139874", "title": "Neoprenschuh ION BALLISTIC SLIPPER 1.5" } } } ], "count": 25, "total": 25, "offset": "0", "aggregations": { "price": { "title": "Price", "key": "price", "type": "range_slider_price", "values": null, "min": 7.99, "max": 1599, "selectedValues": null, "position": 10, "showDocCount": null }, "hersteller": { "title": "Hersteller", "key": "hersteller", "type": "list_multiselect", "values": { "Core Kiteboarding": { "key": "Core Kiteboarding", "count": 3 }, "RRD": { "key": "RRD", "count": 3 }, "Cabrinha": { "key": "Cabrinha", "count": 2 }, "ION": { "key": "ION", "count": 2 }, "Liquid Force": { "key": "Liquid Force", "count": 2 }, "Naish": { "key": "Naish", "count": 2 }, "Flyboards": { "key": "Flyboards", "count": 1 }, "Flysurfer": { "key": "Flysurfer", "count": 1 }, "Spleene": { "key": "Spleene", "count": 1 } }, "min": null, "max": null, "selectedValues": null, "position": 30, "showDocCount": true }, "delivery": { "title": "Lieferumfang", "key": "delivery", "type": "list_multiselect", "values": { "Kite, Backpack, Reparaturset": { "key": "Kite, Backpack, Reparaturset", "count": 3 }, "Kite, Tasche, Reparaturset": { "key": "Kite, Tasche, Reparaturset", "count": 3 }, "Kite, Tasche": { "key": "Kite, Tasche", "count": 2 }, "Kite, Tasche, CPR Control System, Pumpe": { "key": "Kite, Tasche, CPR Control System, Pumpe", "count": 2 }, "Kite": { "key": "Kite", "count": 1 }, "Kite, Global Bar, Tasche, Pumpe": { "key": "Kite, Global Bar, Tasche, Pumpe", "count": 1 } }, "min": null, "max": null, "selectedValues": null, "position": 40, "showDocCount": false }, "stock": { "title": "sofort lieferbar", "key": "stock", "type": "script", "values": { "true": { "key": "true", "count": 21 } }, "min": null, "max": null, "selectedValues": null, "position": 90, "showDocCount": false }, "sale": { "title": "Sale", "key": "sale", "type": "script", "values": { "true": { "key": "true", "count": 11 } }, "min": null, "max": null, "selectedValues": null, "position": 999, "showDocCount": false } }, "additionalData": [] }, "manufacturer": { "items": [ { "id": "adc566c366db8eaf30c6c124a09e82b3", "fields": { "manufacturer_title": "Core Kiteboarding", "id": "adc566c366db8eaf30c6c124a09e82b3" } } ], "count": 1, "total": 1, "offset": 0, "aggregations": [], "additionalData": [] }, "category": { "items": [ { "id": "943a9ba3050e78b443c16e043ae60ef3", "fields": { "category_title": "Kiteboarding", "id": "943a9ba3050e78b443c16e043ae60ef3" } }, { "id": "0f4fb00809cec9aa0910aa9c8fe36751", "fields": { "category_title": "Kites", "id": "0f4fb00809cec9aa0910aa9c8fe36751" } }, { "id": "0f4f08358666c54b4fde3d83d2b7ef04", "fields": { "category_title": "Kiteboards", "id": "0f4f08358666c54b4fde3d83d2b7ef04" } } ], "count": 3, "total": 3, "offset": 0, "aggregations": [], "additionalData": [] } } } } } } } }, "description": "The search endpoint is the heart of the Makaira Marketing Suite when it comes to searching for products in a classic shop scenario.\nIt is used for your autosuggest and search results as well as for listing products on category or manufacturer pages.", "parameters": [ { "$ref": "#/components/parameters/instance" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "isSearch": { "type": "boolean", "description": "Set this to true when the request is an actual search request (e.g. autosuggest) and to false when you want to perform a request for products on a category or manufacturer page." }, "searchPhrase": { "type": "string", "description": "The term to search for." }, "enableAggregations": { "type": "boolean", "description": "Set this to true when you want aggregations to be included in the response, otherwhise false." }, "aggregations": { "type": "object", "description": "List of selected values to filter for." }, "sorting": { "type": "object" }, "fields": { "type": "array", "description": "List of additional fields to be included in the response. When the value is an empty array, the response will include all available fields for each item.", "items": {} }, "count": { "type": "string", "description": "Number of products to be returned in the response." }, "offset": { "type": "string", "description": "The offset to start returning products from. In combination with the \"count\" property this is used for paginating the search results." }, "constraints": { "type": "object", "required": [ "query.shop_id", "query.language" ], "properties": { "query.shop_id": { "type": "string", "description": "This constraints acts as an implicit filter and only returns products that belong to the given Shop-ID. Only relevant if you have multiple shops." }, "query.language": { "type": "string", "description": "The language constraints tells Makaira in what language to search and return data for." }, "query.use_stock": { "type": "string" }, "oi.user.agent": { "type": "string", "description": "The user agent is only relevant if you use the personalization module of Makaira." }, "oi.user.ip": { "type": "string", "description": "The ip address is only relevant if you use the personalization module of Makaira." }, "query.variant_sorting": { "type": "object", "description": "Sort variants within each product group by a specific field. Example: `{\"price\": \"asc\"}` sorts variants by price ascending." }, "query.use_child_attribute_sorting": { "type": "boolean", "description": "When set to `true`, sorts product groups by the value of a specific attribute on their variants. Use together with `query.attribute_id`, `query.attribute_type`, `query.attribute_aggregation_mode`, and `query.attribute_sort_order`." }, "query.attribute_id": { "type": "string", "description": "The ID of the attribute to sort by. Required when `query.use_child_attribute_sorting` is `true`." }, "query.attribute_type": { "type": "string", "description": "The attribute type (e.g. `attributeInt`, `attributeStr`, `attributeFloat`). Required when `query.use_child_attribute_sorting` is `true`." }, "query.attribute_sort_order": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort direction for the attribute. Defaults to `desc`. Used with `query.use_child_attribute_sorting`." }, "query.attribute_aggregation_mode": { "type": "string", "enum": [ "max", "min", "avg", "sum" ], "description": "Aggregation mode used to compute a single score from multiple variant attribute values. Defaults to `max`. Used with `query.use_child_attribute_sorting`." } } }, "apiVersion": { "type": "string" }, "enableHook": { "description": "If set to false, the search query hook will be disabled. Default value is true(if not specify)", "type": "boolean" } }, "required": [ "isSearch", "searchPhrase", "enableAggregations", "aggregations", "sorting", "count", "offset", "constraints" ] }, "examples": { "Kite search request": { "value": { "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" } } } } }, "description": "" } } } }, "components": { "parameters": { "instance": { "in": "header", "name": "X-Makaira-Instance", "required": true, "description": "Makaira Instance ID", "schema": { "type": "string" } } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Authentication by JSON Web Token\n" } } }, "security": [ { "bearerAuth": [] } ], "x-readme": { "explorer-enabled": true, "proxy-enabled": true } } ```